Mudanças da API

Esta página é para quem mantém uma integração no ar. Ela lista o que mudou na API v1 e diz o que o TOPO promete não quebrar.

O que a v1 prometeCopiar link da seção

• A versão está no caminho: toda rota começa com /api/v1/. Uma mudança que quebre integração existente vai para /api/v2/, e a v1 continua no ar.
• Na v1 só entra mudança que soma: rota nova, campo novo na resposta, parâmetro opcional novo, código de erro novo. Programe a integração para ignorar campo que ela não conhece.
• Campo, rota ou escopo que existe não muda de nome nem de tipo, e não sai.
• A mudança entra primeiro em staging e só depois em produção.

O número em info.version do contrato em /api/v1/docs-json é a versão do TOPO publicada no ambiente, e muda a cada publicação. A versão da API é o v1 do caminho.

2026Copiar link da seção

28/09Copiar link da seção

• Contrato OpenAPI com uma tag por assunto (Empresas, Planos de contas, Balancetes, Conciliações, GraphQL) no lugar de duas.
• O status da conciliação lista os 16 estados reais do fluxo, e o slaStatus os cinco do prazo. A descrição anterior citava estados que a API não devolve.
• Toda resposta do contrato documenta o cabeçalho X-Request-Id.
• Contrato para baixar e importar no Postman ou no Insomnia. Veja contrato OpenAPI.

27/09Copiar link da seção

• Mensagens e avisos dizem "cliente" onde diziam "escritório".

26/09Copiar link da seção

• Leitura para BI: GET /api/v1/companies, /chart-of-accounts, /chart-of-accounts/{id}/accounts, /trial-balances, /trial-balances/{id}/lines, /reconciliations e POST /api/v1/graphql, com os escopos de leitura.
• POST /api/v1/trial-balances/arquivo: o balancete no mesmo arquivo que o usuário sobe na tela, com o mapeamento de colunas salvo para a empresa.
• Chave aceita em Authorization: Basic, além de Bearer e X-API-Key. Chave de staging começa com topo_test_.
• Envio para competência fechada responde 409 com COMPETENCE_CLOSED ou NEXT_COMPETENCE_CLOSED.
• O balancete confere CNPJ e competência em todas as linhas, e confere débito, crédito e saldo de cada conta.
• Cada chamada fica registrada no TOPO com o nome da chave que a fez.

15/09Copiar link da seção

• Primeira versão pública: POST /api/v1/trial-balances, com chave de API por cliente e escopo trial_balances:write.