v2025-10-13

This is the first major release of B2Brouter API. It includes significant improvements and changes to make the API consistent, RESTful, and easier to work with.

Now there’s an option to select the API Version to use in each request. The X-B2B-API-Version header parameter allows specifying the desired version for the request. If the API Version is not specified in the request, it will be defined by the group configuration related to the API Key used in the request.

This version implements breaking changes. Each breaking change is marked with the tag Breaking.

Key Changes Summary

API Infrastructure

• New Domain: API access moved from app.b2brouter.net to api.b2brouter.net
• Version Header: New X-B2B-API-Version header for explicit version control
• JSON Only: XML format support removed; all responses now JSON by default
• Response Language: All API responses now default to English regardless of account configuration

Path Structure Modernization

• Resource Naming: /projects renamed to /accounts, /clients renamed to /contacts
• Clean URLs: Removed .{format} extensions from all endpoints
• Simplified Hierarchy: Removed /users prefix from code lists, /api/v1 prefix from directory and tax report endpoints
• Standardized Pagination: All list responses now use consistent meta object for pagination data

Schema Standardization

• Terminology Consistency: Unified client → contact throughout the API
• Structured Identifiers: Tax codes split into tin_scheme and tin_value for better structure
• English Naming: Spanish, Catalan, and Italian field names standardized to English equivalents
• Nested Structures: Bank account fields moved to nested objects for better organization
• Deprecated Fields Removed: Cleaned up legacy attributes in favor of standardized alternatives

Response Improvements

• Full Representations: PUT, DELETE, and POST operations now return complete resource representations instead of 204 No Content
• Consistent Errors: Standardized error responses with 409 Conflict for business rule violations
• Simplified References: Removed nested project objects from invoice responses

Tax Reports API Overhaul

The deprecated Tax Reports API has been removed in order to promote the use of a new, more generic and RESTful Tax Reports API suitable for most use cases.

All endpoints that were marked as [Deprecated] in version 2025-01-01 (Legacy) have been removed. The endpoints that were marked as [New Tax Report API] in version 2025-01-01 now become the only way to manage Tax Reporting via API. The /api/v1 prefix has been removed from the path of those endpoints.

---

Added

New API Version Header

Added X-B2B-API-Version header parameter to specify the API version per request. If not specified, defaults to the version configured in the group’s API Key settings.

New Tax Reports Endpoints

• POST /accounts/{account}/tax_reports - Create a Tax Report
• POST /accounts/{account}/tax_reports/import - Import a Tax Report from XML file
• GET /tax_reports/{id} - Get a tax report
• PATCH /tax_reports/{id} - Correct or Modify a Tax Report
• DELETE /tax_reports/{id} - Annulate a tax report
• GET /tax_reports/{id}/download - Download a tax report in Tax Authority format

New Ledgers Endpoints

• GET /ledgers/{id}/download - Download a Ledger XML document
• GET /ledgers/{id}/download_response - Download the Tax Authority response for a Ledger
• POST /accounts/{account}/ledgers/import - Import a ledger from XML payload

New Validation Endpoint

• POST /documents/validate - Validates electronic documents (UBL, CII, Peppol BIS, PINT, ZUGFeRD, XRechnung, Factur-X, FacturaE, Svefaktura, Fattura PA, eSPap, and any EN16931 CIUS-compliant format)

New Transport Endpoint

• DELETE /accounts/{account}/transports/{code} - Delete a transport configuration

Standardized Pagination

All listing endpoints now return pagination metadata in a consistent meta object containing total_count, offset, and limit.

Consolidated Invoice Listing

Added type query parameter to /accounts/{account}/invoices endpoint to filter by invoice type (IssuedInvoice, ReceivedInvoice, IssuedSelfInvoice, IssuedSimplifiedInvoice).

Full Resource Responses

Changed PUT, POST, and DELETE operations to return complete resource representations:

