> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lapyme.com.ar/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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:

```json theme={null}
{
  "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.