Salta al contingut
B2Brouter Docs B2Brouter Docs B2Brouter Docs
Log in
API reference

v2025-10-13

Changelog

Aquesta és la primera versió de l’API de B2Brouter. Inclou millores i canvis significatius per fer l’API consistent, RESTful i més fàcil d’utilitzar.

Ara hi ha l’opció de seleccionar la versió de l’API que s’utilitza a cada petició. El paràmetre de capçalera X-B2B-API-Version permet especificar la versió desitjada per a la petició. Si la Versió de l’API no s’especifica a la petició, es determinarà per la configuració del grup relacionada amb la Clau d’API utilitzada.

Aquesta versió implementa canvis incompatibles. Cada canvi incompatible està marcat amb l’etiqueta Breaking.

Resum dels canvis principals

Section titled “Resum dels canvis principals”

Infraestructura de l’API

Section titled “Infraestructura de l’API”
  • Nou domini: L’accés a l’API s’ha traslladat de app.b2brouter.net a api.b2brouter.net
  • Capçalera de versió: Nova capçalera X-B2B-API-Version per al control explícit de versions
  • Només JSON: S’ha eliminat el suport al format XML; totes les respostes ara són JSON per defecte
  • Idioma de les respostes: Totes les respostes de l’API ara retornen en anglès independentment de la configuració del compte

Modernització de l’estructura de rutes

Section titled “Modernització de l’estructura de rutes”
  • Nomenclatura de recursos: /projects s’ha renomenat a /accounts, /clients s’ha renomenat a /contacts
  • URLs netes: S’han eliminat les extensions .{format} de tots els endpoints
  • Jerarquia simplificada: S’ha eliminat el prefix /users de les llistes de codis, i el prefix /api/v1 dels endpoints de directoris i informes fiscals
  • Paginació estandarditzada: Totes les respostes de llista ara utilitzen un objecte meta consistent per a les dades de paginació

Estandardització de l’esquema

Section titled “Estandardització de l’esquema”
  • Consistència terminològica: Unificació de client → contact a tota l’API
  • Identificadors estructurats: Els codis fiscals s’han dividit en tin_scheme i tin_value per a una millor estructura
  • Nomenclatura en anglès: Els noms de camps en espanyol, català i italià s’han estandarditzat als equivalents en anglès
  • Estructures jeràrquiques: Els camps de compte bancari s’han mogut a subobjectes per a una millor organització
  • Camps obsolets eliminats: S’han netejat els atributs heretats en favor d’alternatives estandarditzades

Millores en les respostes

Section titled “Millores en les respostes”
  • Representacions completes: Les operacions PUT, DELETE i POST ara retornen representacions completes del recurs en lloc de 204 No Content
  • Errors consistents: Respostes d’error estandarditzades amb 409 Conflict per a violacions de regles de negoci
  • Referències simplificades: S’han eliminat els objectes project aniuats de les respostes de factures

Revisió de l’API d’Informes Fiscals

Section titled “Revisió de l’API d’Informes Fiscals”

S’ha eliminat l’API d’Informes Fiscals obsoleta per promoure l’ús d’una nova API d’Informes Fiscals més genèrica i RESTful, adequada per a la majoria de casos d’ús.

Tots els endpoints marcats com a [Deprecated] a la versió 2025-01-01 (Legacy) han estat eliminats. Els endpoints marcats com a [New Tax Report API] a la versió 2025-01-01 ara són l’única manera de gestionar els Informes Fiscals via API. S’ha eliminat el prefix /api/v1 de la ruta d’aquests endpoints.

Afegit

Section titled “Afegit”

Nova capçalera de versió de l’API

S’ha afegit el paràmetre de capçalera X-B2B-API-Version per especificar la versió de l’API per petició. Si no s’especifica, utilitza per defecte la versió configurada als ajustos de la Clau d’API del grup.

Nous endpoints d’Informes Fiscals

  • POST /accounts/{account}/tax_reports - Crea un Informe Fiscal
  • POST /accounts/{account}/tax_reports/import - Importa un Informe Fiscal des d’un fitxer XML
  • GET /tax_reports/{id} - Obté un informe fiscal
  • PATCH /tax_reports/{id} - Corregeix o modifica un Informe Fiscal
  • DELETE /tax_reports/{id} - Anul·la un informe fiscal
  • GET /tax_reports/{id}/download - Descarrega un informe fiscal en format de l’Autoritat Fiscal

