Consulte o extrato bancário

Obtenha o saldo no provedor, o total agendado e as movimentações da conta bancária vinculada, com paginação por cursor e comprovante de Pix recebido.

GET/api/bank-accounts/{accountNumber}/statementSaldo, agendados e movimentações

O extrato devolve, numa só chamada, o saldo atual da conta bancária, o total agendado e a lista de movimentações do período, como a instituição financeira registrou.

O extrato cobre as contas bancárias vinculadas à sua conta e aos seus recebedores, identificadas pelo número da conta no provedor (accountNumber), informado na abertura de cada uma. Uma conta que não é sua responde 404, com a mesma mensagem de uma conta inexistente.

Para saber quanto pode sacar, use o saldo

O accountNumber do extrato não é o accountId do saldo e do saque, nem o número interno da sua conta na Accelerazione. Para o valor disponível para saque, consulte GET /api/v1/balance. Veja Contas, chaves e identificadores.

A permissão é bank-accounts:read. Sem uma conta bancária vinculada, a resposta é 404 Statement.BankAccountNotFound: ter um accountId não cria esse vínculo. No sandbox, a maioria das contas de teste não tem conta bancária vinculada; peça uma à equipe de integração se precisar homologar o extrato.

Requisição

Terminal

curl "$DM_API_BASE/api/bank-accounts/29600685/statement?from=2026-10-01T00:00:00-03:00&to=2026-10-31T23:59:59-03:00&limit=50" \
  -H "Authorization: $DM_API_KEY"

Parâmetro	Onde	Descrição
`accountNumber`	Rota	Número da conta, sem dígito verificador.
`from`	Consulta	Início do período, em ISO 8601 com fuso (`2026-10-01T00:00:00-03:00`). Opcional.
`to`	Consulta	Fim do período, também com fuso. Opcional. Se `to` for anterior a `from`, a resposta é `400`.
`limit`	Consulta	Movimentações por página. Padrão `50`, máximo `200`. Valores acima de `200` são reduzidos para `200` sem erro.
`cursor`	Consulta	O `nextCursor` da página anterior. Quando presente, `from`, `to` e `limit` são ignorados: o cursor já carrega o período e o tamanho da página.

Sem from e to, a instituição devolve uma janela recente padrão. Para conciliação, sempre envie o período.

Resposta

200 OK

{
  "accountNumber": "29600685",
  "merchantId": "a3b2c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "period": { "from": "2026-10-01T00:00:00-03:00", "to": "2026-10-31T23:59:59-03:00" },
  "currentBalance": { "amount": 183427, "currency": "BRL" },
  "scheduled": { "amount": 0, "currency": "BRL" },
  "entries": [
    {
      "id": "stme-AAECAwQFBgc",
      "postedAt": "2026-10-30T18:32:05-03:00",
      "direction": "credit",
      "amount": { "amount": 14990, "currency": "BRL" },
      "description": "Crédito PIX Maria Souza"
    },
    {
      "id": "stme-CAkKCwwNDg8",
      "postedAt": "2026-10-30T19:02:58-03:00",
      "direction": "debit",
      "amount": { "amount": 25000, "currency": "BRL" },
      "description": "Transferência PIX enviada"
    }
  ],
  "hasMore": true,
  "nextCursor": "stmc-eyJvIjoyLCJmIjoiMjAyNi0xMC0wMVQwMDowMDowMC0wMzowMCJ9"
}

Campo	Descrição
`merchantId`	O recebedor dono da conta.
`currentBalance`	Saldo da conta agora, não o saldo no fim do período.
`scheduled`	Total de lançamentos agendados.
`entries[].id`	Identificador opaco do lançamento (`stme-…`). Guarde como texto de até 255 caracteres.
`entries[].postedAt`	Data do lançamento, sempre com fuso `-03:00`.
`entries[].direction`	`credit` (entrada) ou `debit` (saída). Trate valores desconhecidos sem erro.
`entries[].amount`	Valor sempre positivo. O sentido está em `direction`.
`entries[].description`	Texto da instituição financeira. Pode ser `null`. Não use para lógica.
`hasMore`	Se há mais páginas.
`nextCursor`	Cursor da próxima página. Ausente na última página.

