Categorias financeiras

Uma categoria financeira (/financial-categories) classifica para onde o dinheiro vai ou de onde ele vem: "Vendas de produtos", "Aluguel", "Folha de pagamento". É o plano de contas do tenant — contas a receber e contas a pagar apontam para uma categoria através do campo financial_category_id.

Permissão exigida: financial-categories (ações create, read, update, delete).

Conceitos e campos-chave

Hierarquia

Categorias formam uma árvore, com três regras que a API impõe na criação e na atualização:

1. Profundidade máxima de 3 níveis. Uma quarta geração é rejeitada.
2. O type da filha tem que ser igual ao da mãe. Não existe subcategoria de despesa dentro de uma categoria de receita.
3. Sem ciclos. Uma categoria não pode ser mãe de si mesma, nem de uma ancestral sua.

Nome duplicado sob a mesma mãe retorna 409 Conflict. Duas categorias com o mesmo nome em mães diferentes são permitidas.

Quais categorias podem ser usadas em documentos

Nem toda categoria aceita vínculo com um documento financeiro. Ao informar financial_category_id em uma conta a pagar ou a receber, a API exige que a categoria seja:

• Folha — categorias que têm filhas servem para agrupar, não para lançar. Vincular uma categoria com filhas é rejeitado.
• Destravada — uma categoria com is_locked: true continua existindo e mantém o histórico dos documentos que já a usavam, mas é recusada em novos documentos. É como aposentar uma categoria sem apagar o passado.

Criar uma categoria

curl -X POST https://api.biterp.ai/financial-categories \
  -H "Authorization: Bearer sk_abc123_secretXYZ" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Vendas de produtos",
    "type": "revenue",
    "code": "3.01.001",
    "position": 1
  }'

Para criar uma subcategoria, informe o parent_id e repita o type da mãe:

curl -X POST https://api.biterp.ai/financial-categories \
  -H "Authorization: Bearer sk_abc123_secretXYZ" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Vendas no varejo",
    "type": "revenue",
    "parent_id": "7b3e9d1c-4a2f-4e8b-9c0d-5f1a3b7e2d64",
    "position": 1
  }'

Ler a árvore inteira

GET /financial-categories/tree devolve a hierarquia já montada — cada categoria traz suas filhas em children[], recursivamente. É a chamada indicada para popular um seletor na sua interface, porque evita reconstruir a árvore a partir da listagem plana.

# Só a árvore de despesas
curl "https://api.biterp.ai/financial-categories/tree?type=expense" \
  -H "Authorization: Bearer sk_abc123_secretXYZ"

O query param type é opcional e aceita revenue ou expense; sem ele, a resposta traz as duas árvores. Diferente de GET /financial-categories, este endpoint não é paginado.

Listar e manter

GET /financial-categories retorna a lista plana e paginada (ver filtros e paginação).

Campos filtráveis: type, parent_id, reference_code, name, code, position, is_locked, created_at, updated_at. Ordenação por id, type, parent_id, reference_code, name, code, position, is_locked, created_at, updated_at — o padrão é position:asc.

No contrato de filtros deste recurso, apenas reference_code é anulável — então só ele aceita os operadores is_null / is_not_null. É o caminho para achar o que ainda não foi mapeado a partir do seu sistema:

GET /financial-categories?type=expense&reference_code[is_null]=true

DELETE /financial-categories/{id} faz soft delete e responde 204 No Content. Não há endpoint de restauração — ver DELETE é de mão única. Para tirar uma categoria de circulação sem perdê-la, prefira is_locked: true.

Referência dos endpoints

Veja também