Idempotencia

A volumen, reintentar es lo normal: un cliente al que se le venció el tiempo de espera manda la misma petición otra vez. Para que eso no cree dos documentos, dos solicitudes o dos incidentes, cada POST que crea acepta una cabecera Idempotency-Key:

curl -X POST https://www.datrus.cl/api/v1/tasks \
  -H "Authorization: Bearer dtr_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2b7e4a9c-0d1f-4c6e-9a3b-8f5d2e1c7a90" \
  -d '{ "phase": 2, "title": "Cerrar el inventario" }'

Las reglas

• Misma llave, mismo cuerpo: recibes la respuesta guardada, con la cabecera Idempotent-Replayed: true. No se crea nada nuevo.
• Misma llave, cuerpo distinto: 422 idempotency_key_reused. La llave se usó para otra cosa.
• La llave vive 24 horas por empresa y mide hasta 255 caracteres. Un UUID v4 nuevo por cada intento distinto es la elección correcta.
• Sin la cabecera, la petición corre normal. La documentación y las herramientas la mandan siempre; te recomendamos lo mismo.

Qué llave usar

Una que identifique la intención, no el instante: si tu sistema reintenta la creación de la solicitud #4821, la llave debería derivar de ese número, no de la hora. Así el reintento de mañana también encuentra la respuesta de hoy.