Adjuntos de facturas

Disponible desde la versión 2025-10-13

Esta guía explica cómo añadir, leer e interpretar adjuntos cuando se trabaja con facturas a través de la API o XML.

Elija un flujo de trabajo

• Crear con JSON: cree la factura primero, luego añada adjuntos con add_attachment o add_attachments.
• Importar XML con adjuntos incrustados: incluya los adjuntos dentro del XML e importe el archivo.
• Importar PDF con XML incrustado (facturas recibidas): si el PDF contiene un XML incrustado (Factur-X/ZUGFeRD), B2Brouter puede extraerlo y crear la factura recibida.

Principios importantes

• El XML es la fuente legal y estructurada. Su PDF debe ser coherente con los datos del XML. No intente cambiar la estructura del XML para adaptarla a un diseño de PDF personalizado; el XML debe seguir esquemas estandarizados para que cualquier receptor pueda procesarlo.
• Los adjuntos son complementarios. Un PDF (o cualquier adjunto) no es una factura electrónica y no permite el procesamiento automatizado por sí solo. Use los adjuntos como documentos de apoyo, no como fuente de datos principal.

Añadir adjuntos a una factura existente

Añadir un único adjunto (recomendado para vista previa en PDF)

Primero debe crear o importar una factura.

Después de crear la factura, se añade un adjunto realizando una solicitud POST al endpoint /invoices/{id}/add_attachment. La solicitud debe enviar los bytes sin procesar del archivo como cuerpo e incluir el nombre del archivo usando el parámetro de consulta filename.

Si el PDF adjunto debe utilizarse como representación visual y legal de la factura, también debe proporcionarse el parámetro use_as_pdf_view=true.

curl --request POST \
  --url 'https://api-staging.b2brouter.net/invoices/12345/add_attachment?filename=invoice.pdf&use_as_pdf_view=true'

Notas:

• La API espera Content-Type: application/octet-stream.
• Se recomiendan los bytes sin procesar; los payloads en base64 o data-URI también funcionan.
• use_as_pdf_view=true marca el PDF como PDF visual/legal (solo uno por factura).
• use_as_pdf_view=true solo aplica a cargas de PDF. No intente marcar un XML (UBL/Facturae/CII/etc.) como use_as_pdf_view=true: no se convertirá en la vista PDF.
• La vista PDF está disponible para tipos de documento basados en PDF como pdf.invoice, pdf.invoice.signed y tipos híbridos PDF/A como pdf.a.invoice.with.xml.cii.cross_industry_invoice.facturx.en16931 y pdf.a.invoice.with.xml.cii.cross_industry_invoice.facturx.extended.
• Si modifica la factura posteriormente, se seguirá usando el mismo PDF a menos que se reemplace.

Añadir múltiples adjuntos (ZIP)

Use el endpoint ZIP cuando necesite cargar varios archivos en una sola llamada.

zip attachments.zip file1.pdf file2.xml
curl --request POST \
  --url https://api-staging.b2brouter.net/invoices/12345/add_attachments

Si necesita establecer un PDF como vista previa de la factura, primero cargue ese PDF usando el endpoint add_attachment con el parámetro de consulta use_as_pdf_view=true, y luego cargue el resto con el endpoint add_attachments.

Añadir adjuntos al importar un XML de factura

Si ya genera XML (UBL, Facturae, CII, etc.), puede incrustar adjuntos en el XML e importar el archivo. Los adjuntos se extraerán y almacenarán automáticamente.

UBL (Peppol)

<cac:AdditionalDocumentReference>
  <cbc:ID>ATT-1</cbc:ID>
  <cac:Attachment>
    <cbc:EmbeddedDocumentBinaryObject
      mimeCode="application/pdf"
      filename="invoice.pdf">BASE64_DATA</cbc:EmbeddedDocumentBinaryObject>
  </cac:Attachment>
</cac:AdditionalDocumentReference>

Facturae

