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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
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.rbnew file mode 100644index 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+enddiff --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.rbnew file mode 100644index 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+enddiff --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.rbnew file mode 100644index 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+enddiff --git a/spree/api/spec/integration/spree/api/v3/admin/companies_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/companies_spec.rbindex 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-referencproduces '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, :customersparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true@@ -36,7 +36,7 @@ RSpec.describe 'Admin Companies API', type: :request, swagger_doc: 'api-referencproduces '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, :customersparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: truediff --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.rbnew file mode 100644index 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