# Vision General de la API

La API Monetarie permite integrar pagos PIX a su sistema. Todas las operaciones exigen API Key e IP Whitelist; endpoints `POST` agregan HMAC-SHA512 sobre el body.

## URL Base

| Ambiente | URL |
|----------|-----|
| Produccion | `https://api.monetarie.com` |
| Homologacion | `https://api-h.monetarie.com` |

## Autenticacion

Capas de seguridad (por tipo de solicitud):

1. **IP Whitelist** (todas) -- IP de origen debe estar en la whitelist configurada en la API Key
2. **API Key** (todas) -- Header `Authorization: ApiKey {client_id}:{client_secret}` en todas las solicitudes
3. **HMAC-SHA512** (solo `POST`) -- Firma del body de la solicitud; obligatorio en `POST /pix/cash-in`, `POST /pix/cash-out`, `POST /cpf/validate`, `POST /webhooks`, `POST /pix/refund`. Solicitudes `GET` y `DELETE` **no** cargan HMAC (no poseen body a firmar).

:::warning Orden alfabetico obligatorio en el body HMAC
Requests POST que exigen HMAC deben firmar el body con **claves en orden alfabetico**. El backend hace `Jason.decode + Jason.encode!` en el body para validacion, lo que reordena las claves. Si su cliente no alfabetiza antes de firmar, el HMAC computado localmente no coincide con el del servidor → HTTP 401.

Detalles completos: [HMAC-SHA512](/es/hmac).
:::

Vea [Autenticacion](/es/auth-token) y [HMAC-SHA512](/es/hmac) para detalles.

## Formato

| Campo | Formato |
|-------|---------|
| Content-Type | `application/json` |
| Valores de entrada (request) | Enteros en **centavos** (R$ 1,00 = `100`) |
| Valores de respuesta | Enteros en **subcentavos** (unidades base; R$ 1,00 = `10000`, ÷ 10.000 para reales) |
| Fechas | ISO 8601 en UTC con sufijo `Z` (`2026-03-09T15:30:00Z`) |
| IDs | UUID v4 o string alfanumerica |
| E2E ID | `^E\d{8}[a-zA-Z0-9]{22,26}$` (estandar BACEN, 31-35 chars, sufijo puede contener letras) |

::: tip Terminologia
En esta documentacion, **subcentavos** y **unidades base** se refieren a la misma unidad (10.000 = R$ 1,00). El termino "unidades base" aparece en algunos ejemplos heredados; considerelo sinonimo de subcentavos. Siempre divida el valor de la respuesta por 10.000 para obtener reales.
:::

::: warning E2E puede contener letras
El sufijo despues de `E + ISPB + timestamp` es **alfanumerico de 9 a 13 caracteres** (no solo digitos). Bancos como Nubank emiten E2Es con letras al final. Siempre valide con la regex completa. Detalles en [PIX Cash-In por E2E ID](/es/pix-cashin-e2e).
:::

::: danger Conversion de valores
**Para enviar**: multiplique reales por 100. R$ 1,00 = `100`.
**Para leer respuestas**: divida por 10.000. `10000` ÷ 10.000 = R$ 1,00.
**Nunca use punto flotante** -- siempre enteros.
:::

## Case de las claves (camelCase opcional)

Respuestas JSON usan `snake_case` por default (ej: `transaction_id`, `end_to_end_id`). Si su cliente prefiere `camelCase`, envie el header:

```
X-Key-Case: camelCase
```

El backend convierte **todas las claves del JSON de respuesta** (incluyendo objetos anidados) automaticamente. Ejemplo: `transaction_id` → `transactionId`, `pix_key_type` → `pixKeyType`. El header no afecta el body de entrada - envie siempre en `snake_case` al hacer `POST`.

## Patron de Respuesta

### Exito

```json
{
  "worked": true,
  "transaction_id": "PIXOUT20260309abcdef123456",
  "status": "processing"
}
```

### Error

El formato del error varia segun la capa que rechazo la solicitud:

```json
// Plug HMAC (401 firma invalida)
{ "worked": false, "detail": "Invalid HMAC signature" }

// ApiKeyAuth (401 / 403)
{ "error": { "status": 401, "message": "Invalid API key" } }

// Respuestas de error de la API (404 / 400 / 409 / 422 / 500)
{ "errors": { "not_found": "transaction not found" } }
```

