Idempotencia

En sistemas de pagos, los reintentos por errores de red son inevitables. Sin idempotencia, un reintento puede crear cobros duplicados o cuentas duplicadas. La API ofrece dos mecanismos complementarios:

1. Idempotency-Key (recomendado)

Cualquier POST, PUT, PATCH o DELETE puede llevar el header Idempotency-Key con un identificador único elegido por el integrador (UUID, hash, o cualquier string ≤ 255 caracteres).

Semántica

Situación	Respuesta
Primera vez con esa key	Se ejecuta normalmente. La key + el resultado quedan cacheados por 24 horas.
Mismo Idempotency-Key + mismo cuerpo de request, dentro de las 24h	Se devuelve el mismo response sin volver a ejecutar la operación.
Mismo Idempotency-Key + cuerpo distinto	409 idempotency-key-reuse. Casi siempre indica un bug en el integrador.
Pasadas las 24h	La key se reusa como nueva.

Scope

La caché de idempotencia está alcanzada por (apiKeyId, idempotencyKey). Significa que:

• Dos integradores pueden usar la misma key sin colisionar.
• Mismo integrador no puede reusar la key entre rotaciones de API key (no es un problema en la práctica).

Cuándo es obligatorio

Recurso	Recomendado	Obligatorio
POST /v1/clients	Sí	No (ver §2, upsert nativo)
POST /v1/associates	Sí	No (UNIQUE en taxId + customer)
POST /v1/receivable-accounts	Sí	Sí (es la única forma de recuperar el ID si el response se pierde antes de leerlo)
POST /v1/receivables	Sí	Sí (especialmente para flujos masivos del ERP)
POST /v1/webhooks	Sí	No
PATCH /v1/receivables/{id}/status	Sí	No

Ejemplo

POST /v1/receivables
Authorization: Bearer eyJ...
Idempotency-Key: erp-fac-2026-05-15-00012345
Content-Type: application/json

{
  "receivableAccountId": 4242,
  "amount": 45000.00,
  "currencyCode": "ARS",
  "receivableType": "INVOICE",
  "legalNumber": "0001-00012345",
  "issueDate": "2026-05-15",
  "dueDate": "2026-05-30"
}

Si la respuesta se pierde por timeout, reenviá el mismo request con la misma Idempotency-Key y recibirás el mismo response sin duplicar el comprobante.

Política recomendada (How-to)

Generá la Idempotency-Key de forma determinística a partir de identificadores estables del ERP:

erp-{empresa}-{recurso}-{externalId}
erp-distribuidora-demo-fac-202605-00012345

Esto te permite reintentar desde cero, sin riesgo de duplicación dentro de la ventana de 24h. Para retries más allá de 24h la protección depende del recurso (ver §2): algunos recursos son idempotentes nativamente, otros requieren manejar conflictos 409.

Key y body son inseparables

Si cambiás el body de un reintento (corregís un monto, agregás un campo), también tenés que cambiar la Idempotency-Key. Reusar la misma key con un body distinto devuelve 409 idempotency-key-reuse.

2. Comportamiento ante colisión de claves de negocio

Más allá del Idempotency-Key (que protege dentro de 24h), algunos recursos tienen claves de negocio que también detectan duplicados — pero el comportamiento varía por recurso:

Recurso	Clave de negocio	Comportamiento ante colisión
POST /v1/clients	(documentType, documentNumber, branchExternalCode) por customer	Idempotente: 200 OK con el cliente existente.
POST /v1/associates	taxId por customer	Idempotente: 200 OK con el asociado existente.
POST /v1/receivable-accounts	(clientId, associateId, currencyCode) por customer	409 receivable-account-already-exists con existingResourceId en el body. El integrador decide si usar el existente o cancelarlo.
POST /v1/receivables	legalNumber por customer (cuando se envía)	409 duplicated-legal-number si el legalNumber ya existe para ese customer. Si no enviás legalNumber, no hay clave de negocio y el comprobante se crea sin chequeo de duplicado.

Patrones sugeridos por recurso

• Clients y associates: usá la idempotencia nativa. Si la sincronización inicial postea siempre los mismos datos, no necesitás manejar errores especiales — alcanza con que documentType + documentNumber (clients) o taxId (associates) sean estables en tu ERP.
• Receivable-accounts: manejá explícitamente el 409 receivable-account-already-exists recuperando el existingResourceId del response — ese es el recurso que tu ERP debería seguir usando.
• Comprobantes: combiná Idempotency-Key determinística (cubre reintentos dentro de 24h) con una clave de negocio única en tu lado (por ejemplo externalId con el número de factura) que te permita consultar antes de postear en flujos masivos donde un retry tardío podría duplicar.