Cuando una factura destinada a su organización llega a través de Peppol u otra red, el PSB almacena el documento y envía una notificación a su webhook. En este artículo aprenderá cómo recibir esa notificación, descargar el documento y configurar la gestión de estados.

La recepción de una factura se realiza en cuatro pasos:

1. Notificación: el PSB envía un evento webhook InvoiceReceived a su endpoint
2. Descarga: usted recupera el documento a través del endpoint PurchaseInvoice
3. Procesamiento: usted procesa la factura en su propio sistema
4. Limpieza (opcional): usted elimina el documento del PSB

Para recibir facturas necesita un webhook que escuche el topic InvoiceReceived. Regístrelo a través de la Hook API:

POST /api/v1/hook

{
  "action": "https://mijn-systeem.nl/webhook/invoices#mijnSecretKey",
  "topics": ["InvoiceReceived"]
}

En cuanto llegue una factura, su endpoint recibirá una solicitud POST con un payload JSON. Este payload contiene, entre otros, el documentId y el partyId con los cuales puede recuperar el documento.

Consejo: configure también un webhook en el topic InvoiceReceivedError para recibir notificaciones en caso de problemas durante la recepción.

Utilice el documentId del payload webhook para recuperar la factura:

GET /api/v1/{partyId}/purchaseInvoice/{documentId}/download HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}

La respuesta contiene el documento XML (por defecto en el formato original). ¿Desea recibir el documento en otro formato? Utilice el parámetro targetDocumentTypeId:

GET /api/v1/{partyId}/purchaseInvoice/{documentId}/download?targetDocumentTypeId={URN}

El PSB transforma automáticamente el documento al formato especificado antes de devolverlo.

El PSB conserva los documentos recibidos según el siguiente esquema:

Se recomienda recuperar los documentos inmediatamente después de la recepción y almacenarlos en su propio sistema. No confíe en el PSB como almacenamiento a largo plazo.

Después del procesamiento, puede eliminar manualmente el documento:

DELETE /api/v1/{partyId}/purchaseInvoice/{documentId} HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}

Esto elimina definitivamente el documento del PSB. La pista de auditoría permanece disponible.

Después de la recepción, puede actualizar el estado de procesamiento de una factura de compra. Esto es especialmente relevante si desea enviar Invoice Responses (mensajes de estado) al remitente. Para ello, consulte el artículo Enviar Invoice Response.

El PSB envía automáticamente un mensaje MLS (Message Level Status) al remitente tras la recepción de un documento. Esto confirma que el documento ha sido recibido y entregado. Como integrador no necesita configurar nada para ello: el PSB lo gestiona completamente. Si usted envía documentos usted mismo, recibe retroalimentación MLS a través del topic webhook MessageLevelStatusReceived. Consulte Configurar webhooks para la configuración.

Si no puede configurar webhooks (por ejemplo en un entorno on-premise sin tráfico de internet entrante), también puede recuperar facturas mediante polling:

GET /api/v1/{partyId}/purchaseInvoice HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}

Este endpoint devuelve una lista de facturas de compra disponibles. Sin embargo, los webhooks son siempre el método preferido debido al procesamiento en tiempo real y la menor carga sobre la API.

Atención: para integraciones on-premise, considere también el reverse webhook (HTTPS inbound hook), con el cual el PSB envía los documentos sin que su sistema necesite ser directamente accesible desde Internet.

• Procese de forma idempotente: el PSB puede, en casos excepcionales, entregar un evento varias veces. Verifique de su lado si ya ha procesado un documento antes de importarlo nuevamente.
• Descargue inmediatamente: recupere los documentos lo antes posible después de la notificación webhook. La retención de 90 días es una red de seguridad, no una estrategia de almacenamiento.
• Registre el documentId: conserve el documentId del PSB en su propio sistema para rastreo y eventual resolución de problemas.
• Convertir formato: si necesita un formato XML específico, utilice targetDocumentTypeId al descargar en lugar de convertir usted mismo.
• Reintentos de webhook: si su endpoint no es accesible temporalmente, el PSB reintenta la entrega de la notificación durante un máximo de 5 días. ¿Periodo de inactividad prolongado? Utilice batch hooks como alternativa para recuperar los documentos perdidos.

Consulte los endpoints PurchaseInvoice completos y los modelos de respuesta en psb.econnect.eu.