Relevé

Liste les transactions du compte avec pagination et filtres.

Endpoint

GET /api/external/statement

Headers

Header	Type	Obligatoire	Description
Authorization	String	Oui	ApiKey {client_id}:{client_secret}
X-Key-Case	String	Non	Définissez à camelCase pour recevoir les champs de la réponse en camelCase (par défaut snake_case)

Query Parameters

Paramètre	Type	Obligatoire	Description	Default
page	Integer	Non	Numéro de page	1
per_page	Integer	Non	Items par page (max 100)	20
status	String	Non	Filtrer par la colonne payment_status. Valeurs : settled, rejected, failed, processing	--
type	String	Non	Filtrer par type (pix, ted, internal)	--
date_from	String	Non	Date initiale (format YYYY-MM-DD)	--
date_to	String	Non	Date finale (format YYYY-MM-DD)	--

Valeurs acceptées dans status :

• settled : Transactions liquidées (pattern de succès)
• rejected : Rejetées par le BACEN
• failed : Échecs internes ou post-rejection
• processing : En traitement

Display vs Filter

La valeur affichée dans le champ status de la réponse peut différer de la valeur acceptée par le filtre :

• Row avec status=2 affiche "pending" mais est filtrée par status=processing
• Row avec payment_status=nil et status=1 affiche "completed" mais est filtrée par status=settled

Utilisez les valeurs du filtre ci-dessus ; l'affichage est normalisé pour la consommation client.

Exemple

curl -X GET "https://api.owem.com.br/api/external/statement?page=1&per_page=20&status=settled&date_from=2026-03-01&date_to=2026-03-07" \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

Réponse de succès (200)

{
  "worked": true,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "transaction_id": "7popu57v6us7p6pcicgq12345",
      "end_to_end_id": "E37839059202603071530000001",
      "external_id": "order-9876",
      "type": "pix",
      "status": "settled",
      "amount": 300000,
      "fee_amount": 0,
      "net_amount": 300000,
      "description": "Commande #1234",
      "direction": "inbound",
      "counterparty_name": "Maria Santos",
      "created_at": "2026-03-07T15:30:00Z",
      "completed_at": "2026-03-07T15:30:02Z"
    },
    {
      "id": "f7e8d9c0-b1a2-4c3d-9e8f-7a6b5c4d3e2f",
      "transaction_id": "PIXOUT20260306x9y8z7w6v5u4",
      "end_to_end_id": "E37839059202603061200000005",
      "external_id": "invoice-4521",
      "type": "pix",
      "status": "settled",
      "amount": 500000,
      "fee_amount": 350,
      "net_amount": 500350,
      "description": "Paiement fournisseur",
      "direction": "outbound",
      "counterparty_name": "Joao Silva",
      "recipient_key": "12345678901",
      "created_at": "2026-03-06T12:00:00Z",
      "completed_at": "2026-03-06T12:00:03Z"
    }
  ],
  "page": 1,
  "per_page": 20
}

Champ	Type	Description
worked	Boolean	true indique le succès de l'opération
data	Array	Liste des transactions
page	Integer	Page actuelle
per_page	Integer	Items par page

Champs de chaque transaction

Champ	Type	Description
id	String	UUID interne de la transaction
transaction_id	String	Identifiant public de la transaction
end_to_end_id	String	E2E ID du BACEN
external_id	String	Identifiant de votre système. null s'il n'est pas renseigné
type	String	Type (pix, ted, internal)
status	String	Status de la transaction (normalisé pour l'affichage). Voir bloc « Display vs Filter » dans Query Parameters.
amount	Integer	Valeur en unités de base (÷ 10 000 pour reais). 300000 = R$ 30,00
fee_amount	Integer	Frais prélevés en unités de base
net_amount	Integer	Valeur nette en unités de base
description	String	Description de la transaction
direction	String	inbound (entrée) ou outbound (sortie)
counterparty_name	String	Nom de la contrepartie
recipient_key	String	Clé PIX du destinataire (uniquement sorties)
payer_document	String	CPF/CNPJ du payeur (uniquement inbound). null pour outbound.
recipient_document	String	CPF/CNPJ du bénéficiaire (uniquement outbound). null pour inbound.
payer_ispb	String	ISPB de l'institution payeuse (uniquement inbound). null pour outbound.
payer_bank_name	String	Nom de la banque payeuse résolu par l'ISPB (uniquement inbound). null pour outbound.
created_at	String	Date de création (ISO 8601 UTC)
completed_at	String	Date de conclusion (ISO 8601 UTC). null si pas encore liquidée.

Date en UTC

Tous les champs date/heure sont retournés en ISO 8601 UTC (suffixe Z). Pour convertir en heure de Brasília (BRT), soustrayez 3 heures. Le filtre date_from/date_to est également interprété en UTC — un jour filtré (date_from=2026-03-07) couvre de 2026-03-07T00:00:00Z à 2026-03-07T23:59:59Z.

In-flight transactions

La page 1 du listing inclut les PIX OUT encore en vol (table outbound_requests, stage < 3) quand aucun filtre status n'est appliqué ou status=processing. Cela permet une conciliation en temps réel — vous voyez la transaction pendant qu'elle est traitée par le BACEN, avec status="pending", payment_status="processing" et completed_at=null.

Quand vous appliquez status=settled ou status=rejected, le merge avec outbound_requests n'est pas effectué — seule la table transactions/failed_transactions est consultée. Cela évite la duplication quand vous voulez uniquement des transactions terminales.

net_amount en outbound est la somme (pas la soustraction)

Dans les transactions outbound (direction="outbound"), le net_amount est calculé comme amount + fee_amount (débit total sur le compte, y compris les frais). Dans les transactions inbound, net_amount = amount - fee_amount (crédit net déjà frais déduits).

Exemple outbound : amount=500000, fee_amount=350, net_amount=500350 — R$ 50,035 débités de votre compte. Pas R$ 49,965.

Rate limit et polling

GET /statement passe par le rate limiter global de /api/external/* (90 000 req/min par IP authentifié). Seul GET /balance est exempt de ce limiter. Malgré cela, évitez un polling élevé sur cet endpoint — préférez vous abonner aux webhooks (pix.charge.paid, pix.payout.confirmed, pix.payout.failed) pour les notifications en temps réel et utilisez /statement pour la conciliation périodique (ex. : intervalles de 5-15 min ou batch de fin de journée).

Permission

Cet endpoint exige statement:read sur l'API Key. L'endpoint jumeau GET /api/external/transactions (même query base, shape quasi identique) exige transfer:read — si votre intégration n'utilise qu'un seul ensemble de permissions, confirmez quel endpoint accepte vos scopes.

Réponse d'erreur (401)

{
  "worked": false,
  "errors": {
    "unauthorized": "Missing API key credentials. Use Authorization: ApiKey <client_id>:<client_secret>"
  }
}

Pagination

La limite maximale de per_page est de 100. Pour extraire de grands volumes, itérez à travers les pages en incrémentant le paramètre page jusqu'à ce que la réponse retourne un array data vide ou avec moins d'items que per_page.