Ir al contenido
B2Brouter Docs B2Brouter Docs B2Brouter Docs
Log in
API reference

v2025-10-13

Changelog

Esta es la primera versión de la API de B2Brouter. Incluye mejoras y cambios significativos para hacer la API consistente, RESTful y más fácil de usar.

Ahora existe la opción de seleccionar la versión de la API que se utiliza en cada petición. El parámetro de cabecera X-B2B-API-Version permite especificar la versión deseada para la petición. Si la Versión de la API no se especifica en la petición, se determinará por la configuración del grupo relacionada con la Clave de API utilizada.

Esta versión implementa cambios incompatibles. Cada cambio incompatible está marcado con la etiqueta Breaking.

Resumen de los cambios principales

Sección titulada «Resumen de los cambios principales»

Infraestructura de la API

Sección titulada «Infraestructura de la API»
  • Nuevo dominio: El acceso a la API se ha trasladado de app.b2brouter.net a api.b2brouter.net
  • Cabecera de versión: Nueva cabecera X-B2B-API-Version para el control explícito de versiones
  • Solo JSON: Se ha eliminado el soporte al formato XML; todas las respuestas son ahora JSON por defecto
  • Idioma de las respuestas: Todas las respuestas de la API retornan ahora en inglés independientemente de la configuración de la cuenta

Modernización de la estructura de rutas

Sección titulada «Modernización de la estructura de rutas»
  • Nomenclatura de recursos: /projects se ha renombrado a /accounts, /clients se ha renombrado a /contacts
  • URLs limpias: Se han eliminado las extensiones .{format} de todos los endpoints
  • Jerarquía simplificada: Se ha eliminado el prefijo /users de las listas de códigos, y el prefijo /api/v1 de los endpoints de directorios e informes fiscales
  • Paginación estandarizada: Todas las respuestas de lista ahora utilizan un objeto meta consistente para los datos de paginación

Estandarización del esquema

Sección titulada «Estandarización del esquema»
  • Consistencia terminológica: Unificación de client → contact en toda la API
  • Identificadores estructurados: Los códigos fiscales se han dividido en tin_scheme y tin_value para una mejor estructura
  • Nomenclatura en inglés: Los nombres de campos en español, catalán e italiano se han estandarizado a sus equivalentes en inglés
  • Estructuras anidadas: Los campos de cuenta bancaria se han movido a objetos anidados para una mejor organización
  • Campos obsoletos eliminados: Se han eliminado los atributos heredados en favor de alternativas estandarizadas

Mejoras en las respuestas

Sección titulada «Mejoras en las respuestas»
  • Representaciones completas: Las operaciones PUT, DELETE y POST ahora retornan representaciones completas del recurso en lugar de 204 No Content
  • Errores consistentes: Respuestas de error estandarizadas con 409 Conflict para violaciones de reglas de negocio
  • Referencias simplificadas: Se han eliminado los objetos project anidados de las respuestas de facturas

Revisión de la API de Informes Fiscales

Sección titulada «Revisión de la API de Informes Fiscales»

Se ha eliminado la API de Informes Fiscales obsoleta para promover el uso de una nueva API de Informes Fiscales más genérica y RESTful, adecuada para la mayoría de casos de uso.

Todos los endpoints marcados como [Deprecated] en la versión 2025-01-01 (Legacy) han sido eliminados. Los endpoints marcados como [New Tax Report API] en la versión 2025-01-01 son ahora la única manera de gestionar los Informes Fiscales via API. Se ha eliminado el prefijo /api/v1 de la ruta de estos endpoints.

Añadido

Sección titulada «Añadido»

Nueva cabecera de versión de la API

Se ha añadido el parámetro de cabecera X-B2B-API-Version para especificar la versión de la API por petición. Si no se especifica, utiliza por defecto la versión configurada en los ajustes de la Clave de API del grupo.

Nuevos endpoints de Informes Fiscales

  • POST /accounts/{account}/tax_reports - Crea un Informe Fiscal
  • POST /accounts/{account}/tax_reports/import - Importa un Informe Fiscal desde un fichero XML
  • GET /tax_reports/{id} - Obtiene un informe fiscal
  • PATCH /tax_reports/{id} - Corrige o modifica un Informe Fiscal
  • DELETE /tax_reports/{id} - Anula un informe fiscal
  • GET /tax_reports/{id}/download - Descarga un informe fiscal en formato de la Autoridad Fiscal

