Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Document the whole company surface, not just the top of it

Łukasz Adamczyk4ee23e477219
diff --git a/spree/api/spec/integration/spree/api/v3/admin/companies/locations_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/companies/locations_spec.rb
new file mode 100644
index 0000000000..74232b1d25
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/companies/locations_spec.rb
@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Company Locations API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+ let!(:company) { create(:company, store: store, name: 'Acme Industrial') }
+ let!(:location) { create(:company_location, company: company, name: 'Berlin') }
+ let(:germany) { create(:country, iso: 'DE', name: 'Germany') }
+
+ path '/api/v3/admin/companies/{company_id}/locations' do
+ let(:company_id) { company.prefixed_id }
+
+ get 'List company locations' do
+ tags 'Companies'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns the branches of a business customer. Each branch owns its own addresses and the buyers authorised to purchase for it.'
+ admin_scope :read, :customers
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :company_id, in: :path, type: :string, required: true
+
+ response '200', 'locations found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].pluck('id')).to include(location.prefixed_id)
+ end
+ end
+ end
+
+ post 'Create a company location' do
+ tags 'Companies'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Creates a branch. Addresses are supplied inline and belong to the branch, so editing one later changes the branch\'s own record rather than an address the buyer also uses.'
+ admin_scope :write, :customers
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :company_id, in: :path, type: :string, required: true
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ name: { type: :string, example: 'Hamburg warehouse' },
+ external_id: { type: :string, nullable: true, example: 'HAM-01' },
+ billing_address: {
+ type: :object,
+ description: 'Created inline and owned by the branch.',
+ properties: {
+ first_name: { type: :string }, last_name: { type: :string },
+ address1: { type: :string }, city: { type: :string },
+ postal_code: { type: :string }, country_iso: { type: :string, example: 'DE' }
+ }
+ }
+ },
+ required: ['name']
+ }
+
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ response '201', 'location created' do
+ let(:body) do
+ {
+ name: 'Hamburg warehouse',
+ billing_address: {
+ first_name: 'Anna', last_name: 'Muller', address1: 'Hafenstr 1',
+ city: 'Hamburg', postal_code: '20095', country_iso: germany.iso
+ }
+ }
+ end
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['name']).to eq('Hamburg warehouse')
+ end
+ end
+
+ response '422', 'invalid request' do
+ let(:body) { { external_id: 'NO-NAME' } }
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/admin/company_locations/{id}' do
+ let(:id) { location.prefixed_id }
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+
+ get 'Get a company location' do
+ tags 'Companies'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Branches are addressed by their own id once you hold one — the company id is not needed.'
+ admin_scope :read, :customers
+
+ response '200', 'location found' do
+ run_test! do |response|
+ expect(JSON.parse(response.body)['name']).to eq('Berlin')
+ end
+ end
+ end
+
+ patch 'Update a company location' do
+ tags 'Companies'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Address fields sent here edit the branch\'s existing address in place; send only what changes.'
+ admin_scope :write, :customers
+
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ name: { type: :string, example: 'Berlin Mitte' },
+ billing_address: { type: :object, properties: { city: { type: :string } } }
+ }
+ }
+
+ response '200', 'location updated' do
+ let(:body) { { name: 'Berlin Mitte' } }
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['name']).to eq('Berlin Mitte')
+ end
+ end
+ end
+
+ delete 'Delete a company location' do
+ tags 'Companies'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Removes the branch, its buyers and the addresses it owned.'
+ admin_scope :write, :customers
+
+ response '204', 'location deleted' do
+ run_test!
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/companies/tax_exemption_certificates_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/companies/tax_exemption_certificates_spec.rb
new file mode 100644
index 0000000000..30174b58c6
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/companies/tax_exemption_certificates_spec.rb
@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Tax Exemption Certificates API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+ let!(:company) { create(:company, store: store) }
+ let(:germany) { create(:country, iso: 'DE', name: 'Germany') }
+ let!(:certificate) do
+ create(:tax_exemption_certificate, company: company,
+ certificate_number: 'DE-RESALE-1', reason_code: 'resale')
+ end
+
+ def pdf_blob
+ ActiveStorage::Blob.create_and_upload!(
+ io: StringIO.new('%PDF-1.4 certificate'),
+ filename: 'resale.pdf',
+ content_type: 'application/pdf'
+ )
+ end
+
+ path '/api/v3/admin/companies/{company_id}/tax_exemption_certificates' do
+ let(:company_id) { company.prefixed_id }
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :company_id, in: :path, type: :string, required: true
+
+ get 'List tax exemption certificates' do
+ tags 'Companies'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Returns a business's exemption evidence. `active` is the field that decides whether a certificate
+ exempts a sale: a verified certificate stops counting once its expiry date passes, so the status
+ alone does not answer it.
+ DESC
+ admin_scope :read, :customers
+
+ response '200', 'certificates found' do
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].pluck('certificate_number')).to include('DE-RESALE-1')
+ end
+ end
+ end
+
+ post 'Create a tax exemption certificate' do
+ tags 'Companies'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Records exemption evidence against a business. Certificates start `pending` and exempt nothing
+ until verified.
+
+ `country_iso` and `state_code` say where the certificate holds — omit both for one valid
+ everywhere, give only the country for one valid throughout it. `document` takes an ActiveStorage
+ signed blob id obtained from `POST /api/v3/admin/direct_uploads`.
+ DESC
+ admin_scope :write, :customers
+
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ certificate_number: { type: :string, example: 'DE-RESALE-7' },
+ reason_code: { type: :string, description: 'Becomes the tax provider\'s entity use code.', example: 'resale' },
+ country_iso: { type: :string, nullable: true, example: 'DE' },
+ state_code: { type: :string, nullable: true, example: 'BE' },
+ expires_at: { type: :string, format: 'date-time', nullable: true },
+ issuing_authority: { type: :string, nullable: true, example: 'Finanzamt Berlin' },
+ document: {
+ type: :string,
+ description: 'ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads.',
+ example: 'eyJfcmFpbHMiOnsiZGF0YSI6MX0=--signed'
+ }
+ },
+ required: %w[certificate_number reason_code]
+ }
+
+ response '201', 'certificate created' do
+ let(:body) do
+ {
+ certificate_number: 'DE-RESALE-7',
+ reason_code: 'resale',
+ country_iso: germany.iso,
+ document: pdf_blob.signed_id
+ }
+ end
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['status']).to eq('pending')
+ expect(data['document_filename']).to eq('resale.pdf')
+ end
+ end
+
+ response '422', 'invalid request' do
+ let(:body) { { reason_code: 'resale' } }
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/verify' do
+ let(:company_id) { company.prefixed_id }
+ let(:id) { certificate.prefixed_id }
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :company_id, in: :path, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+
+ patch 'Verify a tax exemption certificate' do
+ tags 'Companies'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Accepts the certificate as evidence, which is what makes it exempt sales. Only a pending
+ certificate can be accepted — re-accepting a revoked one would restore evidence that was
+ deliberately withdrawn. An installation that checks numbers against a registry, or requires a
+ second approval, can refuse here, and the refusal is returned as a validation error.
+ DESC
+ admin_scope :write, :customers
+
+ response '200', 'certificate verified' do
+ run_test! do |response|
+ expect(JSON.parse(response.body)['status']).to eq('verified')
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/revoke' do
+ let(:company_id) { company.prefixed_id }
+ let(:id) { create(:tax_exemption_certificate, :verified, company: company).prefixed_id }
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :company_id, in: :path, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+
+ patch 'Revoke a tax exemption certificate' do
+ tags 'Companies'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Withdraws accepted evidence. A verified certificate cannot be deleted — how a sale was taxed has to remain explainable — so revoking is the way out.'
+ admin_scope :write, :customers
+
+ response '200', 'certificate revoked' do
+ run_test! do |response|
+ expect(JSON.parse(response.body)['status']).to eq('revoked')
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/download' do
+ let(:company_id) { company.prefixed_id }
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :company_id, in: :path, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+
+ get 'Download a certificate document' do
+ tags 'Companies'
+ produces 'application/octet-stream'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Streams the uploaded document. Deliberately not a storage link: the bytes come through the API so
+ the same credentials apply to every read of a confidential document. Requires only read access.
+ DESC
+ admin_scope :read, :customers
+
+ response '200', 'document streamed' do
+ let(:id) do
+ create(:tax_exemption_certificate, company: company).tap do |record|
+ record.document.attach(pdf_blob.signed_id)
+ end.prefixed_id
+ end
+
+ run_test!
+ end
+
+ response '422', 'no document attached' do
+ let(:id) { certificate.prefixed_id }
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/companies/tax_identifiers_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/companies/tax_identifiers_spec.rb
new file mode 100644
index 0000000000..19e9b22c5d
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/companies/tax_identifiers_spec.rb
@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Company Tax Identifiers API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+ let!(:company) { create(:company, store: store) }
+ let!(:tax_identifier) do
+ create(:tax_identifier, customer: nil, company: company, kind: 'eu_vat', value: 'DE123456789')
+ end
+
+ path '/api/v3/admin/companies/{company_id}/tax_identifiers' do
+ let(:company_id) { company.prefixed_id }
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :company_id, in: :path, type: :string, required: true
+
+ get 'List company tax registrations' do
+ tags 'Companies'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Returns the business's tax registrations, one per kind. A business registration takes precedence
+ over the buyer's own when a sale is for that business, because the invoice is addressed to the
+ entity rather than the person who placed the order.
+ DESC
+ admin_scope :read, :customers
+
+ response '200', 'registrations found' do
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].pluck('value')).to include('DE123456789')
+ end
+ end
+ end
+
+ post 'Create a company tax registration' do
+ tags 'Companies'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Registers a tax number against the business. Verification against the relevant registry runs in
+ the background where a validator is installed for the kind; a stock installation registers none,
+ leaving the status unattempted.
+ DESC
+ admin_scope :write, :customers
+
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ kind: { type: :string, description: 'The regime the number belongs to.', example: 'gb_vat' },
+ value: { type: :string, example: 'GB123456789' }
+ },
+ required: %w[kind value]
+ }
+
+ response '201', 'registration created' do
+ let(:body) { { kind: 'gb_vat', value: 'GB123456789' } }
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['value']).to eq('GB123456789')
+ end
+ end
+
+ response '422', 'invalid request' do
+ # One registration per kind.
+ let(:body) { { kind: 'eu_vat', value: 'DE999999999' } }
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/admin/companies/{company_id}/tax_identifiers/{id}/validate' do
+ let(:company_id) { company.prefixed_id }
+ let(:id) { tax_identifier.prefixed_id }
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :company_id, in: :path, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+
+ post 'Re-check a company tax registration' do
+ tags 'Companies'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Asks the registry again. Manual because a registry answers only "valid now" — a number verified
+ last year may have been deregistered since — and because a check that came back unavailable
+ cannot otherwise be retried without editing the number.
+ DESC
+ admin_scope :write, :customers
+
+ response '422', 'no validator installed for this kind' do
+ run_test! do |response|
+ expect(JSON.parse(response.body)['error']['code']).to eq('tax_id_not_validatable')
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/companies_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/companies_spec.rb
index 647b60455f..e4ed3026fd 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/companies_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/companies_spec.rb
@@ -15,7 +15,7 @@ RSpec.describe 'Admin Companies API', type: :request, swagger_doc: 'api-referenc
produces 'application/json'
security [api_key: [], bearer_auth: []]
description 'Returns the business customers of the current store.'
- admin_scope_note '`read_customers` — a company is a customer record.'
+ admin_scope :read, :customers
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
@@ -36,7 +36,7 @@ RSpec.describe 'Admin Companies API', type: :request, swagger_doc: 'api-referenc
produces 'application/json'
security [api_key: [], bearer_auth: []]
description 'Creates a business customer. Exemption certificates and tax registrations hang off it.'
- admin_scope_note '`write_customers`.'
+ admin_scope :write, :customers
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
diff --git a/spree/api/spec/integration/spree/api/v3/admin/company_locations/contacts_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/company_locations/contacts_spec.rb
new file mode 100644
index 0000000000..3af1e89336
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/company_locations/contacts_spec.rb
@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Company Contacts API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+ let!(:company) { create(:company, store: store) }
+ let!(:location) { create(:company_location, company: company, name: 'Berlin') }
+ let!(:customer) { create(:customer, email: '[email protected]') }
+ let!(:contact) { create(:company_contact, company_location: location, customer: customer) }
+
+ path '/api/v3/admin/company_locations/{company_location_id}/contacts' do
+ let(:company_location_id) { location.prefixed_id }
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :company_location_id, in: :path, type: :string, required: true
+
+ get 'List company contacts' do
+ tags 'Companies'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns the customers authorised to purchase for a branch. A customer may act for more than one branch.'
+ admin_scope :read, :customers
+
+ response '200', 'contacts found' do
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].pluck('id')).to include(contact.prefixed_id)
+ end
+ end
+ end
+
+ post 'Create a company contact' do
+ tags 'Companies'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Authorises a customer to purchase for a branch. A customer who acts for exactly one branch has
+ their orders attributed to it automatically; one who acts for several needs the branch set on
+ the order, because guessing would invoice the wrong business.
+ DESC
+ admin_scope :write, :customers
+
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ customer_id: { type: :string, example: 'cus_UkLWZg9DAJ' },
+ role: { type: :string, description: 'Free-form label; carries no permissions in 6.0.', example: 'buyer' }
+ },
+ required: ['customer_id']
+ }
+
+ response '201', 'contact created' do
+ let(:body) { { customer_id: create(:customer).prefixed_id, role: 'admin' } }
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['role']).to eq('admin')
+ end
+ end
+
+ response '422', 'invalid request' do
+ # The same customer cannot be added to one branch twice.
+ let(:body) { { customer_id: customer.prefixed_id } }
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/admin/company_contacts/{id}' do
+ let(:id) { contact.prefixed_id }
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+
+ get 'Get a company contact' do
+ tags 'Companies'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ admin_scope :read, :customers
+
+ response '200', 'contact found' do
+ run_test! do |response|
+ expect(JSON.parse(response.body)['email']).to eq('[email protected]')
+ end
+ end
+ end
+
+ delete 'Delete a company contact' do
+ tags 'Companies'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Withdraws the customer\'s authority to purchase for the branch. The customer account itself is untouched.'
+ admin_scope :write, :customers
+
+ response '204', 'contact deleted' do
+ run_test!
+ end
+ end
+ end
+end