Enriquecer transações

A Enrich API roda transações de propriedade do cliente através do mesmo classificador que categoriza os Items da Malvo — mas sem exigir um Item nem uma conexão bancária. Você envia as transações que já tem (de qualquer origem: ERP, extrato importado, conciliação) e recebe de volta a categoria, o merchant identificado e a descrição normalizada.

A Enrich API fica no host único da Malvo: POST https://api.malvo.io/categorization. Não existe um subdomínio enrichment-api — todos os produtos de Inteligência & Enriquecimento são servidos em https://api.malvo.io e autenticados pelo header X-API-KEY.

Quando usar

Você já possui transações (não vindas de um Item Malvo) e quer categorizá-las com o catálogo da Malvo. Veja o catálogo em Categorização.
Você quer identificar o estabelecimento (merchant) por trás de uma descrição crua de extrato.
Você quer normalizar descrições (PAGTO PIX MERCADO PAO → Mercado Pão) antes de exibir ao usuário.

Diferente do Item Insights e dos Pagamentos recorrentes, a Enrich API não lê um Item: ela processa exatamente as transações do corpo da requisição.

O payload

Envie um objeto { "transactions": [...] }. Por transação, os campos obrigatórios são id, amount, date e description. Os demais são opcionais, mas melhoram materialmente a precisão do classificador.

Campo	Tipo	Obrigatório	Notas
`id`	string	sim	Seu identificador da transação. É devolvido no resultado para você fazer o join.
`amount`	number	sim	Valor com sinal. Negativo = saída (despesa); positivo = entrada (renda).
`date`	string	sim	Data no formato `yyyy-mm-dd`.
`description`	string	sim	Descrição crua do extrato.
`accountType`	string	não	Subtipo público da conta: `CHECKING_ACCOUNT`, `SAVINGS_ACCOUNT`, `CREDIT_CARD`, `LOAN_ACCOUNT`, `CASH_ACCOUNT` ou `OTHER_ACCOUNT`. Ajuda a desambiguar a categoria.
`isBusinessAccount`	boolean	não	`true` para conta PJ. Muda a categorização (ex.: folha, fornecedores).
`paymentData`	object	não	Dados de Pix/TED com `payer.document` e `receiver.document` (CPF/CNPJ). O CNPJ do recebedor é o sinal mais forte para identificar o merchant.
`creditCardMcc`	number	não	MCC (Merchant Category Code) do cartão, quando disponível.

Até 5.000 transações por requisição. Lotes maiores devem ser divididos — veja Lotes maiores que 5.000 abaixo. Uma requisição com mais de 5.000 itens é rejeitada.

Exemplo de requisição

curl -s -X POST https://api.malvo.io/categorization \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $MALVO_API_KEY" \
  -d '{
    "transactions": [
      {
        "id": "tx-001",
        "amount": -89.90,
        "date": "2026-04-12",
        "description": "PAGTO PIX MERCADO PAO",
        "accountType": "CHECKING_ACCOUNT",
        "isBusinessAccount": false,
        "paymentData": {
          "payer": { "document": "12345678900" },
          "receiver": { "document": "11222333000181" }
        },
        "creditCardMcc": 5411
      }
    ]
  }'

const res = await fetch("https://api.malvo.io/categorization", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-KEY": process.env.MALVO_API_KEY,
  },
  body: JSON.stringify({
    transactions: [
      {
        id: "tx-001",
        amount: -89.9,
        date: "2026-04-12",
        description: "PAGTO PIX MERCADO PAO",
        accountType: "CHECKING_ACCOUNT",
        isBusinessAccount: false,
        paymentData: {
          payer: { document: "12345678900" },
          receiver: { document: "11222333000181" },
        },
        creditCardMcc: 5411,
      },
    ],
  }),
});

const { results } = await res.json();

Ler o response

A resposta é { "results": [...] }, com um resultado por transação enviada, na mesma ordem. Faça o join pelo id que você enviou.

