Saltar al contenido principal
En esta página

Utiliza una clave de idempotencia cuando un fallo de red o un tiempo de espera del cliente dejan incierta la respuesta de una solicitud que cambia de estado. DEUNA asocia la clave con la operación y el cuerpo de la solicitud, y luego reproduce la respuesta almacenada en lugar de procesar la misma operación nuevamente.

Flujo de reintento#

01 · merchant
Guarda una única clave
Genera un UUID v4 y guárdalo con la operación comercial antes de enviar la solicitud.
02 · DEUNA
Procesa o reproduce
DEUNA procesa la primera solicitud, o reproduce su resultado almacenado cuando la misma clave y cuerpo llegan nuevamente.
03 · merchant
Concilia el resultado
Utiliza la respuesta y el estado actual del pedido para decidir si la operación ha finalizado o puede ser reintentada de forma segura.

El comerciante es responsable de la generación, persistencia y temporización de reintentos de las claves. DEUNA es responsable de la asociación entre la clave, la operación, el cuerpo de la solicitud y la respuesta almacenada dentro del período de retención documentado.

Operaciones soportadas#

enviar X-Idempotency-Key con las siguientes operaciones públicas:

OperaciónMétodo y rutaReferencia
Crear un pedido · Flujo opcionalPOST /merchants/ordersCrear un pedido
Crear un pago · Compra V2POST /v2/merchants/orders/purchaseCrear un pago
Capturar un pago autorizadoPOST /v2/merchants/orders/{order_token}/captureCapturar un pago
Anular una autorizaciónPOST /merchants/orders/{order_token}/voidAnular una autorización
Reembolsar un pagoPOST /v2/merchants/orders/{order_token}/refundReembolsar un pago

No asuma que todas POST las operaciones soportan la idempotencia. Utilice la lista de operaciones anterior o verifique si la referencia del punto final incluye... X-Idempotency-Key header.

Generar y persistir la clave#

Generar un UUID v4 en su backend comercial para cada operación distinta. Almacénelo junto con su propio registro de operación antes de llamar a DEUNA.

Generar una clave en Node.jsJavaScript
const idempotencyKey = crypto.randomUUID();

Siga estas instrucciones:

  • Reutilizar la misma clave solo al intentar la misma operación.
  • Enviar el mismo cuerpo de solicitud en cada intento. DEUNA compara el hash del cuerpo, por lo que incluso un cuerpo semánticamente equivalente, pero serializado de forma diferente, puede ser rechazado.
  • Generar una nueva clave para un nuevo pago, captura, cancelación, reembolso o intento de creación de pedido.
  • Generar una nueva clave cuando se corrigen los datos de la solicitud después de una validación o error de negocio.
  • No derivar claves de una secuencia corta que pueda colisionar en diferentes sistemas o entornos.

La clave está restringida al comerciante y a la operación, pero su integración debe tratarla como única a nivel global y nunca reutilizarla para otras acciones.

Enviar la solicitud#

Agregue la clave a la solicitud original y a cada intento de reintento de esa solicitud. Este ejemplo de "Purchase V2" utiliza un token de pedido que la integración ya ha creado:

curl --request POST \
  --url https://api.sandbox.deuna.io/v2/merchants/orders/purchase \
  --header "X-Api-Key: YOUR_PRIVATE_API_KEY" \
  --header "X-Idempotency-Key: 9f510c4a-0f7d-4c31-94c5-590b85e4d231" \
  --header "Content-Type: application/json" \
  --data '{
    "order_token": "ORDER_TOKEN",
    "payer_info": {
      "email": "buyer@example.com",
      "external_user_id": "customer_1042"
    },
    "payment_source": {
      "method_type": "credit_card",
      "payment_method": "PAYMENT_METHOD_TOKEN"
    }
  }'

Si la respuesta X-Idempotency-Replay: true, DEUNA devuelve el resultado almacenado para una solicitud anterior con la misma clave y cuerpo. Maneje su código de estado y payload exactamente como lo haría con la respuesta original.

