Transaction:
categoryId— o id estável de 8 dígitos (por exemplo"11010000"). Use sempre este campo para joins, agrupamentos e regras.category— o nome legível da categoria (por exemplo"Eating out"). É derivado docategoryIde pode mudar; nunca dependa do texto.
O catálogo
São 130 categorias em até três níveis (pai → filho → neto), cada uma com um id de 8 dígitos. O id codifica a posição na árvore:XX é o índice da categoria de nível 1, YY o índice do filho dentro do pai e ZZ o índice do
neto. Alguns âncoras úteis:
A lista completa fica na tabela de referência: Catálogo de categorias.
Ler o catálogo
GET /categories — listar
Retorna o catálogo no envelope paginado padrão (sempre uma única página, totalPages: 1). Aceite
o parâmetro opcional parentId para listar apenas os filhos de uma categoria.
Resposta 200
Em categorias de nível 1, as chaves
parentId e parentDescription são omitidas (não vêm como
null). Elas só aparecem em filhos e netos.GET /categories/{id} — recuperar uma
Retorna um único objeto Category. Um id inexistente devolve 404 com
codeDescription: "CATEGORY_NOT_FOUND".
Campos do Category
Regras de cliente
Regras permitem forçar uma categoria sempre que a descrição de uma transação casar com um texto. Elas têm escopo de cliente (vinculadas ao seuclientId), não por Item nem por usuário.
POST /categories/rules — criar uma regra
Resposta 200
category na resposta é a descrição resolvida do categoryId. Um categoryId inexistente
devolve 404 CATEGORY_NOT_FOUND; um corpo malformado devolve 400.
GET /categories/rules — listar as regras
Retorna o envelope paginado padrão com results: ClientCategoryRule[].
Corrigir a categoria de uma transação
Para corrigir um lançamento já categorizado, usePATCH /transactions/{id} com o novo categoryId:
200 é a Transaction atualizada (com o novo category e categoryId). A correção é
persistida — leituras seguintes retornam a categoria corrigida — e cria automaticamente uma regra
de cliente para a descrição daquela transação. Ou seja, correções manuais se propagam para
lançamentos futuros semelhantes.
Precedência
A engine resolve a categoria de cada transação nesta ordem:1
Regras de cliente
As regras (
POST /categories/rules e as criadas por PATCH) são aplicadas antes do modelo
e sempre vencem para as linhas que casam.2
Modelo de categorização
Quando nenhuma regra casa, o classificador da Malvo atribui o
categoryId automaticamente
durante a sincronização.Regra do cliente > modelo. Se uma transação casa com uma regra, o rótulo do modelo é ignorado.
Enriquecimento por estabelecimento
Quando a Malvo identifica o estabelecimento (merchant) por trás de uma compra, a transação ganha um objetomerchant com name, businessName, cnpj, cnae e category. Esse dado refina a
categorização — por exemplo, distinguir um streaming de vídeo de uma assinatura genérica.
Trecho de transação enriquecida
GET /merchants?cnpjs=... para
enriquecer transferências sem depender da engine.
Recapitulando
Por que joinar pelo categoryId e não pelo nome?
Por que joinar pelo categoryId e não pelo nome?
Os ids de 8 dígitos são estáveis e nunca mudam. Os nomes em inglês e português podem ser
ajustados. Sua base de dados deve guardar
categoryId; resolva o nome no momento da exibição
consultando o catálogo.Quando devo criar uma regra em vez de corrigir transação a transação?
Quando devo criar uma regra em vez de corrigir transação a transação?
Use
PATCH /transactions/{id} para corrigir um caso pontual — isso já cria a regra
automaticamente. Use POST /categories/rules quando quiser definir o comportamento
proativamente, com matchType e filtros de transactionType/accountType.As regras valem para todos os usuários?
As regras valem para todos os usuários?
Sim. Regras têm escopo de cliente (
clientId), não por Item ou usuário. Uma regra criada vale
para todas as transações de todos os Items da sua aplicação.