Una red inestable puede cortar la respuesta de una escritura que sí se aplicó; repetir la solicitud podría crear el mismo documento dos veces. La cabecera Idempotency-Key lo evita: Chainlink conserva la respuesta de cada llave durante 24 horas y, si recibe la misma solicitud con la misma llave, devuelve esa respuesta sin repetir la operación.

Documento de salida con llave de idempotencia

curl -X POST "https://empresa.chainlink.mx/api/v1/exit-documents" \
  -H "Authorization: Bearer $CHAINLINK_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c7f1e-2b8a-4f43-9a0e-3c2f9b8f1d2a" \
  -d '{"external_ref": "PED-88121", "type": "Orden de Venta", "doc_date": "2026-10-06", "partner_code": "CLI-001", "warehouse_code": "CEDIS-GDL", "lines": [{"item_code": "P-1001", "qty": 6}]}'

Funcionamiento

Situación	Respuesta
Primera solicitud con la llave	Se procesa; la respuesta se conserva 24 horas
Misma llave, mismo método, ruta y cuerpo	La respuesta conservada (mismo estado, cuerpo y `Location`) con `X-Idempotency-Replayed: true`
Misma llave mientras la primera sigue en proceso	`409 duplicate_in_flight`: reintentar después con la misma llave
Misma llave con otro método, ruta o cuerpo	`422 idempotency_key_reused`
Error del servidor (5xx)	No se conserva: reintentar con la misma llave
Falta la llave donde es obligatoria	`400 idempotency_key_required`

La llave es válida por instancia y por cliente de integración (o usuario): dos sistemas no entran en conflicto aunque usen la misma.
Es obligatoria en POST /entry-documents y POST /exit-documents, y opcional en las demás escrituras.
Genere un UUID v4 por operación de negocio y guárdelo junto al registro del sistema antes de enviar, para reutilizarlo en los reintentos.

Referencia externa

Los documentos de entrada y salida y las órdenes de transferencia aceptan external_ref, el folio del sistema de origen. Un documento con un type y un external_ref existentes no se crea otra vez: la respuesta es 200 con el documento existente, aunque la llave sea distinta. Se recomienda usar ambas protecciones: la llave cubre el reintento inmediato y la referencia externa cubre un reenvío posterior.