Sincronizar transações

A forma correta de manter as transações de um usuário em dia é dirigida por webhooks: você assina transactions/created, transactions/updated e transactions/deleted, e a cada evento puxa as transações de forma incremental e aplica um upsert (ou delete) por id. Nada de polling em intervalo fixo.

Há um único host de API: https://api.malvo.io. Toda leitura de transação é server-side com o header X-API-KEY. Os webhooks são a fonte da verdade do que mudou.

Por que webhooks, e não polling

transactions/created

Novas transações detectadas durante o sync. Traz itemId e transactionsCount.

transactions/updated

Transações existentes mudaram (ex.: PENDING → POSTED). Traz itemId e transactionsCount.

transactions/deleted

Transações removidas (merge de duplicatas no Open Finance). Traz transactionIds inline.

Em transactions/created e transactions/updated, liste as contas do itemId e pagine GET /v2/transactions?accountId=... para cada conta. Use createdAtFrom para puxar somente o que entrou desde a última sincronização. O payload não traz accountId nem link de transações.

1. Pagine /v2/transactions por cursor

O endpoint atual é GET /v2/transactions, paginado por cursor. A resposta traz results e um campo next: uma query string pronta para anexar à URL. Você continua chamando enquanto next não for null.

Resposta de /v2/transactions

{
  "results": [
    {
      "id": "a8534c85-53ce-4f21-94d7-50e9d2ee4957",
      "description": "PAGAMENTO RECEBIDO",
      "amount": 1500,
      "date": "2026-06-15T00:00:00.000Z",
      "accountId": "562b795d-1653-429f-be86-74ead9502813",
      "status": "POSTED",
      "type": "CREDIT"
    }
  ],
  "next": "?accountId=562b795d-1653-429f-be86-74ead9502813&after=MjAyMC0xMC0xNV..."
}

status=UNKNOWN é um registro válido cujo provedor não enquadrou o lançamento como liquidado ou pendente. Preserve-o e consulte providerStatus (por exemplo, OTHR em alguns ASPSPs); não o trate como delete. Cancelamentos/rejeições confirmados chegam por transactions/deleted.

Loop até next === null (Node)

async function* fetchAllTransactions(accountId, { createdAtFrom } = {}) {
  const headers = { "X-API-KEY": process.env.MALVO_API_KEY };
  const base = "https://api.malvo.io/v2/transactions";

  // primeira página: monta a query inicial
  const params = new URLSearchParams({ accountId });
  if (createdAtFrom) params.set("createdAtFrom", createdAtFrom);
  let url = `${base}?${params.toString()}`;

  while (url) {
    const page = await fetch(url, { headers }).then((r) => r.json());
    for (const tx of page.results) yield tx;

    // next já vem como "?accountId=...&after=..." — basta anexar ao base
    url = page.next ? `${base}${page.next}` : null;
  }
}

Não há parâmetro pageSize no /v2/transactions: o servidor controla o tamanho da página (500 por página). O cursor after é opaco — trate como string e não tente decodificá-lo.

2. Sync incremental com createdAtFrom

Para uma sincronização incremental, filtre por createdAtFrom (horário de ingestão, formato yyyy-mm-ddThh:mm:ss.000Z). Guarde o maior createdAt que você já processou e use-o como createdAtFrom na próxima execução.

GET incremental

curl "https://api.malvo.io/v2/transactions?accountId=<accountId>&createdAtFrom=2026-06-15T00:00:00.000Z" \
  -H "X-API-KEY: $MALVO_API_KEY"

createdAtFrom não pode ser combinado com dateFrom no mesmo request. Use createdAtFrom para sync incremental (o que entrou desde a última coleta) e dateFrom/dateTo para janelas por data da transação.

3. Upsert por id, delete por id

Como os webhooks não têm ordem garantida e podem ser reentregues, a regra de ouro é tornar a escrita idempotente: faça upsert por id da transação. Em transactions/deleted, apague por id.

Aplicar transações no seu banco

async function upsertTransactions(transactions) {
  for (const tx of transactions) {
    await db.transactions.upsert({
      where: { id: tx.id }, // chave: id da transação
      create: mapTransaction(tx),
      update: mapTransaction(tx),
    });
  }
}