{
  "results": [
    {
      "id": "tx-001",
      "amount": -89.90,
      "date": "2026-04-12",
      "description": "Mercado Pão",
      "type": "DEBIT",
      "merchant": {
        "name": "Mercado Pão",
        "businessName": "Mercado Pão Ltda",
        "cnpj": "11.222.333/0001-81"
      },
      "category": "Eating out"
    }
  ]
}

Campo	Tipo	Notas
`id`	string	O mesmo `id` que você enviou. Use para o join.
`amount`	number	Ecoa o valor enviado.
`date`	string	Ecoa a data enviada.
`description`	string	Descrição normalizada (limpa e legível).
`type`	string	`DEBIT` ou `CREDIT`, derivado do sinal do `amount`.
`merchant`	object \| null	Estabelecimento identificado: `name`, `businessName`, `cnpj`. `null` quando não há identificação.
`category`	string	Nome da categoria (ex.: `Eating out`). Veja o catálogo em Categorização.

O merchant só é preenchido quando há sinal suficiente para identificar o estabelecimento (CNPJ do recebedor em paymentData, MCC, ou a própria descrição). Quanto mais campos opcionais você enviar, maior a taxa de identificação.

Lotes maiores que 5.000

Para enriquecer mais de 5.000 transações, divida em lotes de no máximo 5.000 e faça uma requisição por lote. Os resultados de cada lote vêm com o id original, então você pode reagrupar localmente.

const BATCH = 5000;

function chunk(arr, size) {
  const out = [];
  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size));
  return out;
}

async function enrichAll(transactions) {
  const results = [];
  for (const batch of chunk(transactions, BATCH)) {
    const res = await fetch("https://api.malvo.io/categorization", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-KEY": process.env.MALVO_API_KEY,
      },
      body: JSON.stringify({ transactions: batch }),
    });
    const body = await res.json();
    results.push(...body.results);
  }
  return results; // join pelo id original
}

# Divida o arquivo em lotes de até 5.000 transações antes de enviar.
# Cada chamada processa um lote; reagrupe os results pelo id localmente.
curl -s -X POST https://api.malvo.io/categorization \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $MALVO_API_KEY" \
  --data-binary @lote-01.json

Boas práticas

Envie os campos opcionais que tiver

accountType, isBusinessAccount, paymentData.receiver.document e creditCardMcc melhoram a categoria e a identificação do merchant. O CNPJ do recebedor é o sinal mais forte.

Respeite o sinal do amount

Negativo = despesa, positivo = renda. O type (DEBIT/CREDIT) do response deriva disso.

Faça o join pelo id

Os resultados voltam com o id que você enviou. Não dependa apenas da ordem em integrações assíncronas.

Divida lotes acima de 5.000

Mantenha cada requisição em no máximo 5.000 transações.

Próximos passos

Item Insights

KPIs agregados por Item para crédito e segmentação.

Pagamentos recorrentes

Detecte assinaturas, salários e contas recorrentes de um Item.

Categorização

O catálogo de categorias e o join por categoryId.

Referência da API

O grupo Inteligência & Enriquecimento no playground.

Comece aqui

Conceitos

Connect Widget

Webhooks

Guias

Conta & Dashboard

Sandbox & Suporte

Enriquecer transações

Quando usar

O payload

Exemplo de requisição

Ler o response

Lotes maiores que 5.000

Boas práticas

Próximos passos

Item Insights

Pagamentos recorrentes

Categorização

Referência da API

​Quando usar

​O payload

​Exemplo de requisição

​Ler o response

​Lotes maiores que 5.000

​Boas práticas

​Próximos passos

Item Insights

Pagamentos recorrentes

Categorização

Referência da API

Quando usar

O payload

Exemplo de requisição

Ler o response

Lotes maiores que 5.000

Boas práticas

Próximos passos