Nous endpoints de Llibres Comptables

  • GET /ledgers/{id}/download - Descarrega un document XML de Llibre Comptable
  • GET /ledgers/{id}/download_response - Descarrega la resposta de l’Autoritat Fiscal per a un Llibre Comptable
  • POST /accounts/{account}/ledgers/import - Importa un llibre comptable des d’un payload XML

Nou endpoint de Validació

  • POST /documents/validate - Valida documents electrònics (UBL, CII, Peppol BIS, PINT, ZUGFeRD, XRechnung, Factur-X, FacturaE, Svefaktura, Fattura PA, eSPap i qualsevol format compatible amb EN16931 CIUS)

Nou endpoint de Transport

  • DELETE /accounts/{account}/transports/{code} - Elimina una configuració de transport

Paginació estandarditzada

Tots els endpoints de llistat ara retornen metadades de paginació en un objecte meta consistent que conté total_count, offset i limit.

Llistat de factures consolidat

S’ha afegit el paràmetre de consulta type a l’endpoint /accounts/{account}/invoices per filtrar per tipus de factura (IssuedInvoice, ReceivedInvoice, IssuedSelfInvoice, IssuedSimplifiedInvoice).

Respostes de recursos complets

S’han modificat les operacions PUT, POST i DELETE perquè retornin representacions completes del recurs:

  • PUT /accounts/{account} - Ara retorna la representació completa del compte
  • DELETE /accounts/{account} - Ara retorna la representació completa del compte amb l’estat d’eliminació
  • POST /accounts/{account}/unarchive - Ara retorna la representació completa del compte
  • POST /accounts/{account}/logo - Ara retorna la representació completa del compte
  • DELETE /accounts/{account}/logo - Ara retorna la representació completa del compte
  • PUT /bank_accounts/{id} - Ara retorna la representació completa del compte bancari
  • DELETE /bank_accounts/{id} - Ara retorna la representació completa del compte bancari
  • PUT /contacts/{id} - Ara retorna la representació completa del contacte
  • DELETE /contacts/{id} - Ara retorna la representació completa del contacte
  • PUT /invoices/{id} - Ara retorna la representació completa de la factura
  • DELETE /invoices/{id} - Ara retorna la representació completa de la factura
  • POST /invoices/{id}/mark_as - Ara retorna la representació completa de la factura
  • POST /invoices/{id}/ack - Ara retorna la representació completa de la factura

Modificat

Section titled “Modificat”

🚨 Breaking

Idioma de les respostes

Totes les respostes de l’API ara retornen en anglès independentment de la configuració del compte.

Comportament anterior:

  • Les respostes de l’API heretaven l’idioma de la configuració d’idioma per defecte del compte

Nou comportament:

  • Totes les respostes de l’API retornen en anglès per defecte

Canvi de domini de l’API

La URL base de l’API ha canviat de app.b2brouter.net a api.b2brouter.net

  • Anterior: https://app.b2brouter.net/api/...
  • Nova: https://api.b2brouter.net/...

Canvi de nom de rutes de recursos

Tots els endpoints que contenien /projects/{account} s’han actualitzat a /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
  • I tots els altres endpoints amb àmbit de projecte

Tots els endpoints que feien referència a /clients s’han actualitzat a /contacts:

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

Eliminació de l’extensió de format

S’han eliminat les extensions de ruta .{format} de tots els endpoints. JSON és ara l’únic format suportat i s’estableix com a predeterminat:

  • 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}
  • I tots els endpoints de llistes de codis

Simplificació de la ruta de llistes de codis

S’ha eliminat el prefix /users de tots els endpoints de llistes de codis:

  • 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
  • I tots els altres endpoints de llistes de codis

Estandardització de l’esquema de contactes

El recurs Contacte (abans Client) ara utilitza noms de camps estandarditzats:

Identificadors fiscals:

  • taxcode → dividit en tin_scheme (p. ex., “VAT”, “TAX”) i tin_value (el número real)
  • company_identifier → cin_value amb el corresponent cin_scheme

Codis d’encaminament:

  • cin1_value, cin1_scheme, cin2_value, cin2_scheme, … cin5_value, cin5_scheme → aniuats sota l’objecte routing_codes
  • A les respostes, els codis d’encaminament sempre es retornen dins d’un objecte routing_codes
  • A les peticions, els codis d’encaminament s’han d’enviar dins d’un contenidor routing_codes

Transport:

  • channel → transport_type_code

Camps italians:

  • posta_elettronica_certificata → certified_email
  • codice_destinatario → recipient_code

