Idempotencia

Cómo evitar guías duplicadas. Léalo antes de crear en producción.

Lea esto antes de crear en producción. El courier upstream no es idempotente y cada creación exitosa genera una guía real y cobrable. Un reintento ciego tras un corte de red puede generar un segundo envío que su cliente paga.

La clave representa el intento lógico

No la petición HTTP. Esa distinción es toda la mecánica:

Un reintento por timeout de red debe reusar la misma clave.
Un reenvío deliberado tras anular usa una clave nueva.

Idempotency-Key: drivenbox-order:1234:shipment:1

La plataforma no interpreta el formato: aplica idempotencia por workspace y endpoint. El formato es una convención suya.

Qué puede recibir

Respuesta	Significado	Qué hacer
`201`	Guía creada	Guarde el tracking.
`200` + `Idempotent-Replayed`	Reintento de una creación previa	Trátelo igual que un 201. No cree otra.
`202`	Encolada	Consulte `/v1/operations/{id}`.
`409 idempotency_conflict`	Misma clave, cuerpo distinto	Bug suyo. Registre y alerte.
`409 operation_in_progress`	Resultado sin confirmar	No reintente. Ver abajo.

Resultado sin confirmar

{
  "error": {
    "code": "operation_in_progress",
    "details": { "reason": "unknown_outcome", "operation_id": "op_..." }
  }
}

La solicitud salió hacia el courier y puede haber creado una guía real, pero la respuesta se perdió. La clave queda reclamada de forma permanente, así que un reintento con la misma clave recibe este mismo error en lugar de crear una segunda guía.

Consulte la operación hasta que se resuelva:

succeeded — la guía existía y quedó enlazada. Use su tracking.
failed con reconciliation: not_created — no se creó nada. Ahora sí puede reintentar, con una clave nueva.
requires_review — evidencia ambigua. Requiere intervención humana; no reintente.

Verificado: cincuenta peticiones simultáneas con la misma clave producen exactamente una guía.