El envío de una e-factura a través de la API PSB es el endpoint más utilizado. Usted envía un documento XML a la API en el formato que su software produce, y el PSB se encarga de la validación, la transformación automática al formato esperado por el destinatario, el enrutamiento y la entrega a través de la red correspondiente.

POST /api/v1/{partyId}/salesInvoice/send

El {partyId} en la URL es el identificador Peppol de la organización remitente (el proveedor). La solicitud contiene el documento XML como body (content-type application/xml). El PSB detecta automáticamente el formato del documento y lo valida. Puede entregar en cualquier formato soportado: UBL 2.1, NLCIUS, BIS Billing V3, PINT, CII, XRechnung, Factur-X, FatturaPA, ebInterface, Svefaktura, DICO, SETU y muchos más. El PSB transforma automáticamente el documento al formato esperado por el destinatario.

1. Upload: envíe el documento XML al endpoint
2. Validación: la PSB valida el documento contra el esquema XSD y las reglas de negocio
3. Enrutamiento: la PSB busca a través de SML/SMP cómo llegar al destinatario
4. Entrega: el documento se entrega a través del canal apropiado (Peppol, correo electrónico u otra red)
5. Actualización de estado: se recibe una notificación webhook con el estado de entrega

Importante: la PSB determina el destinatario en función del EndpointID en su documento XML. Si este elemento falta o contiene un identificador incorrecto, el envío falla con el estado InvoiceSentError. Asegúrese de que su sistema de origen complete correctamente el EndpointID. Más información sobre identificadores y enrutamiento en el artículo sobre identificadores Peppol.

La PSB admite idempotency a través del header de solicitud X-EConnect-DocumentId. Incluyendo un UUID propio en cada solicitud de upload, se previene el procesamiento duplicado:

X-EConnect-DocumentId: 550e8400-e29b-41d4-a716-446655440000

Si envía el mismo documentId de nuevo, la API retorna 409 Conflict, indicando al remitente que el documento ya ha sido procesado.

Importante: Utilice siempre un UUID/GUID como documentId. Nunca utilice el número de factura, ya que esto causa problemas si desea reenviar una versión corregida de la misma factura.

Antes de enviar una factura, puede verificar a través de queryRecipientParty si y cómo el destinatario es accesible:

POST /api/v1/{partyId}/salesInvoice/queryRecipientParty

En el cuerpo de la solicitud se pasa una lista de identificadores, por ejemplo ["0106:12345678"], o un objeto con partyIds y metaAttributes. Los parámetros de consulta opcionales son ?preferredDocumentTypeId y ?includeOptions.

La respuesta contiene información sobre:

• Si el destinatario está registrado en Peppol
• Qué tipos de documentos puede recibir el destinatario
• A través de qué Access Point el destinatario es accesible
• Qué canal utilizará la PSB para la entrega

Para búsquedas avanzadas que incluyen la URL del Access Point y el certificado AP, hay disponible una ruta separada:

GET /api/v1/peppol/deliveryOption?partyIds={id}&documentFamily=Invoice&isCredit=false

En caso de fallo en la entrega, la PSB aplica automáticamente un mecanismo de reintento:

• Hasta 8 intentos distribuidos en aproximadamente 35 horas
• Solo para errores de servidor 5xx (errores temporales en el lado receptor)
• Se publica un evento InvoiceSentRetry por cada intento
• En caso de fallo definitivo, se recibe un evento InvoiceSentError a través del webhook

Errores comunes al enviar:

Nota: SI-UBL 1.2 (Simpler Invoicing 1.2) no está permitido en la red Peppol desde el 1 de enero de 2024. Las facturas en este formato resultan en un InvoiceSentError. Utilice NLCIUS (SI-UBL 2.0) o Peppol BIS Billing V3. Compruebe el CustomizationID en su documento XML si encuentra este error.

Un upload exitoso retorna 200 OK con el identificador del documento en la PSB. Utilice este identificador para seguir el estado del documento a través de la API o a través de webhooks.

