---
title: Postman Collection
---

# Colecciones de API

Collection lista para importar en Postman, Insomnia, o cualquier cliente HTTP compatible.

::: tip Cual usar?
- **Postman** (JSON abajo) -- 21 solicitudes cubriendo los 18 endpoints externos (PIX Cash-Out tiene 3 variantes: clave, email, copia-y-pega), mas un ejemplo del `GET /health` (endpoint fuera del namespace `/api/external`, util para probe de disponibilidad). Snapshot estatico actualizado cuando necesario.
:::

## Download Postman

<a href="/downloads/monetarie-api-externa.postman_collection.json" download>Descargar Postman Collection (JSON)</a>

## Que incluye

| Categoria | Endpoints |
|-----------|-----------|
| PIX Cash-Out | Envio por clave, email, copia-y-pega (3 variantes del mismo endpoint `POST /pix/cash-out`) |
| PIX Cash-In | Generar QR Code (`POST /pix/cash-in`) |
| Consultas | Por ID, E2E, tag, external_id, comprobante |
| Extracto | `GET /statement` |
| Transacciones | `GET /transactions` (listado con filtros) |
| Saldo | `GET /balance` |
| Claves PIX | `GET /pix/keys` |
| Devolucion | `POST /pix/refund` |
| Webhooks | `POST /webhooks`, `GET /webhooks`, `DELETE /webhooks/:id` |
| MED | `GET /med`, `GET /med/:id` |
| Validacion | `POST /cpf/validate` |
| Health | `GET /health` (fuera de `/api/external`, probe de disponibilidad) |

**Total: 21 solicitudes cubriendo los 18 endpoints de la API External + 1 probe `GET /health`.**


## Configuracion

### 1. Importar en Postman

1. Abra Postman
2. Haga clic en **Import** (esquina superior izquierda)
3. Arrastre el archivo JSON o haga clic en **Upload Files**
4. La collection "Monetarie - API Externa" aparece en el panel izquierdo

### 2. Configurar variables

Haga clic en la collection > pestana **Variables** y complete:

| Variable | Valor | Descripcion |
|----------|-------|-------------|
| `base_url` | `https://api.monetarie.com/api/external` | URL base de la API (produccion) |
| `client_id` | Su `cli_...` | Client ID de la API key |
| `client_secret` | Su `sk_...` | Client Secret de la API key |

Para homologacion, solicite la URL y las credenciales al equipo Monetarie.

### 3. HMAC automatico

La collection tiene un **pre-request script** global que genera automaticamente el header `hmac` (HMAC-SHA512) para todas las solicitudes POST. El script hace `JSON.parse(body)` + `JSON.stringify(parsed, Object.keys(parsed).sort())` para garantizar que el body sea serializado con **claves en orden alfabetico** antes de calcular el HMAC -- esto coincide con la normalizacion `Jason.decode + Jason.encode!` del backend. No necesita calcular manualmente.

::: warning HMAC solo en POST
Solicitudes `GET` y `DELETE` **no** reciben header `hmac` -- no poseen body para firmar. El pre-request script ignora esos metodos automaticamente.
:::

### 4. Variables automaticas

Los test scripts capturan automaticamente:
- `last_transaction_id` - del response de cash-out
- `last_e2e_id` - del response de cash-out
- `last_qr_tx_id` - del response de cash-in

Estas variables son reutilizadas en las consultas subsecuentes.

## Valores monetarios

::: warning Atencion
**Request**: valores en centavos (R$ 1,00 = `100`)

**Response**: valores en subcentavos (R$ 1,00 = `10000`)

Para convertir response a Reales: divida por 10.000.
:::

## Workflow sugerido

1. **Saldo** - `GET /balance` para verificar saldo disponible (sin rate limit)
2. **Cash-In** - `POST /pix/cash-in` para generar QR Code
3. **Cash-Out** - `POST /pix/cash-out` para enviar PIX
4. **Consulta** - `GET /transactions/:id` (por ID interno) o `GET /transactions/e2e/:e2e_id` (por E2E BACEN) para acompanar status
5. **Consulta por external_id** - `GET /transactions/ref/:external_id` para localizar por la referencia de su sistema
6. **Comprobante** - `GET /transactions/:id/receipt` disponible solo cuando `status: "settled"` (PIX Cash-Out) o `paid_at` llenado (Cash-In)
7. **Webhooks** - `POST /webhooks` para recibir notificaciones asincronicas de status (alternativa recomendada al polling)

## Importar en Insomnia

1. Abra Insomnia
2. **Application > Preferences > Data > Import Data**
3. Seleccione **From File** y elija el JSON
4. Configure las variables de entorno con los mismos valores anteriores