Esta versión (v0.7) todavía no se publicó en npm.
Ir al contenido

Idempotencia ​

Las operaciones que mueven dinero (depósito, retiro, apuesta, orden, opt-in y claim de bono) envían el header Idempotency-Key. El gateway guarda la respuesta por 72 horas: repetir el request con la misma clave no duplica la operación.

El SDK genera la clave automáticamente (una por llamada) y la mantiene en el retry interno tras renovar la sesión. Si llamas al módulo directamente (enginex.deposits.createPix), para repetir con seguridad después de un error de red genera la clave antes del primer intento y pasa la misma en idempotencyKey, en las opciones de la llamada. En las mutations (abajo) el SDK se encarga de esto:

ts
import { isEnginexError } from '@getenginex/sdk'

const key = crypto.randomUUID() // one per operation, not per attempt
try {
  await enginex.deposits.createPix({ amount: 5000 }, { idempotencyKey: key })
} catch (e) {
  if (isEnginexError(e, 'NETWORK_ERROR')) {
    await enginex.deposits.createPix({ amount: 5000 }, { idempotencyKey: key }) // does not duplicate
  }
}

idempotencyKey forma parte de CallOptions y solo aplica a métodos idempotentes (los que mueven dinero); en los demás se ignora. Una cadena vacía se trata como ausente y el SDK genera la clave. Los paquetes de producto (@getenginex/sdk-igaming) siguen la misma regla: consulta Extensibilidad.

Cuándo el SDK reutiliza la clave ​

El gateway guarda la primera respuesta definitiva de cada clave por 72 horas y la repite para cualquier request con la misma clave. Por eso la clave solo debe reutilizarse cuando no sabes si el primer intento llegó. Las mutations del SDK (@getenginex/sdk/query, useEnginexMutation y los paquetes de producto) aplican esta regla por sí solas:

Resultado del intento¿Ambiguo?La clave...
NETWORK_ERROR, TIMEOUT (la respuesta no llegó)síse conserva para el próximo intento
Error con status >= 500síse conserva para el próximo intento
KEY_IN_USE (409: el intento anterior con la misma clave todavía se está procesando)síse conserva para el próximo intento (una clave nueva duplicaría la operación)
VALIDATION_ERROR después de un 2xx (la operación ocurrió, pero la respuesta llegó fuera de formato)síse conserva para el próximo intento (el gateway devuelve la misma respuesta)
Éxitonose descarta (el mismo valor de nuevo es una operación nueva)
Los demás 4xx (INSUFFICIENT_BALANCE, DEPOSIT_LIMIT_EXCEEDED, PAYMENT_FAILED, PAYLOAD_MISMATCH...)nose descarta
CONFIGURATION_ERRORnose descarta
ABORTED (cancelaste)nose descarta

El intento abierto guarda la entrada y la clave, y la comparación es por el contenido de la entrada (claves de objeto en cualquier orden, undefined omitido), no por el objeto. Así que un "reintentar" con mutate({ amount: 5000 }) literal, después de un 503, reutiliza la clave; una entrada distinta empieza un intento nuevo y descarta el anterior. Dos llamadas simultáneas con la misma entrada, en el mismo objeto de opciones, usan la misma clave.

Dónde vive el intento:

  • Core y TanStack: en cada objeto de opciones (m.deposits.createPix()); cada llamada a la fábrica tiene el suyo. En React, useEnginexMutation guarda el intento por instancia del hook, y sobrevive a las opciones recreadas en cada render (React).
  • orders.placeBatch (Predictions): el intento queda en cada resultado de createPredictionsMutations y guarda las claves de las órdenes incluso en un éxito parcial; consulta Órdenes.
  • withdrawals.confirmOtp: pasa el requestId devuelto por withdrawals.request (confirmOtp({ otp, requestId })). No va al gateway: solo separa los desafíos, y un desafío nuevo nunca reutiliza la clave del anterior.

ABORTED libera la clave

Un request cancelado puede haber llegado al gateway. Quien cancela y quiere repetir la misma operación pasa idempotencyKey (abajo); sin ella, la llamada siguiente es una operación nueva.

Otros códigos que puedes ver del gateway:

  • KEY_IN_USE (409): el primer intento todavía se está procesando (doble clic, otra pestaña). Espera y repite con la misma entrada: las mutations mantienen la clave (tabla de arriba) y el gateway devuelve la respuesta de la primera, si se procesó.
  • PAYLOAD_MISMATCH (422): la clave ya se usó con otro cuerpo (otro monto, otra clave PIX). Como el SDK renueva la clave cuando cambia la entrada, esto solo ocurre con una clave explícita reutilizada en otra operación: genera una por operación, nunca por pantalla.

Después de expirar ​

Después del expiresAt de un cobro PIX o de un código OTP de retiro, un nuevo pedido con la clave antigua devolvería el mismo cobro (o el mismo pedido) ya vencido. Como esas respuestas son éxitos, la clave ya se descartó: el próximo pedido es nuevo.

Clave explícita ​

Para repetir después de recargar la página, o después de un ABORTED, guarda la clave tú mismo y pasa idempotencyKey: gana sobre el intento del SDK y aplica a toda llamada de esas opciones. Genera una por operación, cuando el jugador confirma, no una por pantalla:

ts
const key = crypto.randomUUID() // one per operation, not per attempt
sessionStorage.setItem('pix-key', key)
await enginex.deposits.createPix({ amount: 5000 }, { idempotencyKey: key })

En mutations (m.deposits.createPix({ idempotencyKey })), la clave se lee cuando se llama a la fábrica y entra en las opciones del render, así que mutate debe ejecutarse después del render que la recibió; el ejemplo está en React.

La clave se aplica por usuario y por ruta: la misma cadena en deposits.createPix y en withdrawals.request son operaciones independientes, pero no es buena práctica reutilizarla.

Sin Web Crypto (crypto.randomUUID y crypto.getRandomValues ausentes), generar la clave rechaza con CONFIGURATION_ERROR. En HTTP en la LAN (origen inseguro, sin randomUUID), el SDK usa getRandomValues y sigue funcionando.

Métodos idempotentes ​

MétodoRuta
deposits.createPixPOST /deposits/pix
withdrawals.requestPOST /withdrawals
withdrawals.confirmOtpPOST /withdrawals/confirm-otp

En los demás métodos (incluidos withdrawals.cancel y pixKeys.*), idempotencyKey se ignora: el gateway no aplica idempotencia a esas rutas.