Fundamentos de integración de API

Configura estos aspectos compartidos antes de integrar un recurso de la API de DEUNA. Las mismas reglas de entorno, red, reintentos y tiempos de espera se aplican a órdenes, pagos, usuarios, links de pago y suscripciones.

Entornos#

Sandbox y producción están aislados y usan credenciales, datos y endpoints de webhook diferentes.

Consulta Autenticación y entornos para conocer los tipos de credenciales, la rotación y los ejemplos de solicitudes.

Colección de Postman#

Usa la colección de Postman de DEUNA para explorar solicitudes antes de desarrollar un cliente.

Abrir la colección de DEUNA en Postman

1. Inicia sesión en Postman y crea un fork de la colección en tu espacio de trabajo.
2. Selecciona el entorno de sandbox o producción.
3. Configura merchant_id, public_api_keyy private_api_key con los valores de ese entorno.
4. Comienza con una operación del catálogo de endpoints.

Direcciones IP#

Prefiere una lista de dominios permitidos cuando tu política de red lo admita. Si tu receptor de webhooks o un proveedor de pagos o fraude exige una lista de IP permitidas, usa las siguientes direcciones.

Códigos de respuesta#

Las operaciones exitosas devuelven una respuesta 2xx . Una respuesta 4xx indica que deben cambiar la autenticación, los permisos, los datos o el estado del recurso. Una respuesta 5xx es un fallo temporal de DEUNA o del proveedor y solo debe reintentarse cuando sea seguro repetir la operación.

Usa la referencia de respuestas y códigos de error para identificar la causa, la política de reintentos y la acción correctiva.

Solicitudes idempotentes#

Envía un X-Idempotency-Key estable para cada operación distinta que cree o cambie el estado de un pago. Reutiliza la misma clave y el cuerpo idéntico al reintentar después de un fallo de red o un tiempo de espera del cliente. Usa una clave nueva para un intento de negocio nuevo.

X-Api-Key: YOUR_PRIVATE_API_KEY
X-Store-Code: STORE_CODE
X-Idempotency-Key: order_1042-attempt_1
Content-Type: application/json

Consulta Crear un pago para conocer el contrato y el ejemplo de reintento de compra.

Tiempos de espera del cliente#

Un tiempo de espera del cliente significa que dejó de esperar; no demuestra que el pago falló. El procesamiento puede continuar con controles de fraude, enrutamiento y el proveedor después de la desconexión.

Cuando una solicitud de pago vence:

1. Mantén bloqueado el fulfillment y marca el intento como pendiente de conciliación en tu sistema.
2. Conserva el ID de la orden, el cuerpo y la clave de idempotencia original.
3. Reintenta solo si la operación es elegible, con la misma clave y un cuerpo idéntico.
4. Concilia el estado final desde un gancho web verificado o una consulta de orden adecuada del catálogo de endpoints.
5. Muestra el resultado conciliado al comprador y resuelve cualquier anulación o reembolso requerido antes del fulfillment.