Idempotencia

Cómo usar Idempotency-Key para reintentar escrituras sin crear duplicados.

Las escrituras que pueden crear duplicados requieren o aceptan el header Idempotency-Key. Esto permite reintentar una operación ante timeouts, cortes de red o errores temporales sin crear dos recursos por accidente.

Cómo usarla

Enviá una clave única por operación de negocio:

curl -X POST "https://api.lapyme.com.ar/api/v1/purchases" \
  -H "Authorization: Bearer TU_API_KEY_AQUI" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: purchase-2026-05-27-0001" \
  -d '{ ... }'

Reutilizá la misma key solo para reintentar la misma operación con el mismo payload. Idempotency-Key no reemplaza los campos de referencia externa de los recursos. Por ejemplo, en POST /api/v1/sales, si querés guardar el ID de tu sistema en la venta, enviá integration_source e integration_id en el cuerpo además del header.

Endpoints que la usan

Idempotency-Key es obligatoria en:

1. POST /api/v1/purchases
2. POST /api/v1/sales
3. POST /api/v1/products
4. POST /api/v1/products/bulk-adjustments
5. POST /api/v1/stock-movements
6. POST /api/v1/purchase-orders
7. POST /api/v1/purchase-orders/{purchase_order_id}/receipts

Es opcional en:

1. POST /api/v1/stock-transfers

Cuando se omite en endpoints donde es opcional, la operación sigue siendo válida, pero no tiene protección automática contra repeticiones.

Conflictos

Si reutilizás una key con otro payload, la API responde:

{
  "request_id": "req_123",
  "error": {
    "type": "idempotency_error",
    "code": "IDEMPOTENCY_CONFLICT",
    "message": "La misma Idempotency-Key fue reutilizada con otro payload.",
    "retryable": false,
    "details": []
  }
}

Reintentos

Para timeouts de red o respuestas 5xx, reintentá con la misma key. Para errores 4xx, corregí el payload antes de enviar una key nueva.