async function deleteTransactions(transactionIds) {
  await db.transactions.deleteMany({ where: { id: { in: transactionIds } } });
}

O payload de transactions/deleted traz os ids inline (sem link):

Webhook transactions/deleted

{
  "event": "transactions/deleted",
  "eventId": "a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",
  "itemId": "de7bbf5a-abf2-47e4-94b1-586b36758423",
  "transactionIds": ["tx-uuid-1", "tx-uuid-2"],
  "transactionsCount": 2,
  "triggeredBy": "SYNC",
  "clientUserId": "client-user-id"
}

4. Worker de exemplo

Junte tudo em um worker que reage aos webhooks. Cada execução faz uma sincronização, seguindo o link do evento (ou paginando /v2/transactions), e aplica os efeitos por id.

Worker dirigido por webhook (Node)

app.post("/webhooks/malvo", async (req, res) => {
  res.sendStatus(200); // responda 2XX em < 5s; processe assíncrono

  const evt = req.body;

  // idempotência: o mesmo eventId é reusado em redeliveries
  if (await alreadyProcessed(evt.eventId)) return;

  switch (evt.event) {
    case "transactions/created":
    case "transactions/updated": {
      const accounts = await listAccounts(evt.itemId);
      for (const account of accounts) {
        for await (const tx of fetchAllTransactions(account.id, {
          createdAtFrom: await lastIngestedAt(account.id),
        })) {
          await upsertTransactions([tx]);
        }
      }
      break;
    }
    case "transactions/deleted": {
      await deleteTransactions(evt.transactionIds);
      break;
    }
  }

  await markProcessed(evt.eventId);
});

async function listAccounts(itemId) {
  const res = await fetch(`https://api.malvo.io/accounts?itemId=${encodeURIComponent(itemId)}`, {
    headers: { "X-API-KEY": process.env.MALVO_API_KEY },
  });
  return (await res.json()).results;
}

Boas práticas

Uma sync por execução

Cada webhook dispara exatamente uma sincronização da conta afetada. Não acumule nem rode em paralelo várias coletas da mesma conta.

Dirigido por webhook

Prefira os webhooks transactions/* a polling. Quando precisar puxar manualmente, use createdAtFrom em /v2/transactions, uma vez por sincronização.

Upsert por id

Escreva sempre por id da transação. Como os eventos não têm ordem e podem repetir, o upsert idempotente evita duplicatas.

Dedupe pelo eventId

Persista o eventId e ignore entregas repetidas antes de aplicar efeitos colaterais.

Use GET /v2/transactions (cursor) para qualquer sincronização nova. O antigo GET /transactions (paginado por page/pageSize) é descontinuado — mantido só por compatibilidade.

Próximos passos

Conectar um banco

O fluxo ponta a ponta que cria o Item de onde vêm as transações.

Webhooks

Os payloads exatos de transactions/created, transactions/updated e transactions/deleted.

Comece aqui

Conceitos

Connect Widget

Webhooks

Guias

Conta & Dashboard

Sandbox & Suporte

Sincronizar transações

Por que webhooks, e não polling

transactions/created

transactions/updated

transactions/deleted

1. Pagine /v2/transactions por cursor

2. Sync incremental com createdAtFrom

3. Upsert por id, delete por id

4. Worker de exemplo

Boas práticas

Uma sync por execução

Dirigido por webhook

Upsert por id

Dedupe pelo eventId

Próximos passos

Conectar um banco

Webhooks

​Por que webhooks, e não polling

transactions/created

transactions/updated

transactions/deleted

​1. Pagine /v2/transactions por cursor

​2. Sync incremental com createdAtFrom

​3. Upsert por id, delete por id

​4. Worker de exemplo

​Boas práticas

Uma sync por execução

Dirigido por webhook

Upsert por id

Dedupe pelo eventId

​Próximos passos

Conectar um banco

Webhooks

Por que webhooks, e não polling

1. Pagine /v2/transactions por cursor

2. Sync incremental com createdAtFrom

3. Upsert por id, delete por id

4. Worker de exemplo

Boas práticas

Próximos passos