<AdditionalData>
  <RelatedDocuments>
    <Attachment>
      <AttachmentCompressionAlgorithm>NONE</AttachmentCompressionAlgorithm>
      <AttachmentFormat>PDF</AttachmentFormat>
      <AttachmentEncoding>BASE64</AttachmentEncoding>
      <AttachmentDescription>invoice.pdf</AttachmentDescription>
      <AttachmentData>BASE64_DATA</AttachmentData>
    </Attachment>
  </RelatedDocuments>
</AdditionalData>

CII / ZUGFeRD

<ram:AdditionalReferencedDocument>
  <ram:AttachmentBinaryObject
    mimeCode="application/pdf"
    filename="invoice.pdf">BASE64_DATA</ram:AttachmentBinaryObject>
</ram:AdditionalReferencedDocument>

Detalles de codificación:

• Base64 es la codificación predeterminada.
• Si el XML incluye un código de codificación explícito, los valores compatibles son BASE64, BER y DER.
• En Facturae, AttachmentCompressionAlgorithm puede ser ZIP o GZIP.
• Si no se define la compresión, el contenido se decodifica como base64 plano.

Usar su propio PDF en ZUGFeRD / Factur-X

Para enviar un PDF híbrido (PDF + XML incrustado) usando su propio diseño:

1. Elija un tipo de documento híbrido en el contacto (por ejemplo: pdf.a.invoice.with.xml.cii.cross_industry_invoice.facturx.en16931).
2. Cree la factura como de costumbre.
3. Cargue su PDF con use_as_pdf_view=true.
4. Envíe la factura.

Ejemplo de contacto:

{
  "contact": {
    "name": "Example GmbH",
    "tin_scheme": "9930",
    "tin_value": "DE8******3",
    "transport_type_code": "email",
    "document_type_code": "pdf.a.invoice.with.xml.cii.cross_industry_invoice.facturx.en16931"
  }
}

Para listar los tipos de documento disponibles, use el endpoint de tipos de documento GET /document_types.

Cómo aparecen los adjuntos en las respuestas de la API

• El array attachments en el endpoint de obtener factura GET /invoices/{id} incluye los archivos normales que cargó en la factura (no incluye el PDF marcado como pdf_view).
• En general, un PDF cargado con use_as_pdf_view=true se almacena como PDF visual/legal (pdf_view) y no aparece en el array attachments.
• Excepción: para facturas recibidas, si el documento original es un PDF y su tipo de documento no es un attached_document_type, ese PDF original también se expone en el array attachments.
• Tras enviar una factura emitida, download_legal_url apunta al PDF legal (generado por B2Brouter o su pdf_view si se proporcionó).

Leer adjuntos de facturas recibidas

Cuando recupere una factura recibida, la respuesta incluye un array attachments con enlaces de descarga:

{
  "attachments": [
    {
      "link": "/attachments/download/253526/2025-02-10_1_original.pdf",
      "content_type": "application/pdf"
    }
  ]
}

Para descargar el archivo, use el endpoint GET /attachments/download/{id}/{filename}.

Incluya su cabecera de clave API al descargar. El id proviene del enlace.

Eliminar adjuntos

La eliminación es posible desde la aplicación web, pero no hay un endpoint de API público. Si un adjunto se importó incorrectamente y necesita un flujo automatizado, el enfoque recomendado es eliminar la factura y volver a enviarla sin el adjunto incorrecto.

Límites y restricciones de transporte

• B2Brouter permite hasta 50 MB por archivo. Si envía por correo electrónico, el tamaño total de adjuntos está limitado a 40 MB. Algunas redes pueden imponer límites más bajos (10–20 MB), según el canal.
• Formatos esperados: PDF y XML, además de archivos de oficina comunes (por ejemplo, CSV). Los formatos ejecutables o de script están bloqueados (por ejemplo, .exe, .js, .bat, .sh, .jar, .ps1, .html, .gif).
• Algunos transportes están configurados como “sin adjuntos incrustados” (desvinculados), por lo que los adjuntos no se incluyen en el XML enviado al receptor.
• Algunos sistemas de destinatarios ignoran los adjuntos incrustados aunque estén presentes.
• Si la factura no se envía correctamente, el destinatario no verá el PDF independientemente de los adjuntos.
• El endpoint add_attachment requiere Content-Type: application/octet-stream y un parámetro de consulta filename.