Colecciones de API

Collection lista para importar en Bruno (recomendado), Postman, Insomnia, o cualquier cliente HTTP compatible.

Cual usar?

• Bruno (backend/bruno/external/) -- 100% de cobertura (18 endpoints externos), actualizado a cada cambio de endpoint, versionado en git. Preferencia para desarrollo/prueba.
• 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

Descargar Postman Collection (JSON)

Coleccion Bruno (recomendada)

El proyecto mantiene una coleccion Bruno con 100% de cobertura de los endpoints Owem (admin, merchant, external, simulator). Bruno es un cliente API open-source, git-friendly (requests son archivos .bru en texto).

Acceso

La coleccion vive en backend/bruno/ del repositorio Owem Pay:

• admin/ — requests del panel Admin Console
• merchant/ — requests del portal Merchant
• external/ — 18 requests de la API External, cubriendo 100% de los endpoints expuestos en /api/external/* ← esta documentacion
• simulator/ — requests para el CloudPix Simulator

Cada endpoint External mapea 1:1 a un archivo .bru en backend/bruno/external/{namespace}/{operacion}.bru (ej: balance/get.bru, pix/cash-out.bru, transactions/list.bru).

Uso

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

# Clone o copie solo la carpeta external
cp -r backend/bruno/external/ ~/mi-coleccion-owem/

# Abra en Bruno (File > Open Collection)

Bruno es actualizado a cada cambio de endpoint — prefieralo sobre la coleccion Postman para ambientes de desarrollo/prueba.

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.

Paridad con el router

El router canonico es backend/lib/fluxiq_web/routers/external_router.ex. Cualquier divergencia entre la coleccion y el router debe ser reportada como bug de la coleccion.

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

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.

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

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