Coleções de API

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

Qual usar?

• Bruno (backend/bruno/external/) -- 100% de cobertura (18 endpoints externos), atualizado a cada mudança de endpoint, versionado no git. Preferência para desenvolvimento/teste.
• 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

Baixar Postman Collection (JSON)

Coleção Bruno (recomendada)

O projeto mantém uma coleção Bruno com 100% de cobertura dos endpoints Owem (admin, merchant, external, simulator). Bruno é um cliente API open-source, git-friendly (requests são arquivos .bru em texto).

Acesso

A coleção vive em backend/bruno/ do repositório Owem Pay:

• admin/ — requests do painel Admin Console
• merchant/ — requests do portal Merchant
• external/ — 18 requests da API External, cobrindo 100% dos endpoints expostos em /api/external/* ← esta documentação
• simulator/ — requests para o CloudPix Simulator

Cada endpoint External mapeia 1:1 para um arquivo .bru em backend/bruno/external/{namespace}/{operacao}.bru (ex.: balance/get.bru, pix/cash-out.bru, transactions/list.bru).

Uso

# Instale Bruno
# https://www.usebruno.com/downloads

# Clone ou copie apenas a pasta external
cp -r backend/bruno/external/ ~/minha-colecao-owem/

# Abra no Bruno (File > Open Collection)

Bruno é atualizado a cada mudança de endpoint — prefira-o sobre a coleção Postman para ambientes de desenvolvimento/teste.

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.

Paridade com o router

O router canônico é backend/lib/fluxiq_web/routers/external_router.ex. Qualquer divergência entre a coleção e o router deve ser reportada como bug da coleção.

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 "Owem Pay - 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.owem.com.br/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, use https://api-hml.owem.com.br/api/external.

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.

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

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