Paginação

A API da Malvo usa dois formatos de paginação. Saber qual endpoint usa qual evita laços infinitos e perda de dados.

Formato	Onde	Como termina
Baseado em página	Maioria das listas (`/connectors`, `/accounts/{id}/statements`, `/bills`, `/investments`, `/categories`, `/webhooks`, …)	Quando `page >= totalPages`
Baseado em cursor	Apenas `GET /v2/transactions`	Quando `next === null`

GET /v2/transactions é o endpoint atual para transações. A versão antiga, paginada por página (GET /transactions), está depreciada e será removida após 2026-12-31 — mantida apenas por compatibilidade. Use sempre /v2/transactions em integrações novas.

Formato baseado em página

O envelope traz a página atual e o total de resultados:

{
  "page": 1,
  "total": 8,
  "totalPages": 1,
  "results": [
    { "id": "resource-id" }
  ]
}

Campo	Tipo	Notas
`page`	number	Página atual, base 1
`total`	number	Total de resultados em todas as páginas
`totalPages`	number	`ceil(total / pageSize)`
`results`	array	Os recursos desta página

Parâmetros de consulta: page (base 1, padrão 1) e pageSize. Para os endpoints de transações e investimentos o pageSize é 500 por padrão e 500 no máximo.

Como iterar

Incremente page até alcançar totalPages:

Node

async function listAll(url) {
  const results = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await fetch(`${url}&page=${page}&pageSize=500`, {
      headers: { "X-API-KEY": process.env.MALVO_API_KEY },
    });
    const body = await res.json();
    results.push(...body.results);
    totalPages = body.totalPages;
    page += 1;
  } while (page <= totalPages);

  return results;
}

// Ex.: todas as faturas de uma conta de cartão
const bills = await listAll(
  "https://api.malvo.io/bills?accountId=562b795d-1653-429f-be86-74ead9502813"
);

Formato baseado em cursor (`/v2/transactions`)

GET /v2/transactions retorna um cursor opaco em vez de números de página:

{
  "results": [
    {
      "id": "a8534c85-53ce-4f21-94d7-50e9d2ee4957",
      "description": "COMPRA SUPERMERCADO CENTRAL",
      "amount": -212.45,
      "date": "2020-10-15T00:00:00.000Z",
      "category": "Groceries",
      "accountId": "562b795d-1653-429f-be86-74ead9502813",
      "status": "POSTED",
      "type": "DEBIT"
    }
  ],
  "next": "?accountId=562b795d-1653-429f-be86-74ead9502813&after=MjAyMC0xMC0xNVQwMDowMDowMC4wMDBafGE4NTM0Yzg1LTUzY2UtNGYyMS05NGQ3LTUwZTlkMmVlNDk1Nw=="
}

Campo	Tipo	Notas
`results`	`Transaction[]`	As transações desta página
`next`	string \| null	Query string pronta para concatenar (começa com `?`). `null` quando não há mais resultados

O next já vem com accountId e o cursor after. O cursor codifica date|id da última linha em base64 — trate-o como opaco, não tente parsear. Não há parâmetro pageSize no /v2: o servidor controla o tamanho da página (500 por página).

Como iterar

Continue chamando GET /v2/transactions{next} até next virar null:

Node

async function listTransactions(accountId) {
  const results = [];
  // Primeira chamada: monte a query inicial.
  let next = `?accountId=${accountId}`;

  while (next !== null) {
    const res = await fetch(`https://api.malvo.io/v2/transactions${next}`, {
      headers: { "X-API-KEY": process.env.MALVO_API_KEY },
    });
    const body = await res.json();
    results.push(...body.results);
    next = body.next; // null encerra o laço
  }

  return results;
}

const txs = await listTransactions("562b795d-1653-429f-be86-74ead9502813");

A condição de parada é estritamente next === null. Não pare ao ver uma página com menos de 500 itens — o servidor pode entregar páginas parciais e ainda assim trazer um next não nulo.

Sincronização incremental

Para sincronizar apenas o que chegou desde a última leitura, combine o cursor com createdAtFrom (tempo de ingestão). Não combine createdAtFrom com dateFrom na mesma chamada:

Node

const since = "2025-01-01T00:00:00.000Z";
let next = `?accountId=${accountId}&createdAtFrom=${encodeURIComponent(since)}`;
// ...itere como acima até next === null

O melhor gatilho para essa sincronização são os webhooks transactions/created e transactions/updated, e não polling.

Endpoint depreciado: `GET /transactions`

A versão antiga retorna o formato baseado em página e aceita page/pageSize (1–500, padrão 500), além de from/to/ids/billId. Está depreciada (remoção após 2026-12-31). Migre para /v2/transactions e itere pelo cursor, uma vez por sincronização, guiado por webhooks.

Comece aqui

Conceitos

Connect Widget

Webhooks

Guias

Conta & Dashboard

Sandbox & Suporte

Formato baseado em página

Como iterar

Formato baseado em cursor (`/v2/transactions`)

Como iterar

Sincronização incremental

Endpoint depreciado: `GET /transactions`

​Formato baseado em página

​Como iterar

​Formato baseado em cursor (/v2/transactions)

​Como iterar

​Sincronização incremental

​Endpoint depreciado: GET /transactions

Formato baseado em página

Como iterar

Formato baseado em cursor (`/v2/transactions`)

Como iterar

Sincronização incremental

Endpoint depreciado: `GET /transactions`