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

# Idempotencia

> Reintentos seguros en las APIs públicas de Cobrix

La idempotencia evita duplicar clientes, documentos, pagos y asientos financieros cuando una solicitud se repite por timeout o pérdida de conexión.

## API de integraciones

Todos los `POST` bajo `/integrations/v1` requieren:

```http theme={null}
Idempotency-Key: 2cf0b8d1-3388-47ea-8b67-bc11e7de4efe
```

La clave se almacena por empresa, llave, método y ruta. El mismo cuerpo reproduce la respuesta original; reutilizarla con un cuerpo diferente devuelve un conflicto.

## API pública de documentos de cobro

La creación usa un header distinto:

```http theme={null}
x-idempotency: 2cf0b8d1-3388-47ea-8b67-bc11e7de4efe
```

* Misma llave y mismo cuerpo: devuelve el documento original con `201`.
* Misma llave y cuerpo diferente: `409 idempotency_error`.
* Header ausente: `409 idempotency_error`.
* La deduplicación `provider + reference` se conserva aunque cambie la clave.

## Recomendaciones

1. Genera una clave UUID por operación de negocio, no por intento HTTP.
2. Conserva la clave hasta recibir una respuesta definitiva.
3. Reintenta timeouts y errores `5xx` con backoff exponencial.
4. No reutilices una clave para otro documento o pago.
5. Conserva exactamente el mismo cuerpo serializado al reintentar requests firmados.