Idempotencia

Las llamadas de red fallan de formas ambiguas: una solicitud expira después de que el servidor la procesó pero antes de que la respuesta te llegara, y no puedes saber si tuvo éxito. La idempotencia es lo que permite reintentar de forma segura en esa situación — una solicitud repetida produce el mismo resultado que la primera, en lugar de un duplicado.

La API de Remesas no usa un encabezado Idempotency-Key. En su lugar, cada endpoint de creación es idempotente según el externalId que proporcionas — la misma convención en todas partes, así que un reintento tras un timeout es seguro siempre que envíes un externalId estable. Esta página es la referencia única de qué operaciones son seguras de repetir y cómo.

La única regla: envía tu propio externalId único en cada creación (remitente, beneficiario, transacción). Es la clave de idempotencia — lo que convierte un reintento ambiguo en uno seguro.

Creación de Persona — Idempotente en externalId

Crear un remitente o beneficiario es idempotente cuando proporcionas un externalId:

• POST /organizations/{tenant}/v2/senders
• POST /organizations/{tenant}/v2/beneficiaries
• POST /organizations/{tenant}/v2/people (obsoleto)

Si una persona con el mismo externalId ya existe en tu tenant, la creación devuelve la persona existente con HTTP 200 — no se crea ningún duplicado. Una persona realmente nueva devuelve 201.

Primera llamada → 201 Created   (persona nueva, id abc-123)
Reintento       → 200 OK        (se devuelve la misma persona abc-123, no se crea nada nuevo)

Envía siempre tu propio externalId al crear personas. Es tu red de seguridad para reintentos: sin él, una creación reintentada tras un corte de red produce un segundo registro de persona para el mismo individuo.

Desactivación de Cuenta — Idempotente

Desactivar una cuenta de fondeo o una cuenta de destinatario es seguro de repetir:

• DELETE /organizations/{tenant}/payout/participants/{participantId}/fundingAccounts/{fundingAccountId}
• DELETE /organizations/{tenant}/payout/recipientAccounts/{recipientAccountId}

Desactivar una cuenta que ya está inactiva tiene éxito y devuelve la cuenta sin cambios (isActive: false). No hay error en la segunda llamada ni cambio de estado adicional.

Creación de Transacción — Idempotente en externalId

POST /organizations/{tenant}/fx/transactions es idempotente cuando proporcionas un externalId. Un reintento con el mismo externalId devuelve la transacción existente con HTTP 200 y no inicia un segundo payout; una transacción realmente nueva devuelve 202 Accepted.

Primera llamada → 202 Accepted   (transacción nueva, id tx-abc)
Reintento       → 200 OK         (se devuelve la misma transacción tx-abc, sin segundo payout)

Como aquí se mueve dinero, este es el lugar más importante para manejar bien los reintentos:

• Envía siempre un externalId único por transacción pretendida. Es la clave de idempotencia — sin él, una creación reintentada tras un corte de red inicia un segundo payout.
• Reutiliza el mismo externalId al reintentar la misma transacción pretendida. La coincidencia es por tenant y está respaldada por una restricción de unicidad, así que incluso dos reintentos concurrentes se resuelven en una sola transacción.
• Un timeout ahora es seguro de reintentar siempre que envíes el mismo externalId — el reintento crea la transacción (si la primera nunca llegó) o devuelve la ya creada.

Trata un 200 en este endpoint como "ya creada, aquí está" y un 202 como "recién aceptada" — ambos son éxito. Consulta el estado de la transacción devuelta en cualquier caso.

Cotizaciones

Las cotizaciones no son idempotentes y no están pensadas para serlo — cada POST /payout/quotes genera una cotización nueva con su propio id y vencimiento. No hay nada que deduplicar: solicita una cotización nueva cuando la necesites, y nunca caches ni reutilices un quoteId entre transacciones. Ver Cotizaciones (FX).

Lecturas

Todos los endpoints GET son naturalmente idempotentes y sin efectos secundarios — reintenta libremente.

Resumen

La API de Wallet es un producto aparte y sí usa un encabezado Idempotency-Key explícito en sus endpoints de escritura — ver la Referencia de la API de Wallet. La guía de esta página es solo para la API de Remesas.