# Guia para integradores

## Autenticacion

Usa `x-api-key` en cada solicitud de sistema externo. Para operaciones administrativas usa `Authorization: Bearer <token>`.

## Idempotencia

Todas las operaciones de creacion deben enviar `Idempotency-Key`. Reutilizar la misma llave devuelve la misma respuesta si la operacion ya fue procesada.

## Estados

`pending`, `paid`, `expired`, `cancelled`, `failed`, `duplicated`, `callback_failed`, `partially_processed`, `webhook_received`, `webhook_processed`, `callback_sent`, `reconciled`, `reconciliation_error`.

## Layout CSV

```csv
external_reference,contract_number,customer_name,customer_email,customer_phone,amount,currency,description,due_date,period
RECIBO-2026-000001,CONTRATO-123456,Juan Perez,juan@example.com,5555555555,248.50,MXN,Pago de agua potable,2026-07-15T23:59:59-06:00,2026-06
```

## Callback

La plataforma envia `POST` al callback configurado con `x-signature`.

```json
{
  "event_type": "payment.paid",
  "reference": "RECIBO-2026-000001",
  "status": "paid",
  "paid_at": "2026-06-22T10:20:30-06:00"
}
```