API Version Release - 2025-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.

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.

Breaking Changes

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

Changelog

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.

Changelog

Changelog - 2026-03-02

API Version 2026-03-02

Changelog - 2025-10-13

API Version Release - 2025-10-13