Referência da API
Como integrar o ERP, o BI ou um script ao TOPO pela API.
Esta seção é para quem vai ligar outro sistema ao TOPO: o time de TI do cliente, o consultor SAP ou quem monta os painéis de BI. Você não precisa de login no TOPO para ler nada daqui.
Com a API você consegue:
- enviar o balancete de cada competência direto do ERP, em JSON ou no mesmo arquivo que o usuário subiria na tela;
- ler empresas, planos de contas, contas, balancetes e conciliações para montar relatórios no Power BI ou no Excel, por REST ou por GraphQL.
Por onde começar
- Peça a chave de API ao suporte TOPO por um chamado. O chamado é aberto por quem administra o TOPO no cliente: se você é de uma empresa que integra o sistema do cliente, peça a essa pessoa. Diga qual sistema vai usar a chave e o que ele precisa fazer (enviar balancete, ler dados para BI ou os dois). A equipe TOPO gera a chave com os escopos certos e entrega o segredo uma vez só.
- Siga a primeira chamada: em cinco minutos você lista as empresas e envia um balancete de teste, com
curl, JavaScript ou Python. - Leia autenticação antes de colocar a chave no sistema de produção.
- Use a receita do SAP ou a receita de BI, conforme o caso, e consulte a referência para cada campo.
Os dois ambientes
| Ambiente | Endereço da API | Para quê |
|---|---|---|
| Produção | https://api.topocontabil.com.br | Os dados reais do cliente. |
| Staging | https://api-staging.kinho.dev | Testes de integração, com cadastros próprios. |
Cada ambiente tem as suas chaves e os seus cadastros. Uma chave de staging começa com topo_test_ e não funciona em produção. Uma empresa cadastrada só em produção responde 404 em staging.
O que existe hoje
| Rota | O que faz | Escopo da chave |
|---|---|---|
POST /api/v1/trial-balances | Envia o balancete em JSON | trial_balances:write |
POST /api/v1/trial-balances/arquivo | Envia o balancete em arquivo | trial_balances:write |
GET /api/v1/companies | Lista as empresas | companies:read |
GET /api/v1/chart-of-accounts | Lista os planos de contas de uma empresa | chart_of_accounts:read |
GET /api/v1/chart-of-accounts/{id}/accounts | Lista as contas de um plano | chart_of_accounts:read |
GET /api/v1/trial-balances | Lista os balancetes | trial_balances:read |
GET /api/v1/trial-balances/{id}/lines | Linhas de um balancete | trial_balances:read |
GET /api/v1/reconciliations | Lista as conciliações | reconciliations:read |
POST /api/v1/graphql | Os mesmos dados de leitura, em GraphQL | analytics:read |
A chave só enxerga as empresas do próprio cliente e só os módulos que cada empresa contratou. As mensagens de erro e os avisos saem em português.
Acompanhar o que muda no TOPO
A API não avisa o seu sistema quando algo muda no TOPO. Para acompanhar, consulte de tempos em tempos: GET /api/v1/trial-balances?period=AAAA-MM mostra se o balancete da competência foi liberado, e GET /api/v1/reconciliations?period=AAAA-MM mostra a etapa, o responsável e o prazo de cada conciliação. Uma consulta a cada 15 minutos por competência cabe folgada no limite.
Para consultar
- Glossário: conciliação, balancete, competência, etapa, responsável e o campo de cada um.
- Contrato OpenAPI: o arquivo para o Postman, o Insomnia ou um gerador de código.
- Mudanças da API: o que mudou e o que a v1 promete não quebrar.