Primeros pasos
Peticiones repetidas
Qué pasa si envías dos veces lo mismo y cómo evitar acreditar dos veces un depósito.
Las redes fallan: una petición puede llegar al servidor y perderse la respuesta, o un webhook puede entregarse dos veces. La API está pensada para que repetir sea seguro en los dos sentidos.
Idempotency-Key solo en retiros
La cabecera Idempotency-Key solo la acepta Crear retiro, donde la idempotencia es obligatoria. En el resto de rutas, la protección contra duplicados viene de cómo está hecha cada una, como se explica abajo.
De tu servidor a la API#
| Ruta | ¿Se puede repetir? | Qué pasa |
|---|---|---|
RutaPOST /v1/customers | ¿Se puede repetir?Sí | Qué pasaEs idempotente por external_id: la primera vez responde 201; las siguientes, 200 con el mismo cliente y la misma dirección. |
RutaCualquier GET | ¿Se puede repetir?Sí | Qué pasaSolo lee. |
RutaPOST /v1/quotes | ¿Se puede repetir?Sí | Qué pasaNo crea cobros. Cada llamada recalcula con el gas del momento. |
RutaPOST /v1/payouts | ¿Se puede repetir?Sí, con la misma clave | Qué pasaIdempotente por external_id (o Idempotency-Key): repetir devuelve el mismo retiro con 200. Ver Retiros. |
RutaPOST /v1/payouts/quote | ¿Se puede repetir?Sí | Qué pasaNo crea nada ni reserva saldo. |
RutaPOST /v1/payouts/return | ¿Se puede repetir?No | Qué pasaCada llamada devuelve otra vez ese monto a la tesorería. Si no viste la respuesta, consulta el saldo antes de repetir. |
RutaPATCH /v1/me | ¿Se puede repetir?Sí | Qué pasaDeja el mismo valor final. |
RutaPOST /v1/events/{id}/resend | ¿Se puede repetir?Con cuidado | Qué pasaCada llamada pone en cola un envío más del mismo evento. |
RutaPOST /v1/webhook/test | ¿Se puede repetir?Con cuidado | Qué pasaCada llamada crea un evento de prueba nuevo. |
RutaPOST /v1/api-keys | ¿Se puede repetir?No | Qué pasaCada llamada crea otra clave. Si no viste la respuesta, lista las claves y revoca la que sobre. |
RutaPOST /v1/webhook/secret/rotate | ¿Se puede repetir?No | Qué pasaCada llamada genera un secreto distinto e invalida el anterior. |
De la API a tu servidor#
Cada evento tiene un id estable: el mismo aviso lleva siempre el mismo id, en el primer envío, en cada reintento y en los reenvíos manuales. También viene en la cabecera X-Pasarela-Event-Id.
- Guarda el
idde cada evento que proceses, con una restricción de unicidad en tu base de datos. - Si llega un
idque ya tienes, responde200y no hagas nada más. - Como segunda defensa, acredita por
data.deposit.id: un depósito se acredita una sola vez, aunque te lleguen varios eventos sobre él.
Un depósito tampoco se duplica del lado de la pasarela: se identifica por la transacción y su posición dentro de ella (tx_hash + log_index), así que la misma transferencia nunca genera dos depósitos.