• PUT /accounts/{account} - Now returns full account representation
• DELETE /accounts/{account} - Now returns full account representation with deletion status
• POST /accounts/{account}/unarchive - Now returns full account representation
• POST /accounts/{account}/logo - Now returns full account representation
• DELETE /accounts/{account}/logo - Now returns full account representation
• PUT /bank_accounts/{id} - Now returns full bank account representation
• DELETE /bank_accounts/{id} - Now returns full bank account representation
• PUT /contacts/{id} - Now returns full contact representation
• DELETE /contacts/{id} - Now returns full contact representation
• PUT /invoices/{id} - Now returns full invoice representation
• DELETE /invoices/{id} - Now returns full invoice representation
• POST /invoices/{id}/mark_as - Now returns full invoice representation
• POST /invoices/{id}/ack - Now returns full invoice representation

---

Changed

🚨 Breaking

Response Language

All API responses now default to English regardless of account configuration.

Previous behavior:

• API responses inherited the language from the account’s default language setting

New behavior:

• All API responses default to English

API Domain Change

API base URL changed from app.b2brouter.net to api.b2brouter.net

• Old: https://app.b2brouter.net/api/...
• New: https://api.b2brouter.net/...

Resource Path Renaming

All endpoints that contained /projects/{account} have been renamed to /accounts/{account}:

• GET /projects/{account}/contacts → GET /accounts/{account}/contacts
• POST /projects/{account}/contacts → POST /accounts/{account}/contacts
• GET /projects/{account}/events → GET /accounts/{account}/events
• GET /projects/{account}/invoices → GET /accounts/{account}/invoices
• POST /projects/{account}/invoices → POST /accounts/{account}/invoices
• GET /projects/{account}/orders → GET /accounts/{account}/orders
• POST /projects/{account}/orders → POST /accounts/{account}/orders
• POST /projects/{account}/despatch_advices → POST /accounts/{account}/despatch_advices
• And all other project-scoped endpoints

All endpoints referencing /clients have been renamed to /contacts:

• GET /clients/{id} → GET /contacts/{id}
• PUT /clients/{id} → PUT /contacts/{id}
• DELETE /clients/{id} → DELETE /contacts/{id}

Format Extension Removal

Removed .{format} path extensions from all endpoints. JSON is now the only supported format and is set as default:

• GET /invoices/{id}.{format} → GET /invoices/{id}
• PUT /invoices/{id}.{format} → PUT /invoices/{id}
• DELETE /invoices/{id}.{format} → DELETE /invoices/{id}
• POST /invoices/{id}/mark_as.{format} → POST /invoices/{id}/mark_as
• POST /invoices/{id}/add_attachment.{format} → POST /invoices/{id}/add_attachment
• POST /invoices/{id}/add_attachments.{format} → POST /invoices/{id}/add_attachments
• POST /invoices/{id}/generate_tax_report.{format} → POST /invoices/{id}/generate_tax_report
• POST /invoices/{id}/ack.{format} → POST /invoices/{id}/ack
• GET /orders/{id}.{format} → GET /orders/{id}
• POST /orders/{id}/mark_as.{format} → POST /orders/{id}/mark_as
• GET /clients/{id}.{format} → GET /contacts/{id}
• PUT /clients/{id}.{format} → PUT /contacts/{id}
• DELETE /clients/{id}.{format} → DELETE /contacts/{id}
• And all code list endpoints

Code Lists Path Simplification

Removed /users prefix from all code list endpoints:

• GET /users/countries → GET /countries
• GET /users/currencies → GET /currencies
• GET /users/languages → GET /languages
• GET /users/schemes → GET /schemes
• GET /users/invoice_states → GET /invoice_states
• And all other code list endpoints

Contact Schema Standardization

Contact (formerly Client) resource now uses standardized field names:

Tax Identifiers:

• taxcode → split into tin_scheme (e.g., “VAT”, “TAX”) and tin_value (the actual number)
• company_identifier → cin_value with accompanying cin_scheme