Nuevos endpoints de Libros Contables

  • GET /ledgers/{id}/download - Descarga un documento XML de Libro Contable
  • GET /ledgers/{id}/download_response - Descarga la respuesta de la Autoridad Fiscal para un Libro Contable
  • POST /accounts/{account}/ledgers/import - Importa un libro contable desde un payload XML

Nuevo endpoint de Validación

  • POST /documents/validate - Valida documentos electrónicos (UBL, CII, Peppol BIS, PINT, ZUGFeRD, XRechnung, Factur-X, FacturaE, Svefaktura, Fattura PA, eSPap y cualquier formato compatible con EN16931 CIUS)

Nuevo endpoint de Transporte

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

Paginación estandarizada

Todos los endpoints de listado ahora retornan metadatos de paginación en un objeto meta consistente que contiene total_count, offset y limit.

Listado de facturas consolidado

Se ha añadido el parámetro de consulta type al endpoint /accounts/{account}/invoices para filtrar por tipo de factura (IssuedInvoice, ReceivedInvoice, IssuedSelfInvoice, IssuedSimplifiedInvoice).

Respuestas de recursos completos

Se han modificado las operaciones PUT, POST y DELETE para que retornen representaciones completas del recurso:

  • PUT /accounts/{account} - Ahora retorna la representación completa de la cuenta
  • DELETE /accounts/{account} - Ahora retorna la representación completa de la cuenta con el estado de eliminación
  • POST /accounts/{account}/unarchive - Ahora retorna la representación completa de la cuenta
  • POST /accounts/{account}/logo - Ahora retorna la representación completa de la cuenta
  • DELETE /accounts/{account}/logo - Ahora retorna la representación completa de la cuenta
  • PUT /bank_accounts/{id} - Ahora retorna la representación completa de la cuenta bancaria
  • DELETE /bank_accounts/{id} - Ahora retorna la representación completa de la cuenta bancaria
  • PUT /contacts/{id} - Ahora retorna la representación completa del contacto
  • DELETE /contacts/{id} - Ahora retorna la representación completa del contacto
  • PUT /invoices/{id} - Ahora retorna la representación completa de la factura
  • DELETE /invoices/{id} - Ahora retorna la representación completa de la factura
  • POST /invoices/{id}/mark_as - Ahora retorna la representación completa de la factura
  • POST /invoices/{id}/ack - Ahora retorna la representación completa de la factura

Modificado

Sección titulada «Modificado»

🚨 Breaking

Idioma de las respuestas

Todas las respuestas de la API retornan ahora en inglés independientemente de la configuración de la cuenta.

Comportamiento anterior:

  • Las respuestas de la API heredaban el idioma de la configuración de idioma por defecto de la cuenta

Nuevo comportamiento:

  • Todas las respuestas de la API retornan en inglés por defecto

Cambio de dominio de la API

La URL base de la API ha cambiado de app.b2brouter.net a api.b2brouter.net

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

Cambio de nombre de rutas de recursos

Todos los endpoints que contenían /projects/{account} se han actualizado 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
  • Y todos los demás endpoints con ámbito de proyecto

Todos los endpoints que hacían referencia a /clients se han actualizado a /contacts:

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

Eliminación de la extensión de formato

Se han eliminado las extensiones de ruta .{format} de todos los endpoints. JSON es ahora el único formato soportado y se establece como predeterminado:

  • 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}
  • Y todos los endpoints de listas de códigos

Simplificación de la ruta de listas de códigos

Se ha eliminado el prefijo /users de todos los endpoints de listas de códigos:

  • 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
  • Y todos los demás endpoints de listas de códigos

Estandarización del esquema de contactos

El recurso Contacto (antes Cliente) ahora utiliza nombres de campos estandarizados:

Identificadores fiscales:

  • taxcode → dividido en tin_scheme (p. ej., “VAT”, “TAX”) y tin_value (el número real)
  • company_identifier → cin_value con el correspondiente cin_scheme

Códigos de enrutamiento:

  • cin1_value, cin1_scheme, cin2_value, cin2_scheme, … cin5_value, cin5_scheme → anidados bajo el objeto routing_codes
  • En las respuestas, los códigos de enrutamiento siempre se retornan dentro de un objeto routing_codes
  • En las peticiones, los códigos de enrutamiento deben enviarse dentro de un contenedor routing_codes

Transporte:

  • channel → transport_type_code

