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.

AmbientesPreguntar a Athia sobre esto#

El entorno de pruebas y producción son aislados y utilizan credenciales, datos, conexiones con proveedores y estado de pago diferentes.

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

Colección de PostmanPreguntar a Athia sobre esto#

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 IPPreguntar a Athia sobre esto#

Prefiera la lista de dominios permitidos cuando su política de red lo permita. Si un proveedor de pagos o fraude requiere la lista de direcciones IP, utilice las direcciones a continuación.

Códigos de respuestaPreguntar a Athia sobre esto#

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 idempotentesPreguntar a Athia sobre esto#

Envía un X-Idempotency-Key para cada operación compatible que crea o modifica el estado de pago. Reutilice la misma clave y el cuerpo de la solicitud idéntico byte a byte al reintentar después de un fallo de red o un tiempo de espera del cliente. Utilice una nueva clave para un nuevo intento de negocio.

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

Las respuestas exitosas se conservan durante 24 horas por defecto. Leer Solicitudes idempotentes Para los endpoints soportados, retención de respuestas de error, encabezados de retransmisión, conflictos y verificación en el entorno de pruebas.

Tiempos de espera del clientePreguntar a Athia sobre esto#

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. Reconcile el estado final a través del método soportado modelo de procesamiento asíncrono y una búsqueda de orden apropiada en el catálogo de endpoints.
5. Muestra el resultado conciliado al comprador y resuelve cualquier anulación o reembolso requerido antes del fulfillment.