Visão geral da Referência

A API REST da Malvo é o coração da plataforma: por ela você gera tokens, gerencia Items e lê todos os dados financeiros normalizados.

Base URL e transporte

Há um único host de API:

https://api.malvo.io

Propriedade	Valor
Transporte	HTTPS apenas, TLS 1.2+
Formato	JSON. Toda requisição com corpo envia `Content-Type: application/json`
Timestamps	ISO-8601 com milissegundos e sufixo `Z`, ex.: `"2025-01-02T08:00:00.000Z"`
IDs	Items e consents: UUID. Conectores: inteiros
Compatibilidade futura	Os clientes devem tolerar campos desconhecidos na resposta

Não existem subdomínios de ambiente. Uma Application possui environment: PRODUCTION|SANDBOX, mas ambas usam o mesmo host. Em produção, sandbox=true em GET /connectors e includeSandbox: true no widget incluem mocks locais explicitamente.

Autenticação

As rotas server-side usam o header X-API-KEY, cujo valor é o apiKey obtido em POST /auth (a partir do clientId + clientSecret do Dashboard). O apiKey vive 2 horas.

clientId + clientSecret  ──POST /auth──▶  apiKey (X-API-KEY, 2h)
                                              │
                                   POST /connect_token
                                              ▼
                                   connectToken (30 min, dirige o widget)

O connectToken serve apenas para o Connect Widget e para ler o próprio Item — qualquer tentativa de ler dados de produto com ele retorna 403. O passo a passo completo está em Autenticação.

clientId, clientSecret e apiKey nunca devem chegar ao navegador. O cliente só vê o connectToken.

Chamada autenticada de exemplo

curl https://api.malvo.io/connectors \
  -H "X-API-KEY: $MALVO_API_KEY"

GET /connectors também serve como teste rápido de validade de um apiKey recém-emitido.

Envelope de erro (`GlobalErrorResponse`)

Toda resposta não-2xx usa o mesmo formato de corpo:

{
  "code": 429,
  "message": "Too many requests. Please try again later (see Retry-After header in seconds)",
  "codeDescription": "TOO_MANY_REQUESTS",
  "data": {}
}

Campo	Tipo	Presença	Notas
`code`	number	sempre	Espelha o status HTTP
`message`	string	sempre	Texto legível. Não é estável — nunca faça parse dele
`codeDescription`	string	opcional	Discriminador estável (SCREAMING_SNAKE_CASE). É nele que os clientes ramificam
`data`	object	opcional	Contexto extra

Erros de validação de parâmetros (POST /items, PATCH /items/{id}) trazem, além disso, um array errors[] com code, message e parameter. Veja a lista completa em Erros.

Paginação

A API oferece dois estilos de paginação:

Por página (page-based)
Por cursor (/v2)

As listas REST clássicas retornam um envelope com total, totalPages, page e results:

{ "total": 1234, "totalPages": 25, "page": 1, "results": [] }

Parâmetros de query: page (1-based, padrão 1) e pageSize (padrão 20). Usado em GET /connectors, GET /transactions, GET /accounts, entre outros.

As rotas /v2 (como GET /v2/transactions) usam paginação por cursor, ideal para sincronização incremental: a resposta carrega um cursor que você passa na próxima chamada para continuar de onde parou, sem reprocessar páginas. Prefira /v2/transactions para manter seus dados em dia.

Detalhes e exemplos em Paginação.

Rate limits

Os limites são aplicados por IP, por minuto, independentemente por grupo de endpoint:

Família de endpoint	Limite (req/min)
`POST /auth`	360
`GET /transactions`, `GET /investments` (e subrotas)	360
`PATCH /items/{id}`	20
Demais endpoints	360

Ao estourar o limite, a resposta é 429 com o envelope TOO_MANY_REQUESTS e os headers RateLimit-Limit, RateLimit-Reset e Retry-After: 60. O PATCH /items/{id} é só para atualizações disparadas pelo usuário — atualizações em massa devem usar o auto-sync, nunca o endpoint em loop. Veja Rate limits.

Os limites acima são da API da Malvo. O Open Finance Brasil impõe cotas mensais próprias por (CPF/CNPJ + instituição + produto), sinalizadas por 423/PARTIAL_SUCCESS. No fluxo internacional, a Malvo respeita limites e Retry-After do ASPSP. Veja Open Finance e Open Banking.

Playground interativo

Cada endpoint nesta Referência tem um playground: preencha o X-API-KEY, ajuste os parâmetros e dispare a chamada direto do navegador, vendo a resposta real. É a forma mais rápida de explorar a API antes de escrever código.

Autenticação

O fluxo completo de apiKey e connectToken.

Quickstart

Do zero ao primeiro Item em poucos minutos.

Visão geral

Autenticação & Conectores

Items

Webhooks

Contas & Faturas

Transações & Categorias

Investimentos, Crédito & Identidade

Inteligência & Enriquecimento

Tabelas de referência

Visão geral da Referência

Base URL e transporte

Autenticação

Chamada autenticada de exemplo

Envelope de erro (`GlobalErrorResponse`)

Paginação

Rate limits

Playground interativo

Autenticação

Quickstart

​Base URL e transporte

​Autenticação

​Chamada autenticada de exemplo

​Envelope de erro (GlobalErrorResponse)

​Paginação

​Rate limits

​Playground interativo

Autenticação

Quickstart

Base URL e transporte

Autenticação

Chamada autenticada de exemplo

Envelope de erro (`GlobalErrorResponse`)

Paginação

Rate limits

Playground interativo