Comprenda el período de retención.#

La asociación clave-cuerpo comienza cuando DEUNA recibe la clave por primera vez. La ventana de reproducción de la respuesta comienza cuando DEUNA almacena el resultado completo, y su comportamiento depende de ese resultado:

Resultado originalComportamiento de reproducción
Respuesta exitosaDEUNA almacena la respuesta para De 24 horas por defecto, después de que la operación se completa. Un reintento con la misma clave y cuerpo durante ese período devuelve el código de estado, los encabezados y el payload almacenados.
4xx o 5xx respuestaDEUNA almacena la respuesta de error durante aproximadamente 2 segundos para absorber duplicados inmediatos. La asociación entre la clave y el cuerpo de la solicitud original permanece durante todo el período de 24 horas.
Solicitud en cursoUna solicitud concurrente espera brevemente el primer resultado. Si la primera solicitud aún está en ejecución, DEUNA puede devolver HTTP 409 con IS-4409.

Después de que expire el período de retención de la respuesta exitosa, la misma clave se puede tratar como una nueva operación. Nunca dependa de este comportamiento: cree una nueva clave para cada nueva operación comercial, incluso cuando una clave anterior haya expirado.

Para una respuesta de error, no reutilice la clave con los datos de solicitud corregidos. Debido a que la asociación del cuerpo original permanece activa, el cuerpo modificado se devuelve IS-4401 hasta que finalice el período de retención. Corrija la solicitud y envíela como una nueva operación con una nueva clave.

Maneje los reintentos y los conflictos#

SituaciónQué devuelve DEUNAQué debe hacer su integración
Misma clave y mismo cuerpo después de una solicitud exitosa completadaLa respuesta almacenada con X-Idempotency-Replay: trueAceptar la respuesta y reconciliar el estado actual del pedido cuando no es final.
Misma clave con un cuerpo diferenteHTTP 400, código IS-4401No intente de nuevo esta combinación. Use una nueva clave solo cuando el cuerpo modificado represente una operación corregida o nueva.
Duplicado que llega mientras la primera solicitud está en cursoHTTP 409, código IS-4409, cuando finaliza la espera en cursoRetroceda y luego intente de nuevo la solicitud exacta con la misma clave. Reconcilie el pedido original antes de iniciar un nuevo intento.
Se ha excedido el límite de velocidadHTTP 429, lo que puede incluir código IS-4429Cumpla Retry-After cuando esté presente, luego intente de nuevo con el mismo cuerpo y clave.
Tiempo de espera o pérdida de conexión del clienteEl cliente puede no recibir respuesta, aunque el procesamiento continúaConserve la clave y el cuerpo, reconcilie el pedido y solo intente de nuevo según el procedimiento documentado de tiempo de espera.
Validación o error de negocio no recuperableun 4xx respuestaCorrija la solicitud y utilice una nueva clave. No intente de nuevo un cuerpo modificado bajo la antigua clave.

Utilice un retroceso exponencial limitado con jitter. No envíe múltiples intentos concurrentes para la misma operación de negocio.

Ver Errores de la API para el modelo de código de respuesta y tiempos de espera del cliente para el procedimiento de reconciliación.

Verifique el comportamiento en el entorno de prueba#

  1. Envíe una solicitud válida y compatible a https://api.sandbox.deuna.io con una nueva clave UUID v4.
  2. Guarde su código de estado, encabezados de respuesta y payload.
  3. Envíe la misma solicitud exactamente nuevamente con la misma clave y cuerpo.
  4. Verifique que la segunda respuesta tenga el mismo resultado e incluya X-Idempotency-Replay: true.
  5. Durante una prueba negativa separada, modifique el cuerpo pero mantenga la clave y verifique que DEUNA devuelva un código HTTP 400 con IS-4401.

No reutilice ninguna de las claves de prueba para otra operación en el entorno de prueba.

Continúe con la integración#