Dades bancàries:

  • iban, bic, bank_name → aniuats sota l’objecte bank_account

Persona de contacte:

  • contact → contact_person

Millores a l’esquema de factures

Camps de referència:

  • S’ha eliminat l’objecte aniuat project; utilitza el camp pla account_id
  • accounting_cost → buyer_accounting_reference
  • contact_person → customer_contact_person

Dades bancàries:

  • iban i bic → aniuats sota bank_account.iban i bank_account.bic

Camps d’Administració Pública (noms en anglès):

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

Actualitzacions al recurs Esdeveniment

  • ClientEvent s’ha renomenat a ContactEvent per a coherència

Obsolet

Section titled “Obsolet”

Cap funcionalitat s’ha marcat com a obsoleta en aquesta versió.

Eliminat

Section titled “Eliminat”

🚨 Breaking

Suport al format XML

S’ha eliminat el suport al format de resposta XML. Ara només s’admet el format JSON, que s’ha establert com a predeterminat.

Endpoints obsolets de Company/Projecte

  • GET /projects.{format} - Eliminat. Utilitza GET /accounts en el seu lloc.
  • GET /projects/{account}/my_company.{format} - Eliminat. Utilitza GET /accounts/{account} en el seu lloc.

Endpoints obsolets d’Informes Fiscals

  • POST /tax_reports/send_tax_report/{id}.{format} - Eliminat. Utilitza POST /accounts/{account}/tax_reports en el seu lloc.
  • GET /tax_reports/{id}/as/{document_type_code} - Eliminat. Utilitza GET /tax_reports/{id}/download en el seu lloc.

Endpoint de Canals

  • GET /users/channels.{format} - Eliminat. Utilitza GET /transport_types en el seu lloc.

Camp d’Esdeveniment

S’ha eliminat el camp description de les respostes d’esdeveniments a l’endpoint GET /accounts/{account}/events.

Atributs d’esquema eliminats

Esquema de compte:

  • prefer_xslt_pdf - Eliminat

Esquema de factura:

  • contact_person - Eliminat. Utilitza customer_contact_person en el seu lloc
  • state (només escriptura) - Eliminat. Utilitza l’endpoint POST /invoices/{id}/mark_as en el seu lloc
  • customer_party_identification - Eliminat. Utilitza contact.party_identification en el seu lloc
  • accounting_cost - Eliminat. Utilitza buyer_accounting_reference en el seu lloc
  • iban - Eliminat. Utilitza l’estructura niada bank_account.iban en el seu lloc
  • bic - Eliminat. Utilitza l’estructura niada bank_account.bic en el seu lloc
  • num_contracte - Eliminat. Utilitza contract_number en el seu lloc
  • organ_gestor - Eliminat. Utilitza managing_unit en el seu lloc
  • oficina_comptable - Eliminat. Utilitza accounting_unit en el seu lloc
  • organ_proponent - Eliminat. Utilitza proponent_unit en el seu lloc
  • unidad_contratacion - Eliminat. Utilitza contract_unit en el seu lloc
  • unitat_tramitadora - Eliminat. Utilitza processing_unit en el seu lloc
  • unitat_tramitadora_name - Eliminat. Utilitza processing_unit en el seu lloc

Esquema de contacte:

  • old_channel - Eliminat. Utilitza transport_type_code en el seu lloc
  • contact - Eliminat. Utilitza contact_person en el seu lloc
  • bank_account - Eliminat. Utilitza bank_account_number en el seu lloc
  • company_identifier - Eliminat. Utilitza cin_value en el seu lloc
  • transport_type - Eliminat. Utilitza transport_type_code en el seu lloc
  • document_type - Eliminat. Utilitza document_type_code en el seu lloc
  • sepa_type - Eliminat
  • posta_elettronica_certificata - Eliminat. Utilitza certified_email en el seu lloc
  • codice_destinatario - Eliminat. Utilitza recipient_code en el seu lloc

Esquemes de paràmetres:

Paràmetres de filtre d’estat obsolets:

  • discarded - Marcat com a obsolet i serà eliminat
  • received_invoice_discarded - Marcat com a obsolet
  • received_invoice_new - Eliminat
  • received_invoice_error - Eliminat
  • received_invoice_refused - Eliminat
  • received_invoice_annotated - Eliminat
  • received_invoice_invalid - Eliminat

Corregit

Section titled “Corregit”

No s’han documentat correccions d’errors específiques en aquesta versió.

Seguretat

Section titled “Seguretat”

No s’han documentat canvis específics de seguretat en aquesta versió.