API Collections

Ready-to-import collection for Bruno (recommended), Postman, Insomnia, or any compatible HTTP client.

Which to use?

• Bruno (backend/bruno/external/) -- 100% coverage (18 external endpoints), updated on every endpoint change, versioned in git. Preferred for development/testing.
• Postman (JSON below) -- 21 requests covering the 18 external endpoints (PIX Cash-Out has 3 variants: key, email, copy-and-paste), plus a GET /health example (endpoint outside the /api/external namespace, useful for availability probing). Static snapshot updated when needed.

Postman Download

Download Postman Collection (JSON)

Bruno Collection (recommended)

The project maintains a Bruno collection with 100% coverage of Owem endpoints (admin, merchant, external, simulator). Bruno is an open-source, git-friendly API client (requests are text .bru files).

Access

The collection lives in backend/bruno/ of the Owem Pay repository:

• admin/ — Admin Console panel requests
• merchant/ — Merchant portal requests
• external/ — 18 External API requests, covering 100% of endpoints exposed in /api/external/* ← this documentation
• simulator/ — requests for the CloudPix Simulator

Each External endpoint maps 1:1 to a .bru file in backend/bruno/external/{namespace}/{operation}.bru (e.g., balance/get.bru, pix/cash-out.bru, transactions/list.bru).

Usage

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

# Clone or copy only the external folder
cp -r backend/bruno/external/ ~/my-owem-collection/

# Open in Bruno (File > Open Collection)

Bruno is updated on every endpoint change — prefer it over the Postman collection for development/testing environments.

What's included

Category	Endpoints
PIX Cash-Out	Send by key, email, copy-and-paste (3 variants of the same endpoint POST /pix/cash-out)
PIX Cash-In	Generate QR Code (POST /pix/cash-in)
Queries	By ID, E2E, tag, external_id, receipt
Statement	GET /statement
Transactions	GET /transactions (list with filters)
Balance	GET /balance
PIX Keys	GET /pix/keys
Refund	POST /pix/refund
Webhooks	POST /webhooks, GET /webhooks, DELETE /webhooks/:id
MED	GET /med, GET /med/:id
Validation	POST /cpf/validate
Health	GET /health (outside /api/external, availability probe)

Total: 21 requests covering the 18 External API endpoints + 1 GET /health probe.

Parity with the router

The canonical router is backend/lib/fluxiq_web/routers/external_router.ex. Any divergence between the collection and the router must be reported as a collection bug.

Setup

1. Import in Postman

1. Open Postman
2. Click Import (top left corner)
3. Drag the JSON file or click Upload Files
4. The "Owem Pay - API Externa" collection appears in the left panel

2. Configure variables

Click the collection > Variables tab and fill in:

Variable	Value	Description
base_url	https://api.owem.com.br/api/external	API base URL (production)
client_id	Your cli_...	API key Client ID
client_secret	Your sk_...	API key Client Secret

For staging, use https://api-hml.owem.com.br/api/external.

3. Automatic HMAC

The collection has a global pre-request script that automatically generates the hmac header (HMAC-SHA512) for all POST requests. The script does JSON.parse(body) + JSON.stringify(parsed, Object.keys(parsed).sort()) to ensure the body is serialized with keys in alphabetical order before computing the HMAC -- this matches the backend Jason.decode + Jason.encode! normalization. No manual computation needed.

HMAC only on POST

GET and DELETE requests do not receive an hmac header -- they have no body to sign. The pre-request script ignores these methods automatically.

4. Automatic variables

Test scripts automatically capture:

• last_transaction_id — from cash-out response
• last_e2e_id — from cash-out response
• last_qr_tx_id — from cash-in response

These variables are reused in subsequent queries.

Monetary values

Attention

Request: values in centavos (R$ 1.00 = 100)

Response: values in subcentavos (R$ 1.00 = 10000)

To convert response to BRL: divide by 10,000.

Suggested workflow

1. Balance — GET /balance to check available balance (no rate limit)
2. Cash-In — POST /pix/cash-in to generate QR Code
3. Cash-Out — POST /pix/cash-out to send PIX
4. Query — GET /transactions/:id (by internal ID) or GET /transactions/e2e/:e2e_id (by BACEN E2E) to track status
5. Query by external_id — GET /transactions/ref/:external_id to locate by your system reference
6. Receipt — GET /transactions/:id/receipt available only when status: "settled" (PIX Cash-Out) or paid_at filled in (Cash-In)
7. Webhooks — POST /webhooks to receive asynchronous status notifications (recommended alternative to polling)

Import in Insomnia

1. Open Insomnia
2. Application > Preferences > Data > Import Data
3. Select From File and choose the JSON
4. Set up environment variables with the same values above