Conceptos

Idempotencia

Una falla de red deja la duda de si el pedido llegó. La idempotencia permite reintentarlo sin crear dos veces el mismo turno o la misma consulta.

El header Idempotency-Key

Todas las operaciones POST aceptan el header Idempotency-Key: un valor único por operación, como un UUID v4. Kuida guarda el resultado del primer pedido con esa clave y, si llega otro con la misma, devuelve esa respuesta tal cual, sin volver a ejecutar nada, con el header Idempotent-Replayed: true.

POST /v1/visits

curl https://www.kuida.ar/api/v1/visits \
  -H "Authorization: Bearer kd_test_…" \
  -H "Idempotency-Key: 5f0c2d4e-8a61-4c1f-9d7b-2e3a4b5c6d7e" \
  -H "Content-Type: application/json" \
  -d '{
  "patient": { "phone": "+54 9 342 555 0000" },
  "visitedAt": "2026-10-05T10:45:00-03:00",
  "externalId": "turno-123"
}'

Los SDKs mandan una Idempotency-Key generada en cada POST y la reusan en sus propios reintentos. Pasarla explícitamente, con la opción por pedido de cada SDK, sirve cuando el reintento lo hace su sistema más tarde, por ejemplo desde una cola.

Reglas

Mismo pedido, misma clave: ResultadoLa respuesta original, con Idempotent-Replayed: true.
Misma clave con otro método, ruta o cuerpo: Resultado400 idempotency_key_reused.
Misma clave mientras el primer pedido sigue en curso: Resultado409 idempotency_key_in_use: reintentar en unos segundos.
El primer pedido terminó con 5xx: ResultadoNo se guarda: el reintento con la misma clave se ejecuta de nuevo.
El pedido falló la validación (400) o la autenticación: ResultadoNo se guarda: se puede corregir y reenviar con la misma clave.
Pasaron más de 24 horas: ResultadoLa clave vence y se puede volver a usar.

Situación	Resultado
Mismo pedido, misma clave	La respuesta original, con Idempotent-Replayed: true.
Misma clave con otro método, ruta o cuerpo	`400` idempotency_key_reused.
Misma clave mientras el primer pedido sigue en curso	`409` idempotency_key_in_use: reintentar en unos segundos.
El primer pedido terminó con 5xx	No se guarda: el reintento con la misma clave se ejecuta de nuevo.
El pedido falló la validación (400) o la autenticación	No se guarda: se puede corregir y reenviar con la misma clave.
Pasaron más de 24 horas	La clave vence y se puede volver a usar.

GET, PATCH y DELETE ignoran el header: leer, actualizar con los mismos valores o borrar dos veces da el mismo resultado.

Identidad natural

Además de la Idempotency-Key, varios objetos se reconocen por un dato propio. Mandar dos veces lo mismo devuelve el objeto existente aunque no haya clave:

Pacientes: el teléfono y, si no hay coincidencia, el DNI.
Turnos y consultas: el externalId que les asigna su sistema.
Eventos de POST /v1/events: el id del evento.

Recomendación

Mandar siempre externalId en turnos y consultas. Es la protección más simple contra duplicados y permite encontrar el objeto después con el filtro externalId de cada lista.

Cómo se ve una respuesta repetida

Headers de la respuesta

HTTP/1.1 200 OK
Idempotent-Replayed: true
Request-Id: req_Nw3xQ2c9b8f7a6e5d4c3b2a1
Kuida-Version: 2026-09-28