---
title: Postman Collection
---

# Coleções de API

Collection pronta para importar no Postman, Insomnia, ou qualquer client HTTP compatível.

::: tip Qual usar?
- **Postman** (JSON abaixo) -- 21 requisições cobrindo os 18 endpoints externos (PIX Cash-Out possui 3 variantes: chave, email, copia-e-cola), mais um exemplo do `GET /health` (endpoint fora do namespace `/api/external`, útil para probe de disponibilidade). Snapshot estático atualizado quando necessário.
:::

## Download Postman

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

## O que inclui

| Categoria | Endpoints |
|-----------|-----------|
| PIX Cash-Out | Envio por chave, email, copia-e-cola (3 variantes do mesmo endpoint `POST /pix/cash-out`) |
| PIX Cash-In | Gerar QR Code (`POST /pix/cash-in`) |
| Consultas | Por ID, E2E, tag, external_id, comprovante |
| Extrato | `GET /statement` |
| Transações | `GET /transactions` (listagem com filtros) |
| Saldo | `GET /balance` |
| Chaves PIX | `GET /pix/keys` |
| Devolução | `POST /pix/refund` |
| Webhooks | `POST /webhooks`, `GET /webhooks`, `DELETE /webhooks/:id` |
| MED | `GET /med`, `GET /med/:id` |
| Validação | `POST /cpf/validate` |
| Health | `GET /health` (fora de `/api/external`, probe de disponibilidade) |

**Total: 21 requisições cobrindo os 18 endpoints da API External + 1 probe `GET /health`.**


## Configuração

### 1. Importar no Postman

1. Abra o Postman
2. Clique em **Import** (canto superior esquerdo)
3. Arraste o arquivo JSON ou clique **Upload Files**
4. A collection "Monetarie - API Externa" aparece no painel esquerdo

### 2. Configurar variáveis

Clique na collection > aba **Variables** e preencha:

| Variável | Valor | Descrição |
|----------|-------|-----------|
| `base_url` | `https://api.monetarie.com/api/external` | URL base da API (produção) |
| `client_id` | Seu `cli_...` | Client ID da API key |
| `client_secret` | Seu `sk_...` | Client Secret da API key |

Para homologação, solicite a URL e as credenciais ao time Monetarie.

### 3. HMAC automático

A collection tem um **pre-request script** global que gera automaticamente o header `hmac` (HMAC-SHA512) para todas as requisições POST. O script faz `JSON.parse(body)` + `JSON.stringify(parsed, Object.keys(parsed).sort())` para garantir que o body seja serializado com **chaves em ordem alfabética** antes de calcular o HMAC -- isso casa com a normalização `Jason.decode + Jason.encode!` do backend. Não precisa calcular manualmente.

::: warning HMAC só em POST
Requisições `GET` e `DELETE` **não** recebem header `hmac` -- não possuem body para assinar. O pre-request script ignora esses métodos automaticamente.
:::

### 4. Variáveis automáticas

Os test scripts capturam automaticamente:
- `last_transaction_id` - do response de cash-out
- `last_e2e_id` - do response de cash-out
- `last_qr_tx_id` - do response de cash-in

Essas variáveis são reutilizadas nas consultas subsequentes.

## Valores monetários

::: warning Atenção
**Request**: valores em centavos (R$ 1,00 = `100`)

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

Para converter response para Reais: divida por 10.000.
:::

## Workflow sugerido

1. **Saldo** - `GET /balance` para verificar saldo disponível (sem rate limit)
2. **Cash-In** - `POST /pix/cash-in` para gerar QR Code
3. **Cash-Out** - `POST /pix/cash-out` para enviar PIX
4. **Consulta** - `GET /transactions/:id` (por ID interno) ou `GET /transactions/e2e/:e2e_id` (por E2E BACEN) para acompanhar status
5. **Consulta por external_id** - `GET /transactions/ref/:external_id` para localizar pela referência do seu sistema
6. **Comprovante** - `GET /transactions/:id/receipt` disponível apenas quando `status: "settled"` (PIX Cash-Out) ou `paid_at` preenchido (Cash-In)
7. **Webhooks** - `POST /webhooks` para receber notificações assíncronas de status (alternativa recomendada ao polling)

## Importar no Insomnia

1. Abra o Insomnia
2. **Application > Preferences > Data > Import Data**
3. Selecione **From File** e escolha o JSON
4. Configure as variáveis de ambiente com os mesmos valores acima