Extrato

Lista as transações da conta com paginação e filtros.

Endpoint

GET /api/external/statement

Headers

Header	Tipo	Obrigatório	Descrição
Authorization	String	Sim	ApiKey {client_id}:{client_secret}
X-Key-Case	String	Não	Defina como camelCase para receber os campos da resposta em camelCase (padrão é snake_case)

Query Parameters

Parâmetro	Tipo	Obrigatório	Descrição	Default
page	Integer	Não	Número da página	1
per_page	Integer	Não	Itens por página (max 100)	20
status	String	Não	Filtrar pela coluna payment_status. Valores: settled, rejected, failed, processing	--
type	String	Não	Filtrar por tipo (pix, ted, internal)	--
date_from	String	Não	Data inicial (formato YYYY-MM-DD)	--
date_to	String	Não	Data final (formato YYYY-MM-DD)	--

Valores aceitos em status:

• settled: Transações liquidadas (padrão de sucesso)
• rejected: Rejeitadas pelo BACEN
• failed: Falhas internas ou pós-rejeição
• processing: Em processamento

Display vs Filter

O valor exibido no campo status da resposta pode diferir do valor aceito pelo filtro:

• Row com status=2 exibe "pending" mas é filtrada por status=processing
• Row com payment_status=nil e status=1 exibe "completed" mas é filtrada por status=settled

Use os valores do filtro acima; o display é normalizado para consumo cliente.

Exemplo

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"

Resposta de Sucesso (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": "Pedido #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": "Pagamento fornecedor",
      "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
}

Campo	Tipo	Descrição
worked	Boolean	true indica sucesso na operação
data	Array	Lista de transações
page	Integer	Página atual
per_page	Integer	Itens por página

Campos de cada transação

Campo	Tipo	Descrição
id	String	UUID interno da transação
transaction_id	String	Identificador público da transação
end_to_end_id	String	E2E ID do BACEN
external_id	String	Identificador do seu sistema. null se não informado
type	String	Tipo (pix, ted, internal)
status	String	Status da transação (normalizado para display). Ver bloco "Display vs Filter" em Query Parameters.
amount	Integer	Valor em unidades base (÷ 10.000 para reais). 300000 = R$ 30,00
fee_amount	Integer	Tarifa cobrada em unidades base
net_amount	Integer	Valor líquido em unidades base
description	String	Descrição da transação
direction	String	inbound (entrada) ou outbound (saída)
counterparty_name	String	Nome da contraparte
recipient_key	String	Chave PIX do destinatário (apenas saídas)
payer_document	String	CPF/CNPJ do pagador (apenas inbound). null para outbound.
recipient_document	String	CPF/CNPJ do recebedor (apenas outbound). null para inbound.
payer_ispb	String	ISPB da instituição pagadora (apenas inbound). null para outbound.
payer_bank_name	String	Nome do banco pagador resolvido pelo ISPB (apenas inbound). null para outbound.
created_at	String	Data de criação (ISO 8601 UTC)
completed_at	String	Data de conclusão (ISO 8601 UTC). null se ainda não liquidada.

Data em UTC

Todos os campos de data/hora são retornados em ISO 8601 UTC (sufixo Z). Para converter para horário de Brasília (BRT), subtraia 3 horas. O filtro date_from/date_to também é interpretado como UTC — um dia filtrado (date_from=2026-03-07) cobre de 2026-03-07T00:00:00Z até 2026-03-07T23:59:59Z.

In-flight transactions

A página 1 da listagem inclui PIX OUT ainda em voo (tabela outbound_requests, stage < 3) quando não há filtro status aplicado ou status=processing. Isso permite conciliação em tempo real — você vê a transação enquanto ela está sendo processada pelo BACEN, com status="pending", payment_status="processing" e completed_at=null.

Quando você aplica status=settled ou status=rejected, o merge com outbound_requests não é feito — apenas a tabela transactions/failed_transactions é consultada. Isso evita duplicidade quando você só quer transações terminais.

net_amount em outbound é a soma (não subtração)

Em transações outbound (direction="outbound"), o net_amount é calculado como amount + fee_amount (débito total na conta, incluindo a tarifa). Em transações inbound, net_amount = amount - fee_amount (crédito líquido já com a tarifa descontada).

Exemplo outbound: amount=500000, fee_amount=350, net_amount=500350 — R$ 50,035 debitados da sua conta. Não R$ 49,965.

Rate limit e polling

GET /statement passa pelo rate limiter global de /api/external/* (90.000 req/min por IP autenticado). Apenas GET /balance é exceção e não passa pelo limiter. Mesmo assim, evite polling alto neste endpoint — prefira assinar webhooks (pix.charge.paid, pix.payout.confirmed, pix.payout.failed) para notificação em tempo real e use /statement para conciliação periódica (ex: intervalos de 5-15 min ou end-of-day batch).

Permissão

Este endpoint requer statement:read na API Key. O endpoint irmão GET /api/external/transactions (mesma query base, shape quase idêntica) requer transfer:read — caso sua integração use apenas um conjunto de permissões, confirme qual endpoint aceita seus escopos.

Resposta de Erro (401)

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

Paginação

O limite máximo de per_page é 100. Para extrair grandes volumes, itere pelas páginas incrementando o parâmetro page até que a resposta retorne um array data vazio ou com menos itens que per_page.