Collections d'API

Collection prête à importer dans Bruno (recommandé), Postman, Insomnia, ou tout client HTTP compatible.

Lequel utiliser ?

• Bruno (backend/bruno/external/) -- 100% de couverture (18 endpoints externes), mis à jour à chaque changement d'endpoint, versionné dans git. Préférence pour le développement/test.
• Postman (JSON ci-dessous) -- 21 requêtes couvrant les 18 endpoints externes (PIX Cash-Out a 3 variantes : clé, email, copier-coller), plus un exemple de GET /health (endpoint hors du namespace /api/external, utile pour le probe de disponibilité). Snapshot statique mis à jour au besoin.

Télécharger Postman

Télécharger Postman Collection (JSON)

Collection Bruno (recommandée)

Le projet maintient une collection Bruno avec 100% de couverture des endpoints Owem (admin, merchant, external, simulator). Bruno est un client API open-source, git-friendly (les requests sont des fichiers .bru en texte).

Accès

La collection réside dans backend/bruno/ du dépôt Owem Pay :

• admin/ — requests du panneau Admin Console
• merchant/ — requests du portail Merchant
• external/ — 18 requests de l'API External, couvrant 100% des endpoints exposés dans /api/external/* ← cette documentation
• simulator/ — requests pour le CloudPix Simulator

Chaque endpoint External mappe 1:1 vers un fichier .bru dans backend/bruno/external/{namespace}/{opération}.bru (ex. : balance/get.bru, pix/cash-out.bru, transactions/list.bru).

Usage

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

# Clonez ou copiez seulement le dossier external
cp -r backend/bruno/external/ ~/ma-collection-owem/

# Ouvrez dans Bruno (File > Open Collection)

Bruno est mis à jour à chaque changement d'endpoint — préférez-le à la collection Postman pour les environnements de développement/test.

Ce qui est inclus

Catégorie	Endpoints
PIX Cash-Out	Envoi par clé, email, copier-coller (3 variantes du même endpoint POST /pix/cash-out)
PIX Cash-In	Générer QR Code (POST /pix/cash-in)
Consultations	Par ID, E2E, tag, external_id, reçu
Relevé	GET /statement
Transactions	GET /transactions (listing avec filtres)
Solde	GET /balance
Clés PIX	GET /pix/keys
Remboursement	POST /pix/refund
Webhooks	POST /webhooks, GET /webhooks, DELETE /webhooks/:id
MED	GET /med, GET /med/:id
Validation	POST /cpf/validate
Health	GET /health (hors de /api/external, probe de disponibilité)

Total : 21 requêtes couvrant les 18 endpoints de l'API External + 1 probe GET /health.

Parité avec le router

Le router canonique est backend/lib/fluxiq_web/routers/external_router.ex. Toute divergence entre la collection et le router doit être rapportée comme bug de la collection.

Configuration

1. Importer dans Postman

1. Ouvrez Postman
2. Cliquez sur Import (coin supérieur gauche)
3. Glissez-déposez le fichier JSON ou cliquez sur Upload Files
4. La collection « Owem Pay - API Externa » apparaît dans le panneau gauche

2. Configurer les variables

Cliquez sur la collection > onglet Variables et remplissez :

Variable	Valeur	Description
base_url	https://api.owem.com.br/api/external	URL de base de l'API (production)
client_id	Votre cli_...	Client ID de l'API key
client_secret	Votre sk_...	Client Secret de l'API key

Pour l'homologation, utilisez https://api-hml.owem.com.br/api/external.

3. HMAC automatique

La collection a un pre-request script global qui génère automatiquement le header hmac (HMAC-SHA512) pour toutes les requêtes POST. Le script fait JSON.parse(body) + JSON.stringify(parsed, Object.keys(parsed).sort()) pour garantir que le body est sérialisé avec clés en ordre alphabétique avant de calculer le HMAC -- cela correspond à la normalisation Jason.decode + Jason.encode! du backend. Pas besoin de calculer manuellement.

HMAC uniquement en POST

Les requêtes GET et DELETE ne reçoivent pas d'en-tête hmac -- elles n'ont pas de body à signer. Le pre-request script ignore ces méthodes automatiquement.

4. Variables automatiques

Les test scripts capturent automatiquement :

• last_transaction_id — de la response de cash-out
• last_e2e_id — de la response de cash-out
• last_qr_tx_id — de la response de cash-in

Ces variables sont réutilisées dans les consultations suivantes.

Valeurs monétaires

Attention

Request : valeurs en centavos (R$ 1,00 = 100)

Response : valeurs en subcentavos (R$ 1,00 = 10000)

Pour convertir la response en Reais : divisez par 10 000.

Workflow suggéré

1. Solde — GET /balance pour vérifier le solde disponible (sans rate limit)
2. Cash-In — POST /pix/cash-in pour générer un QR Code
3. Cash-Out — POST /pix/cash-out pour envoyer un PIX
4. Consultation — GET /transactions/:id (par ID interne) ou GET /transactions/e2e/:e2e_id (par E2E BACEN) pour suivre le status
5. Consultation par external_id — GET /transactions/ref/:external_id pour localiser par référence de votre système
6. Reçu — GET /transactions/:id/receipt disponible uniquement quand status: "settled" (PIX Cash-Out) ou paid_at renseigné (Cash-In)
7. Webhooks — POST /webhooks pour recevoir des notifications asynchrones de status (alternative recommandée au polling)

Importer dans Insomnia

1. Ouvrez Insomnia
2. Application > Preferences > Data > Import Data
3. Sélectionnez From File et choisissez le JSON
4. Configurez les variables d'environnement avec les mêmes valeurs ci-dessus