Extracto

Lista las transacciones de la cuenta con paginacion y filtros.

Endpoint

GET /api/external/statement

Headers

Header	Tipo	Obligatorio	Descripcion
Authorization	String	Si	ApiKey {client_id}:{client_secret}
X-Key-Case	String	No	Defina como camelCase para recibir los campos de la respuesta en camelCase (default es snake_case)

Query Parameters

Parametro	Tipo	Obligatorio	Descripcion	Default
page	Integer	No	Numero de pagina	1
per_page	Integer	No	Items por pagina (max 100)	20
status	String	No	Filtrar por la columna payment_status. Valores: settled, rejected, failed, processing	--
type	String	No	Filtrar por tipo (pix, ted, internal)	--
date_from	String	No	Fecha inicial (formato YYYY-MM-DD)	--
date_to	String	No	Fecha final (formato YYYY-MM-DD)	--

Valores aceptados en status:

• settled: Transacciones liquidadas (default de exito)
• rejected: Rechazadas por el BACEN
• failed: Fallas internas o pos-rechazo
• processing: En procesamiento

Display vs Filter

El valor exhibido en el campo status de la respuesta puede diferir del valor aceptado por el filtro:

• Row con status=2 exhibe "pending" pero es filtrada por status=processing
• Row con payment_status=nil y status=1 exhibe "completed" pero es filtrada por status=settled

Use los valores del filtro arriba; el display es normalizado para consumo cliente.

Ejemplo

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"

Respuesta de Exito (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	Descripcion
worked	Boolean	true indica exito en la operacion
data	Array	Lista de transacciones
page	Integer	Pagina actual
per_page	Integer	Items por pagina

Campos de cada transaccion

Campo	Tipo	Descripcion
id	String	UUID interno de la transaccion
transaction_id	String	Identificador publico de la transaccion
end_to_end_id	String	E2E ID del BACEN
external_id	String	Identificador de su sistema. null si no informado
type	String	Tipo (pix, ted, internal)
status	String	Status de la transaccion (normalizado para display). Ver bloque "Display vs Filter" en Query Parameters.
amount	Integer	Valor en unidades base (÷ 10.000 para reales). 300000 = R$ 30,00
fee_amount	Integer	Tarifa cobrada en unidades base
net_amount	Integer	Valor neto en unidades base
description	String	Descripcion de la transaccion
direction	String	inbound (entrada) o outbound (salida)
counterparty_name	String	Nombre de la contraparte
recipient_key	String	Clave PIX del destinatario (solo salidas)
payer_document	String	CPF/CNPJ del pagador (solo inbound). null para outbound.
recipient_document	String	CPF/CNPJ del receptor (solo outbound). null para inbound.
payer_ispb	String	ISPB de la institucion pagadora (solo inbound). null para outbound.
payer_bank_name	String	Nombre del banco pagador resuelto por el ISPB (solo inbound). null para outbound.
created_at	String	Fecha de creacion (ISO 8601 UTC)
completed_at	String	Fecha de conclusion (ISO 8601 UTC). null si aun no liquidada.

Fecha en UTC

Todos los campos de fecha/hora son retornados en ISO 8601 UTC (sufijo Z). Para convertir a horario de Brasilia (BRT), substraiga 3 horas. El filtro date_from/date_to tambien es interpretado como UTC — un dia filtrado (date_from=2026-03-07) cubre de 2026-03-07T00:00:00Z hasta 2026-03-07T23:59:59Z.

In-flight transactions

La pagina 1 del listado incluye PIX OUT aun en vuelo (tabla outbound_requests, stage < 3) cuando no hay filtro status aplicado o status=processing. Esto permite conciliacion en tiempo real — usted ve la transaccion mientras esta siendo procesada por el BACEN, con status="pending", payment_status="processing" y completed_at=null.

Cuando usted aplica status=settled o status=rejected, el merge con outbound_requests no es hecho — solo la tabla transactions/failed_transactions es consultada. Esto evita duplicidad cuando usted solo quiere transacciones terminales.

net_amount en outbound es la suma (no substraccion)

En transacciones outbound (direction="outbound"), el net_amount es calculado como amount + fee_amount (debito total en la cuenta, incluyendo la tarifa). En transacciones inbound, net_amount = amount - fee_amount (credito neto ya con la tarifa descontada).

Ejemplo outbound: amount=500000, fee_amount=350, net_amount=500350 — R$ 50,035 debitados de su cuenta. No R$ 49,965.

Rate limit y polling

GET /statement pasa por el rate limiter global de /api/external/* (90.000 req/min por IP autenticado). Solo GET /balance esta exento de ese limiter. Aun asi, evite polling alto en este endpoint — prefiera suscribir webhooks (pix.charge.paid, pix.payout.confirmed, pix.payout.failed) para notificacion en tiempo real y use /statement para conciliacion periodica (ej: intervalos de 5-15 min o end-of-day batch).

Permiso

Este endpoint requiere statement:read en la API Key. El endpoint hermano GET /api/external/transactions (misma query base, shape casi identica) requiere transfer:read — caso su integracion use solo un conjunto de permisos, confirme cual endpoint acepta sus alcances.

Respuesta de Error (401)

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

Paginacion

El limite maximo de per_page es 100. Para extraer grandes volumenes, itere por las paginas incrementando el parametro page hasta que la respuesta retorne un array data vacio o con menos items que per_page.