Descargar facturas

Cuando trabajas con facturas, es importante diferenciar entre:

• Archivo legal de la factura: el archivo oficial final que fue entregado (facturas emitidas) o recibido (facturas recibidas).
• Archivo original de la factura: el primer archivo recibido por B2Brouter para esa factura (para facturas emitidas, esto es normalmente un archivo fuente importado; para facturas recibidas, es la factura recibida del emisor).
• Exportar una factura a un formato específico: B2Brouter genera un documento a partir de los datos de la factura (puede diferir del archivo legal/original).
• Adjuntos: archivos adicionales vinculados a la factura (PDFs, etc.). Los adjuntos no son la factura en sí.

Dependiendo de lo que necesites, deberás:

• Llamar a un endpoint de descarga directa (por ejemplo, /invoices/{INVOICE_ID}/as/original o /invoices/{INVOICE_ID}/as/legal), o
• Usar una ruta de descarga devuelta en el JSON de la factura (por ejemplo, download_legal_url o attachments[].link).

GET /invoices/{id}/as/legal devuelve el documento legal archivado (p. ej., la versión firmada y con sello de tiempo) tal como está almacenado, sin regenerarlo. Al igual que /as/original, esta llamada no genera ninguna transacción facturable — consulta Transaction: View_as.

Para un proceso desatendido, como un archivo, una sincronización periódica o la exportación de todo un histórico, llama directamente a /invoices/{INVOICE_ID}/as/legal. Solo necesita el id de la factura, funciona tanto para facturas emitidas como recibidas, y evita las trampas de download_legal_url que se describen más abajo. Exportar el histórico de facturas muestra el bucle completo.

Requisitos previos

• Una clave API con acceso al proyecto/cuenta de la factura.
• El invoice.id interno de B2Brouter (puedes obtenerlo de los endpoints de listado).

Paso 1: Obtener el payload de la factura (opcional pero recomendado)

Llama a Get invoice para recuperar el JSON de la factura y localizar los campos relevantes:

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

Este endpoint solo devuelve JSON

El endpoint de la factura no sirve la factura como archivo. En las versiones de la API 2025-10-13 y posteriores, GET /invoices/{INVOICE_ID}.xml responde 406 Not Acceptable con el código de error not_acceptable, y una cabecera Accept: application/xml se ignora: la respuesta es JSON de todos modos. Para obtener el XML o el PDF de una factura, usa las rutas de descarga que se describen a continuación.

Facturas emitidas: archivo legal a través de download_legal_url (IssuedInvoice / IssuedSelfInvoice)

Después de que se envíe una factura emitida, la respuesta incluye download_legal_url, que apunta al archivo legal entregado al receptor (por ejemplo, el XML exacto enviado a una red/plataforma, o el PDF legal).

El campo solo tiene valor para facturas emitidas (IssuedInvoice e IssuedSelfInvoice), y solo una vez que la factura se ha enviado. En cualquier otro caso, incluidas todas las facturas recibidas, el campo está presente con el valor null (la versión de la API 2025-01-01 lo omite). Un null no significa que falte el archivo: para una factura recibida, descárgalo con /invoices/{INVOICE_ID}/as/original o /invoices/{INVOICE_ID}/as/legal, que se describen a continuación. Comprueba el valor del campo, no su presencia.

download_legal_url es una ruta relativa (no una URL completa), por ejemplo:

{
  "invoice": {
    "download_legal_url": "/attachments/download/{ATTACHMENT_ID}/{FILENAME}"
  }
}

Usa la ruta exactamente tal como se devuelve:

• {ATTACHMENT_ID} es el id interno del archivo almacenado. No tiene ninguna relación con el id de la factura, el número, la serie ni la fecha, y no se puede calcular desde tu lado.
• {FILENAME} se comprueba: el id correcto con un nombre de archivo distinto responde 404 Not Found.

Facturas recibidas: archivo original/legal a través de /invoices/{id}/as/original

Para las facturas recibidas, el archivo original también es el archivo legal. Descárgalo directamente con:

GET /invoices/{INVOICE_ID}/as/original

Facturas emitidas o recibidas: archivo legal a través de /invoices/{id}/as/legal

Como alternativa directa de un solo paso a download_legal_url, puedes llamar a /invoices/{INVOICE_ID}/as/legal directamente tanto para facturas emitidas como recibidas. Devuelve el documento legal archivado (p. ej., la versión firmada y con sello de tiempo) tal como está almacenado, sin regenerarlo:

GET /invoices/{INVOICE_ID}/as/legal

Si la factura aún no tiene documento legal, por ejemplo una factura emitida que no se ha enviado, la llamada responde 422 con un mensaje de error que lo indica.

Adjuntos (tanto emitidas como recibidas): attachments[].link

El JSON de la factura puede incluir un array attachments. Cada entrada contiene un link que puedes usar para descargar el adjunto almacenado.

attachments[].link es una ruta relativa (no una URL completa), por ejemplo:

{
  "invoice": {
    "attachments": [
      {
        "link": "/attachments/download/{ATTACHMENT_ID}/{FILENAME}",
        "content_type": "application/pdf"
      }
    ]
  }
}

attachments[].link sigue la misma regla que download_legal_url: úsalo exactamente tal como se devuelve. El segmento numérico es el id del archivo almacenado y no se puede deducir de la factura, y el segmento del nombre de archivo se comprueba.

Para una explicación más detallada de los adjuntos y los PDFs legales, consulta: Gestionar adjuntos de facturas.

Paso 2: Descargar el archivo

Los campos de URL devueltos por la API (download_legal_url, attachments[].link) son rutas relativas. Antepónles la URL base de tu entorno, y no cambies nada más de la ruta.

Descarga usando download_legal_url (facturas emitidas, legal)

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

Descarga usando attachments[].link (adjuntos)

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

Descarga usando /invoices/{id}/as/original (original)

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

Descarga usando /invoices/{id}/as/legal (legal)

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

Notas

• Para facturas recibidas, /invoices/{INVOICE_ID}/as/original devuelve el archivo recibido del emisor (original = legal).
• Para facturas recibidas, download_legal_url es null. Es el comportamiento esperado: usa /invoices/{INVOICE_ID}/as/original o /invoices/{INVOICE_ID}/as/legal.
• GET /invoices/{INVOICE_ID} solo devuelve JSON. El archivo de la factura se obtiene con las rutas de descarga, no con un sufijo de formato en esta llamada.
• Para facturas emitidas, /invoices/{INVOICE_ID}/as/original solo funciona cuando la factura tiene un archivo original (por ejemplo, XML importado). Si la factura fue creada directamente a partir de un payload JSON, es posible que no haya ningún archivo original para descargar.
• /invoices/{INVOICE_ID}/as/legal funciona tanto para facturas emitidas como recibidas y no requiere una llamada previa para obtener download_legal_url.
• Ni /as/original ni /as/legal generan ninguna transacción facturable, ya que no se produce ninguna regeneración del documento. Consulta Transaction: View_as.

Endpoints relacionados

• Get invoice
• Get an invoice with a specific document type
• Get received invoice (list)