Vea la tabla completa en [Autenticacion -- Respuestas de Error](/es/auth-token#respuestas-de-error).

## Codigos HTTP

| Codigo | Significado |
|--------|-------------|
| 200 | Exito |
| 201 | Recurso creado (webhook) |
| 400 | Parametros invalidos |
| 401 | API Key ausente o invalida / HMAC invalido |
| 403 | IP no autorizado en la whitelist |
| 404 | Recurso no encontrado |
| 422 | Validacion fallida (saldo insuficiente, clave invalida) |
| 429 | Rate limit excedido |
| 500 | Error interno |

## Rate Limiting

| Tipo | Limite |
|------|--------|
| Por IP (autenticado) | 90.000 solicitudes/minuto (1.500 req/s) |
| Por IP (autenticacion / login) | 5 solicitudes/minuto |
| `GET /balance` | **sin rate limit** (polling alta frecuencia permitido) |

Headers de respuesta:

```
X-RateLimit-Remaining: 59997
Retry-After: 3  (solo cuando 429)
```

## Idempotencia

Solicitudes POST aceptan el header `Idempotency-Key` (max **256 caracteres**) para evitar procesamiento duplicado. Solo respuestas **2xx (exito)** son cacheadas por 24 horas. Si la misma clave es reenviada para el mismo metodo y endpoint, la API retorna la respuesta original con el header `X-Idempotent-Replay: true`.

```
Idempotency-Key: unique-request-id-123
```

::: tip Alcance de la clave
La clave esta vinculada a `metodo + path + Idempotency-Key`. La misma clave puede ser reutilizada en endpoints diferentes sin colisionar. Respuestas de error (4xx/5xx) **no** son cacheadas -- el cliente puede reintentar despues de corregir la falla.
:::

::: info GET/DELETE y Idempotency-Key
Solicitudes `GET` y `DELETE` **ignoran** silenciosamente el header `Idempotency-Key` -- el plug solo actua en `POST`. Enviar la clave en esos metodos no causa error, pero no genera cache ni replay.
:::

## Politicas de retry y cuarentena

- **Cuarentena (stage=5)**: PIX Cash-Out preso en `status: "processing"` por mas de 30 minutos es movido a cuarentena, donde permanece aguardando resolucion manual por el equipo Monetarie. El status continua `"processing"` desde la perspectiva del cliente hasta la finalizacion. Detalles en el flujo: [PIX Lifecycle](/es/pix-lifecycle).
- **Retry automatico de webhooks**: deliveries con falla (timeout, 5xx, conexion cerrada) son reagendadas en hasta 7 intentos (intervalos `[0, 30s, 2min, 10min, 30min, 1h, 2h, 4h]`). Vea [Webhooks](/es/webhooks).
- **Retry del cliente**: al recibir `429`, respete `Retry-After`. Al recibir `500` o timeout, use backoff exponencial + `Idempotency-Key` para evitar duplicacion. Vea [Autenticacion](/es/auth-token) para detalles.
- **Ventana anti-replay del webhook**: el header `X-Monetarie-Timestamp` es Unix time en segundos. El servidor **no** rechaza webhooks antiguos; cabe a su endpoint descartar entregas con `|now - timestamp| > 300s` (± 5 minutos) como defense-in-depth contra replay. Vea [Webhooks -- Validando la Firma](/es/webhooks#validando-la-firma).

## External ID

Campo opcional `external_id` (max 128 chars, alfanumerico + `._:-`) aceptado en cash-in y cash-out. Retornado en respuestas y webhooks. Permite consulta por referencia:

```
GET /api/external/transactions/ref/{external_id}
```

Vea [Consultar por External ID](/es/pix-query-external-id) para detalles.

## Endpoints

### PIX Cash-Out (Envio)

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | `/api/external/pix/cash-out` | Enviar PIX por clave o copia-y-pega |

### PIX Cash-In (Cobro)

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | `/api/external/pix/cash-in` | Generar QR Code para cobro |

### Consultas

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | `/api/external/transactions` | Listar transacciones |
| GET | `/api/external/transactions/:id` | Consultar transaccion por ID |
| GET | `/api/external/transactions/e2e/:e2e_id` | Consultar por E2E ID |
| GET | `/api/external/transactions/tag/:tag` | Consultar por tag (prefijo) |
| GET | `/api/external/transactions/ref/:external_id` | Consultar por external_id |
| GET | `/api/external/transactions/:id/receipt` | Comprobante |

### Cuenta

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | `/api/external/balance` | Saldo de la cuenta |
| GET | `/api/external/statement` | Extracto |

### Claves PIX

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | `/api/external/pix/keys` | Listar claves PIX de la cuenta |

### Devolucion

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | `/api/external/pix/refund` | Devolucion PIX (total o parcial) |

### MED

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | `/api/external/med` | Listar MEDs |
| GET | `/api/external/med/:id` | Detalles de un MED |
| POST | `/api/external/med/:id/defense` | Enviar defensa MED con justificativa y evidencias |

### Validacion

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | `/api/external/cpf/validate` | Validar CPF |

### Webhooks

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | `/api/external/webhooks` | Listar webhooks |
| POST | `/api/external/webhooks` | Registrar webhook |
| DELETE | `/api/external/webhooks/:id` | Remover webhook |