Campos italianos:

  • posta_elettronica_certificata → certified_email
  • codice_destinatario → recipient_code

Datos bancarios:

  • iban, bic, bank_name → anidados bajo el objeto bank_account

Persona de contacto:

  • contact → contact_person

Mejoras en el esquema de facturas

Campos de referencia:

  • Se ha eliminado el objeto anidado project; usa el campo plano account_id
  • accounting_cost → buyer_accounting_reference
  • contact_person → customer_contact_person

Datos bancarios:

  • iban y bic → anidados bajo bank_account.iban y bank_account.bic

Campos de Administración Pública (nombres en inglé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

Actualizaciones en el recurso Evento

  • ClientEvent se ha renombrado a ContactEvent para mayor consistencia

Obsoleto

Sección titulada «Obsoleto»

Ninguna funcionalidad se ha marcado como obsoleta en esta versión.

Eliminado

Sección titulada «Eliminado»

🚨 Breaking

Soporte al formato XML

Se ha eliminado el soporte al formato de respuesta XML. Ahora solo se admite el formato JSON, que se ha establecido como predeterminado.

Endpoints obsoletos de Empresa/Proyecto

  • GET /projects.{format} - Eliminado. Usa GET /accounts en su lugar.
  • GET /projects/{account}/my_company.{format} - Eliminado. Usa GET /accounts/{account} en su lugar.

Endpoints obsoletos de Informes Fiscales

  • POST /tax_reports/send_tax_report/{id}.{format} - Eliminado. Usa POST /accounts/{account}/tax_reports en su lugar.
  • GET /tax_reports/{id}/as/{document_type_code} - Eliminado. Usa GET /tax_reports/{id}/download en su lugar.

Endpoint de Canales

  • GET /users/channels.{format} - Eliminado. Usa GET /transport_types en su lugar.

Campo de Evento

Se ha eliminado el campo description de las respuestas de eventos en el endpoint GET /accounts/{account}/events.

Atributos de esquema eliminados

Esquema de cuenta:

  • prefer_xslt_pdf - Eliminado

Esquema de factura:

  • contact_person - Eliminado. Usa customer_contact_person en su lugar
  • state (solo escritura) - Eliminado. Usa el endpoint POST /invoices/{id}/mark_as en su lugar
  • customer_party_identification - Eliminado. Usa contact.party_identification en su lugar
  • accounting_cost - Eliminado. Usa buyer_accounting_reference en su lugar
  • iban - Eliminado. Usa la estructura anidada bank_account.iban en su lugar
  • bic - Eliminado. Usa la estructura anidada bank_account.bic en su lugar
  • num_contracte - Eliminado. Usa contract_number en su lugar
  • organ_gestor - Eliminado. Usa managing_unit en su lugar
  • oficina_comptable - Eliminado. Usa accounting_unit en su lugar
  • organ_proponent - Eliminado. Usa proponent_unit en su lugar
  • unidad_contratacion - Eliminado. Usa contract_unit en su lugar
  • unitat_tramitadora - Eliminado. Usa processing_unit en su lugar
  • unitat_tramitadora_name - Eliminado. Usa processing_unit en su lugar

Esquema de contacto:

  • old_channel - Eliminado. Usa transport_type_code en su lugar
  • contact - Eliminado. Usa contact_person en su lugar
  • bank_account - Eliminado. Usa bank_account_number en su lugar
  • company_identifier - Eliminado. Usa cin_value en su lugar
  • transport_type - Eliminado. Usa transport_type_code en su lugar
  • document_type - Eliminado. Usa document_type_code en su lugar
  • sepa_type - Eliminado
  • posta_elettronica_certificata - Eliminado. Usa certified_email en su lugar
  • codice_destinatario - Eliminado. Usa recipient_code en su lugar

Esquemas de parámetros:

Parámetros de filtro de estado obsoletos:

  • discarded - Marcado como obsoleto y será eliminado
  • received_invoice_discarded - Marcado como obsoleto
  • received_invoice_new - Eliminado
  • received_invoice_error - Eliminado
  • received_invoice_refused - Eliminado
  • received_invoice_annotated - Eliminado
  • received_invoice_invalid - Eliminado

Corregido

Sección titulada «Corregido»

No se han documentado correcciones de errores específicas en esta versión.

Seguridad

Sección titulada «Seguridad»

No se han documentado cambios específicos de seguridad en esta versión.