ProductoDesarrolladoresConocimiento
Plataforma Control
Enviar un pedido a través de la API

Enviar un pedido UBL a través de la API PSB: endpoint, perfiles, idempotency y seguimiento de estado.

Con la API PSB puede enviar órdenes de compra (purchase orders) a sus proveedores a través de la red Peppol. El proceso funciona de manera similar al envío de facturas: envía un documento XML UBL Order a la API, y el PSB se encarga de la validación, el enrutamiento y la entrega.

Endpoint
POST /api/v1/{partyId}/purchaseOrder/send

La solicitud contiene el documento XML UBL Order en el body con content-type application/xml. El {partyId} es el identificador Peppol de la organización remitente (el comprador).

Perfiles de pedido

El PSB soporta dos perfiles de pedido Peppol:

PerfilProfileIDUsoOrder Onlyurn:fdc:peppol.eu:poacc:bis:order_only:3Pedido unidireccional sin responseAdvanced Orderingurn:fdc:peppol.eu:poacc:bis:advanced_ordering:3Proceso de pedido completo con response, modificaciones y anulaciones

Con Order Only, el comprador envía un pedido y el proceso termina. Con Advanced Ordering, el proveedor puede responder con una Order Response, y el comprador puede modificar o anular el pedido posteriormente.

Consejo: utilice el perfil Advanced Ordering si desea que el proveedor confirme el pedido o si quiere poder modificar los pedidos posteriormente.

Flujo básico
  1. Carga: envíe el documento XML UBL Order al endpoint
  2. Validación: el PSB valida el documento según el esquema XSD y las reglas de negocio
  3. Enrutamiento: el PSB busca mediante SML/SMP cómo llegar al destinatario
  4. Entrega: el documento se entrega vía Peppol al proveedor
  5. Actualización de estado: usted recibe un webhook OrderSent con el estado de entrega
Idempotency

Utilice el header X-EConnect-DocumentId para evitar el procesamiento duplicado:

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

Si envía el mismo documentId nuevamente, la API devuelve 409 Conflict. Utilice siempre un UUID/GUID, nunca un número de pedido.

Gestión de errores

En caso de entrega fallida, el PSB aplica automáticamente reintentos:

  • Máximo 8 intentos distribuidos en aproximadamente 35 horas
  • Solo en caso de errores de servidor 5xx (errores temporales en el lado receptor)
  • Por cada intento se publica un evento OrderSentRetry
  • En caso de fallo definitivo, recibirá un evento OrderSentError
ErrorCausaSoluciónError de validación (4xx)El documento no cumple con el estándar PeppolVerifique el documento con la Validate APIDestinatario no encontradoIdentificador no registrado en PeppolVerifique mediante queryRecipientParty si el proveedor puede recibir pedidos409 ConflictUn documento con este documentId ya fue procesadoNo se requiere acción
Topics webhook

Configure webhooks para los siguientes topics para seguir el proceso de pedido:

TopicCuándoOrderSentPedido entregado con éxitoOrderSentRetryNuevo intento de entregaOrderSentErrorEl pedido no pudo ser entregadoOrderResponseReceivedEl proveedor ha respondido al pedidoOrderChangeReceivedSe ha recibido una modificación del pedidoOrderCancellationReceivedSe ha recibido una anulación del pedido
Respuesta

Una carga exitosa devuelve 201 Created con el ID del documento en el PSB. Utilice este ID para seguir el pedido a través de la API o mediante webhooks.

Preguntas frecuentes
¿Cuándo elijo Order Only y cuándo Advanced Ordering?

Order Only (urn:fdc:peppol.eu:poacc:bis:order_only:3) es un pedido unidireccional sin flujo de mensajes adicional. Advanced Ordering (urn:fdc:peppol.eu:poacc:bis:advanced_ordering:3) es necesario cuando el proveedor debe responder con una Order Response o cuando desea modificar o cancelar pedidos posteriormente. Elija Advanced si necesita ese proceso completo.

¿Cómo evito el procesamiento duplicado al enviar un pedido?

Envíe el encabezado X-EConnect-DocumentId con un UUID o GUID único. Si reutiliza el mismo documentId, la API responde con 409 Conflict. No utilice un número de pedido como clave de idempotencia, ya que no está previsto para este mecanismo.

¿Qué sucede con los fallos de entrega temporales y qué webhooks recibo?

Ante errores 5xx en el lado receptor, el PSB reintenta automáticamente la entrega (hasta 8 intentos en aproximadamente 35 horas). Verá OrderSentRetry por cada intento y OrderSentError en caso de fallo definitivo. En caso de éxito, recibirá OrderSent.

Consulte la especificación API completa en psb.econnect.eu para todos los parámetros y ejemplos de payloads.

Probar en la API

Artículos relacionados
PreviousSelf-billing recibir
NextRecibir pedido