Enviar facturas (de extremo a extremo)

Esta guía muestra un flujo de API limpio para enviar facturas: crear o reutilizar un contact, crear o importar una factura, enviarla y recuperar los archivos finales.

Requisitos previos

Clave API: X-B2B-API-Key
Versión de la API: X-B2B-API-Version
ACCOUNT_ID: la cuenta que emite la factura.

IDs importantes:

ACCOUNT_ID: cuenta propietaria (parámetro de ruta en /accounts/{ACCOUNT_ID}/...).
CONTACT_ID: contact destinatario (almacenado dentro de la cuenta).
INVOICE_ID: identificador de la factura (usado en los endpoints /invoices/{INVOICE_ID}...).

1) Obtener o crear el contact destinatario

1.1) Buscar contacts (opcional)

curl --request GET \
  --url 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/contacts?offset=0&limit=25&name=Example%20Customer' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

1.2) Búsqueda en el directorio (opcional)

Si conoces el identificador y el país del destinatario, puedes obtener información pública del directorio y usarla para crear el contact.

curl --request GET \
  --url https://api-staging.b2brouter.net/directory/es/ESB63276174 \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

1.3) Crear un contact (si no tienes uno)

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/contacts \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "contact": {
      "name": "Cliente de ejemplo",
      "country": "es",
      "is_client": true,
      "email": "billing@example.com",
      "tin_scheme": "9920",
      "tin_value": "ESB00000000",
      "transport_type_code": "b2brouter",
      "document_type_code": "json"
    }
  }'

Nota: CONTACT_ID se devuelve en la respuesta. No lo confundas con ACCOUNT_ID.

2) Crear (JSON) o importar (XML) la factura

2.1) Crear la factura usando JSON

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "send_after_import": false,
    "invoice": {
      "type": "IssuedInvoice",
      "contact_id": {CONTACT_ID},
      "number": "INV-0001",
      "date": "2026-01-21",
      "terms": "custom",
      "due_date": "2026-02-21",
      "currency": "EUR",
      "invoice_lines_attributes": [
        {
          "quantity": 1,
          "price": 10,
          "description": "Servicio de ejemplo",
          "taxes_attributes": [
            { "name": "VAT", "category": "S", "percent": 21 }
          ]
        }
      ]
    }
  }'

2.2) Importar la factura desde un archivo (cuando ya generas XML)

curl --request POST \
  --url 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices/import?send_after_import=false' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'content-type: application/octet-stream' \
  --data 'data:text/xml;name=invoice.xml;base64,PD94bWw+Li4u'

2.3) Qué pasa con los datos del contacto que lleva la factura (`update_contact`)

Cuando importas un archivo, o creas una factura con un bloque contact en lugar de contact_id, B2Brouter busca al comprador entre los contactos de la cuenta por sus identificadores y usa el contacto que encuentra. Por defecto, una importación nunca modifica un contacto existente:

Si algún dato del archivo (dirección, códigos de encaminamiento, método de envío) no coincide con el del contacto, la factura queda asignada a una unidad organizativa de ese contacto con los datos del archivo. El contacto no cambia.
Si solo difiere el nombre, no pasa nada: no se crea ninguna unidad organizativa ni se escribe ningún campo, y la factura sale con el nombre guardado en el contacto.

El parámetro update_contact es opcional, por defecto está desactivado y existe en todas las versiones de la API. Envía update_contact=true (como parámetro de consulta en la llamada de importación, o como campo de primer nivel del cuerpo JSON en la llamada de creación, igual que send_after_import) para que la importación actualice el contacto en lugar de crear una unidad organizativa. Si ya existe una unidad organizativa con esos datos, se usa esa.

Los datos descriptivos del archivo (el nombre incluido, la dirección y el resto de campos que no son identificadores) sustituyen a los del contacto.
Los identificadores (identificador fiscal, identificador de empresa, identificador Peppol y códigos de encaminamiento) solo se rellenan si en el contacto estaban vacíos. Un identificador que ya tiene valor nunca se sobrescribe, aunque el archivo lleve uno distinto.
Un valor vacío en el archivo nunca borra el valor guardado.
En las facturas recibidas el parámetro se ignora: un documento recibido nunca actualiza el contacto del proveedor.
El endpoint de importación masiva /invoices/imports no admite este parámetro.

Decide qué lado manda sobre los datos del contacto. Con update_contact=true en todas las llamadas, la factura que envías es la referencia: cualquier cambio en el archivo se propaga a la ficha del contacto y a las facturas posteriores. Sin el parámetro, la ficha del contacto en B2Brouter es la referencia, y la corriges con la API de contactos o desde la aplicación web.

3) Enviar la factura

curl --request POST \
  --url https://api-staging.b2brouter.net/invoices/send_invoice/{INVOICE_ID} \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}'

4) Recuperar la factura y descargar los archivos finales

4.1) Obtener el payload de la factura

curl --request GET \
  --url 'https://api-staging.b2brouter.net/invoices/{INVOICE_ID}?include=lines' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

4.2) Descargar los archivos legal/original de la factura

Consulta la guía Descargar facturas.