Idempotencia

Qué POST la requieren

La Idempotency-Key es requerida en los POST que crean, cobran o mandan algo a una persona. Sin ella la respuesta es 400 IDEMPOTENCY_KEY_REQUIRED:

Opcional quiere decir que si la mandas se honra igual (un reintento devuelve la primera respuesta), y si no la mandas la petición se procesa sin protección contra duplicados.

Los recordatorios (remind y remind-all) la exigen aunque además tienen su propio freno de un recordatorio cada 4 horas por firmante: la llave evita que un reintento de red mande dos correos; el freno evita que tu código insista de más.

No la usan:

• GET — ya son idempotentes por naturaleza.
• PATCH y DELETE — idempotentes por definición (el estado final es el mismo).
• Los POST que no la declaran: POST /v3/folders, POST /v3/documents/{id}/fields:assign-role, POST /v3/templates/{id}/validate-values, POST /v3/constancias/verify, POST /v3/devices/enroll y el init de una sesión de firma.

Cómo funciona

La primera vez que llega una key, AllSign procesa la petición normalmente y guarda la respuesta asociada a esa key. Si vuelve a llegar la misma key con el mismo cuerpo, no reprocesa: te devuelve la respuesta guardada íntegra (mismo status, mismo body), con el header Idempotency-Replayed: true para que sepas que fue un replay.

HTTP/1.1 201 Created
Idempotency-Replayed: true
Content-Type: application/json

{ "id": "doc_...", "status": "draft" }

Para decidir si dos peticiones son "la misma", AllSign calcula un fingerprint sobre los bytes crudos del cuerpo (no sobre el JSON normalizado). Reintenta con exactamente el mismo payload que enviaste la primera vez — un cambio de espacios o de orden de campos cuenta como cuerpo distinto.

Respuestas de conflicto

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "https://allsign.io/developers/docs/errors#IDEMPOTENCY_KEY_IN_PROGRESS",
  "title": "Conflict",
  "status": 409,
  "code": "IDEMPOTENCY_KEY_IN_PROGRESS",
  "detail": "A request with this Idempotency-Key is still in progress.",
  "retryAfter": 2,
  "requestId": "req_..."
}

Qué se cachea y por cuánto

No todas las respuestas se guardan para replay. Solo se cachean los resultados determinísticos: si reintentar puede dar un resultado distinto, no tiene sentido guardar el anterior.

Las keys se retienen 24 horas. Dentro de esa ventana, reintentar con la misma key te devuelve la respuesta guardada; después, esa key se libera y una petición nueva se procesa desde cero. Genera una key por operación lógica y no la reutilices para operaciones diferentes.