Idempotencia

El problema

Envías un aviso y la conexión se corta antes de recibir la respuesta. ¿Se creó o no? Si lo vuelves a enviar sin más, puede que tengas dos avisos y que salgan dos unidades al mismo domicilio. Si no lo envías, puede que el paciente se quede sin visita.

La cabecera Idempotency-Key resuelve esto: con ella, repetir la misma alta es seguro.

Cómo funciona

Genera un identificador único para cada alta en tu sistema y envíalo en la cabecera Idempotency-Key de POST /visits. Si tienes que repetir la petición, repítela con la misma clave y el mismo cuerpo.

curl -X POST "$SERAD_API_URL/visits" \
  -H "X-Api-Key: $SERAD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-exp-2026-004512-1" \
  -d @aviso.json

• La clave es tuya: hasta 200 caracteres, cualquier texto. Más larga, 400 con el tipo /errors/provider-api/idempotency-key-invalid.
• Las claves valen por API key: la misma Idempotency-Key enviada con dos claves de API distintas son dos operaciones distintas.
• Se recuerdan durante 24 horas. Pasado ese tiempo, la misma clave crearía un aviso nuevo.
• «El mismo cuerpo» se compara por su contenido JSON, no por los bytes: el orden de los campos o los espacios no importan.

Cómo elegir la clave

La clave tiene que identificar la intención de crear este aviso, no la petición HTTP:

• ✅ Algo que ya tienes y que es único para ese aviso: crm-<nº de expediente>-<nº de aviso del expediente>, o un UUID que generas y guardas junto al aviso antes de llamar a la API.
• ❌ Un UUID nuevo en cada intento: entonces cada reintento es una alta nueva y la idempotencia no sirve de nada.
• ❌ Solo el nº de expediente, si un mismo expediente puede tener varios avisos (por ejemplo, una visita hoy y una cura la semana que viene).

Reintentos seguros

Con la clave, la estrategia de reintento de un alta queda así:

1. Genera y guarda la Idempotency-Key con el aviso pendiente en tu base de datos.
2. Envía POST /visits.
3. Si la respuesta es 201 o 200: guarda el id del aviso. Listo.
4. Si es un error de red, un tiempo de espera agotado, un 429 o un 5xx: reintenta con la misma clave y el mismo cuerpo, con espera exponencial (ver límites de uso).
5. Si es un 409 idempotency-in-progress: espera unos segundos y reintenta igual.
6. Si es un 400, 401, 403 o 409 idempotency-key-reused: no reintentes; es un error que hay que corregir.