Recibir, integrar y gestionar facturas recibidas

Esta guía explica cómo:

• Recibir facturas a través de diferentes canales (Peppol, email, b2brouter, cargas).
• Integrar facturas recibidas en tu sistema (JSON, PDF, archivo original).
• Gestionar el ciclo de vida de la factura (confirmar recepción, aceptar/rechazar/pagar, etc.).

Requisitos previos

• Una empresa con un Identificador Fiscal válido (TIN) o Identificador de Empresa (CIN).
• Una cuenta registrada en el entorno de pruebas de B2Brouter: Regístrate aquí
• Permisos de API (solicítalos a través de un ticket de soporte: Abrir un ticket)
• En caso de duda sobre el proceso de registro, consulta la Guía de usuario.

Si aún necesitas crear la cuenta o habilitar los transportes de recepción, sigue:

• Comenzar (configuración de cuenta): https://developer.b2brouter.net/docs/setting_up_guide#/
• Guía de transportes: https://developer.b2brouter.net/docs/transports_guide/

Conceptos clave (evitar confusión de IDs)

• ACCOUNT_ID se usa solo en los endpoints /accounts/{ACCOUNT_ID}/....
• INVOICE_ID es el identificador de la factura usado en los endpoints /invoices/{INVOICE_ID}....
• En una factura recibida, invoice.contact es el emisor/proveedor (no tu propia cuenta).

1) Recibir facturas

1.1 Importar un archivo de factura recibida (XML) (opcional)

Si ya tienes el archivo de la factura recibida (por ejemplo, para pruebas, migraciones o cargas retroactivas), puedes importarlo con Importar una factura desde un archivo. Usa el parámetro de consulta issued=false para importarla como ReceivedInvoice.

También es posible generar una factura recibida con JSON usando la llamada Crear una factura; recuerda incluir "type": "ReceivedInvoice" al hacerlo.

1.2 Recibir facturas a través de transportes

Una vez que los transportes están habilitados para la cuenta, las facturas llegarán automáticamente (por ejemplo, desde Peppol o email).

2) Listar facturas recibidas

Ejemplo de solicitud:

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

Ejemplo de respuesta (extracto):

{
  "invoices": [
    {
      "id": 105337,
      "number": "2",
      "state": "new",
      "total": 107.1,
      "currency": "EUR"
    },
    {
      "id": 105332,
      "number": "1",
      "state": "received",
      "total": 178.5,
      "currency": "EUR"
    }
  ],
  "total_count": 2,
  "offset": 0,
  "limit": 25
}

Las facturas recibidas pueden tener diferentes estados: las facturas importadas aparecerán en estado “new” y las recibidas a través de diferentes transportes aparecerán normalmente en estado “received”. También pueden tener el estado “invalid” si hay algún problema de validación.

Para consultar todos los estados de factura disponibles, usa el endpoint Lista de estados de factura disponibles.

3) Obtener los detalles de la factura

Para obtener la factura en formato JSON, usa el endpoint Obtener una factura. Añade un Query Param para incluir la información de las líneas:

Ejemplo de solicitud:

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) Descargar el archivo original de la factura

Para descargar la factura legal original que se ha recibido:

Ejemplo de solicitud:

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}'

También puedes usar document_type_code como pdf.invoice para generar una vista en PDF, o cualquier otro document_type_code de Obtener tipos de documento para obtener la factura en cualquier formato de factura electrónica.

5) Confirmar recepción de la factura

Usa el endpoint Marcar una factura como confirmada para evitar que la factura aparezca en el listado de facturas recibidas.

6) Cambiar el estado de la factura

Cambia el estado de la factura para informar al emisor de que has “aceptado”, “rechazado” o “pagado” la factura. También puedes marcar la factura como “anotada” para el seguimiento interno.

Usa el endpoint Cambiar estado de factura. Puedes añadir el parámetro de cuerpo reason para especificar el motivo del rechazo. Si la factura llegó por email, añade el parámetro de cuerpo "commit": "with_mail" para informar al emisor.

Ejemplo de solicitud:

curl --request POST \
  --url https://api-staging.b2brouter.net/invoices/{INVOICE_ID}/mark_as \
  --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 '{
    "state": "refused",
    "reason": "Falta número de pedido"
  }'

Ejemplo de respuesta:

204 No Content

Para más detalles, consulta la Referencia de la API.