A diferencia de purchaseInvoice, el endpoint salesInvoice no tiene DELETE. Es una decisión deliberada, porque una factura de venta enviada o rechazada es un evento de vida relevante para auditoría: el documento sigue siendo rastreable en la pista de auditoría, incluso después de que el envío haya fallado.

Los clientes a veces preguntan si una factura de venta rechazada puede detenerse o eliminarse, por ejemplo después de haber abonado internamente la factura. La respuesta es:

• Error de validación (4xx, por ejemplo Invalid payload): la PSB coloca el documento en el estado final InvoiceSentError. No se ejecuta ningún reintento (solo los errores 5xx se reintentan). El documento no se entrega al destinatario. No se requiere ninguna acción en la PSB; el documento está en su estado final y se conserva 90 días con fines de auditoría.
• No es necesario un endpoint DELETE: como el documento ya no está activo y no se reintenta, no es necesario eliminarlo explícitamente para detener el envío.
• Enviar una corrección mediante un nuevo documento: si la factura original era incorrecta y ya había sido (parcialmente) entregada, utilice una nota de crédito o factura de corrección según el flujo contable estándar. El documentId original permanece como referencia en la pista de auditoría.

Esta diferencia de ciclo de vida entre salesInvoice (sin DELETE) y purchaseInvoice (con DELETE) proviene del rol: una factura saliente es una acción comercial registrada por el emisor que debe ser legalmente rastreable; una factura entrante puede eliminarse del sistema del receptor tras una descarga exitosa.

Al enviar una factura, el PSB también gestiona la declaración fiscal. En el marco de la directiva ViDA (VAT in the Digital Age), el PSB genera automáticamente un DRR (Digital Reporting Requirement) a partir de los datos de la factura y lo envía a la autoridad fiscal correspondiente. Como integrador, no necesita hacer nada adicional: el DRR se deriva de la misma factura que usted envía a través del endpoint habitual. Los mensajes de estado y los mensajes de reporting CTC están incluidos en el precio del documento.

Por defecto, la PSB selecciona automáticamente el mejor canal. Con el parámetro de consulta ?channel={hookId}, puede forzar un canal de entrega específico (por ej. una red específica o fallback de correo electrónico).

Los adjuntos (PDF, imágenes) pueden incrustarse como base64 en el documento UBL como AdditionalDocumentReference. La PSB procesa correctamente los adjuntos incrustados y los entrega junto con la factura.

Nota: El endpoint de envío acepta un máximo de 24 MB por solicitud (incluyendo overhead HTTP). Con adjuntos codificados en base64, el payload crece aproximadamente un 33%, por lo que un PDF de 18 MB resulta en una solicitud de aproximadamente 24 MB. Los payloads que excedan el límite son rechazados por el servidor web con HTTP 500 (no 413), antes de que se realice la validación de la aplicación. Reduzca los adjuntos grandes o envíelos a través de un canal separado.

Consejo: El estándar actual Peppol BIS Billing 3.0 admite un máximo de una OrderReference por factura. Si una factura se refiere a varios pedidos, se deben enviar varias facturas.

Consejo: Algunos destinatarios reportan errores en facturas con un prefijo de espacio de nombres XML (por ej. <urn:Invoice> en lugar de <Invoice>). Ambas formas son XML técnicamente válido según la especificación W3C. Si un destinatario cita esto como motivo de rechazo, no es un rechazo válido dentro de la red Peppol. El destinatario debe utilizar un parser XML que maneje correctamente tanto espacios de nombres prefijados como por defecto.

¿Desea probar primero si su documento es válido? Utilice la Validate API.

• Formatos de documento: UBL, CII y más
• Recibir una factura a través de la API
• Idempotency: prevenir uploads duplicados
• Configurar y asegurar webhooks
• NLCIUS: el estándar holandés de facturación electrónica
• Estructura de una factura UBL
• Crear y enviar una factura a través de la plataforma
• Estados de facturas en la plataforma
• Facturación electrónica con eConnect