Valores em centavos

Os valores do extrato são inteiros em centavos, como no resto da API: 183427 é R$ 1.834,27. Cada valor vem com a moeda em currency.

Saldo do extrato e saldo para saque

currentBalance é o saldo da conta na instituição financeira. O valor que pode ser sacado é o saldo Available da consulta de saldo, apurado pela Accelerazione, e pode ser menor, por exemplo quando há vendas ainda dentro do prazo de liberação. Se o pedido passar do disponível, a API recusa com withdrawal.insufficient_balance.

Paginação

Percorra as páginas seguindo nextCursor até ele desaparecer. A ausência de nextCursor é o único sinal de fim: uma página com menos itens que limit é normal e não indica a última.

Ler o extrato inteiro de um período

async function readStatement(accountNumber, from, to) {
  const entries = [];
  let url = `${DM_API_BASE}/api/bank-accounts/${accountNumber}/statement?from=${encodeURIComponent(from)}&to=${encodeURIComponent(to)}&limit=200`;

  while (url) {
    const res = await fetch(url, { headers: { Authorization: DM_API_KEY } });
    if (!res.ok) throw new Error(`extrato: HTTP ${res.status}`);
    const page = await res.json();
    entries.push(...page.entries);
    url = page.nextCursor
      ? `${DM_API_BASE}/api/bank-accounts/${accountNumber}/statement?cursor=${encodeURIComponent(page.nextCursor)}`
      : null;
  }
  return entries;
}

Comprovante de Pix recebido

GET/api/bank-accounts/{accountNumber}/statement/{entryId}Detalhe de um lançamento

Para um lançamento de Pix recebido, o detalhe traz o pagador e o recebedor:

200 OK

{
  "id": "stme-AAECAwQFBgc",
  "accountNumber": "29600685",
  "type": "pix_cashin",
  "pix": {
    "endToEndId": "E18236120202610302132Zx9Yw8Vu7Ts",
    "payer": {
      "name": "Maria Souza",
      "document": "***.982.247-**",
      "bankName": "NU PAGAMENTOS - IP",
      "agency": "1",
      "accountNumber": "1234567"
    },
    "payee": {
      "name": "Loja Exemplo LTDA",
      "document": "**.222.333/0001-**",
      "bankName": "PINBANK IP",
      "agency": null,
      "accountNumber": null
    }
  }
}

Hoje, só Pix recebido tem comprovante. Para os demais lançamentos a resposta é 422 Statement.DetailNotAvailable, e o resultado é definitivo: não repita. Os documentos chegam mascarados pela instituição.

Erros do extrato

O extrato responde erros num envelope próprio, com retryable dizendo se vale repetir:

404 Not Found

{
  "error": "Statement.BankAccountNotFound",
  "message": "Bank account '29600685' was not found.",
  "retryable": false,
  "requestId": "0HN7Q2S1A8C3K:00000002"
}

HTTP	`error`	Repetir?	Causa
`400`	`Statement.InvalidPeriod`	Não	`to` anterior a `from`, ou período inválido.
`400`	`Statement.InvalidCursor`	Não	Cursor alterado ou de outro período. Recomece sem cursor.
`404`	`Statement.BankAccountNotFound`	Não	Conta inexistente, que não é sua, ou conta sem vínculo bancário no provedor.
`404`	`Statement.EntryNotFound`	Não	Lançamento inexistente.
`422`	`Statement.DetailNotAvailable`	Não	O lançamento não tem comprovante.
`502`	`Statement.ProviderError`	Não	Erro inesperado da instituição financeira. Fale com a equipe de integração se persistir.
`503`	`AccountsGateway.Unavailable`	Sim	Indisponibilidade temporária.
`504`	`AccountsGateway.Timeout`	Sim	A instituição demorou para responder.

Use retryable para decidir a repetição, com espera crescente. Guarde requestId para o suporte.

Consulte o extrato bancário

RequisiçãoCopiar link da seção

RespostaCopiar link da seção

Valores em centavosCopiar link da seção

Saldo do extrato e saldo para saqueCopiar link da seção

PaginaçãoCopiar link da seção

Comprovante de Pix recebidoCopiar link da seção

Erros do extratoCopiar link da seção