Saltar al contenido
Docs

Idempotencia

Por qué los POST de la API de partners de SLAN exigen Idempotency-Key, cómo elegirla y qué ocurre si la reutilizas.

Cuando una petición se corta a mitad de camino, no sabes si llegó. Reintentarla puede duplicar un usuario, una wallet o un cobro; no reintentarla puede perder la operación.

La cabecera Idempotency-Key resuelve esa duda: nos dices qué intención estás ejecutando, y nosotros garantizamos que esa intención se ejecute una sola vez.

Dónde es obligatoria

En los POST que crean un recurso:

Operación Qué crea
POST /v1/partner/users Un usuario final
POST /v1/partner/wallets Una wallet de cobro
POST /v1/partner/payment-links Un link de pago

Cómo se elige la clave

Un identificador único por intención. No por reintento: el reintento debe llevar la misma clave que el intento original, que es justo lo que hace que funcione.

Terminal window
CLAVE=5f1c9c3e-7c1a-4a2e-9a1e-2f0b6d5c4a31


# Intento 1: se corta la red y no sabes si llegó.
curl -X POST https://api.slan.mx/v1/partner/users \
  -H "x-api-key: slan_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $CLAVE" \
  -d '{"email":"ana.ramirez@example.com","externalRef":"tripto-user-4821"}'


# Intento 2: MISMA clave, mismo cuerpo. Es seguro.
curl -X POST https://api.slan.mx/v1/partner/users \
  -H "x-api-key: slan_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $CLAVE" \
  -d '{"email":"ana.ramirez@example.com","externalRef":"tripto-user-4821"}'

El segundo no crea un segundo usuario: devuelve la respuesta del primero.

Si derivas la clave de datos que ya tienes —por ejemplo, el identificador de la operación en tu sistema— te ahorras guardarla en algún sitio para poder reintentar.

Las tres reglas

Misma clave y mismo cuerpo: se reproduce la respuesta. Recibes exactamente lo que devolvió la primera vez, con la cabecera Idempotent-Replayed para que sepas que no se volvió a ejecutar.

Misma clave y cuerpo distinto: 422. Es una protección, no un capricho. Significa que reutilizaste por error una clave de otra operación; si lo permitiéramos, la segunda intención se perdería en silencio.

Clave nueva: se ejecuta. Aunque el cuerpo sea idéntico al de una llamada anterior. Dos cobros del mismo importe al mismo usuario son una situación legítima, y no nos corresponde decidir que es un error.

Cuánto dura

La clave se recuerda el tiempo suficiente para cubrir un reintento razonable, no para siempre. Si reintentas horas después con la misma clave, trátalo como una operación nueva y comprueba antes el estado con un GET.