Routing Codes:

• cin1_value, cin1_scheme, cin2_value, cin2_scheme, … cin5_value, cin5_scheme → nested under routing_codes object
• In responses, routing codes are always returned inside a routing_codes object
• In requests, routing codes must be sent inside a routing_codes wrapper

Transport:

• channel → transport_type_code

Italian Fields:

• posta_elettronica_certificata → certified_email
• codice_destinatario → recipient_code

Bank Details:

• iban, bic, bank_name → nested under bank_account object

Contact Person:

• contact → contact_person

Invoice Schema Improvements

Reference Fields:

• project nested object removed; use flat account_id field
• accounting_cost → buyer_accounting_reference
• contact_person → customer_contact_person

Bank Details:

• iban and bic → nested under bank_account.iban and bank_account.bic

Public Administration Fields (English names):

• num_contracte → contract_number
• organ_gestor → managing_unit
• oficina_comptable → accounting_unit
• organ_proponent → proponent_unit
• unidad_contratacion → contract_unit
• unitat_tramitadora → processing_unit

Event Resource Updates

• ClientEvent renamed to ContactEvent for consistency

---

Deprecated

No features were marked as deprecated in this release.

---

Removed

🚨 Breaking

XML Format Support

Support for XML format response has been removed. JSON format only is now supported and has been set as default.

Deprecated Company/Project Endpoints

• GET /projects.{format} - Removed. Use GET /accounts instead.
• GET /projects/{account}/my_company.{format} - Removed. Use GET /accounts/{account} instead.

Deprecated Tax Reports Endpoints

• POST /tax_reports/send_tax_report/{id}.{format} - Removed. Use POST /accounts/{account}/tax_reports instead.
• GET /tax_reports/{id}/as/{document_type_code} - Removed. Use GET /tax_reports/{id}/download instead.

Channels Endpoint

• GET /users/channels.{format} - Removed. Use GET /transport_types instead.

Event Field

Removed description field from event responses in GET /accounts/{account}/events endpoint.

Schema Attributes Removed

Account Schema:

• prefer_xslt_pdf - Removed

Invoice Schema:

• contact_person - Removed. Use customer_contact_person instead
• state (write-only) - Removed. Use POST /invoices/{id}/mark_as endpoint instead
• customer_party_identification - Removed. Use contact.party_identification instead
• accounting_cost - Removed. Use buyer_accounting_reference instead
• iban - Removed. Use nested bank_account.iban structure instead
• bic - Removed. Use nested bank_account.bic structure instead
• num_contracte - Removed. Use contract_number instead
• organ_gestor - Removed. Use managing_unit instead
• oficina_comptable - Removed. Use accounting_unit instead
• organ_proponent - Removed. Use proponent_unit instead
• unidad_contratacion - Removed. Use contract_unit instead
• unitat_tramitadora - Removed. Use processing_unit instead
• unitat_tramitadora_name - Removed. Use processing_unit instead

Contact Schema:

• old_channel - Removed. Use transport_type_code instead
• contact - Removed. Use contact_person instead
• bank_account - Removed. Use bank_account_number instead
• company_identifier - Removed. Use cin_value instead
• transport_type - Removed. Use transport_type_code instead
• document_type - Removed. Use document_type_code instead
• sepa_type - Removed
• posta_elettronica_certificata - Removed. Use certified_email instead
• codice_destinatario - Removed. Use recipient_code instead

Parameter Schemas:

Deprecated status filter parameters:

• discarded - Marked as deprecated and will be removed
• received_invoice_discarded - Marked as deprecated
• received_invoice_new - Removed
• received_invoice_error - Removed
• received_invoice_refused - Removed
• received_invoice_annotated - Removed
• received_invoice_invalid - Removed

---

Fixed

No bug fixes were specifically documented in this release.

---

Security

No security-specific changes were documented in this release.