Glossário
Os termos do TOPO que aparecem na API, com o campo onde cada um aparece.
Esta página é para quem integra o TOPO sem ser da área contábil. Cada termo diz o que é no dia a dia do cliente e em que campo da API ele aparece.
Termos
| Termo | O que é | Onde aparece na API |
|---|---|---|
| Cliente | A organização que contratou o TOPO. Uma chave de API pertence a um cliente e só enxerga os dados dele. | Não aparece: vem da chave. |
| Empresa | Cada CNPJ que o cliente acompanha no TOPO. Um grupo pode ter controladora e controladas. | companies, companyId, cnpj, empresaId, empresaControladoraId |
| Competência | O mês contábil, no formato AAAA-MM. O balancete de agosto de 2026 é da competência 2026-08. | period no envio, competencia na leitura |
| Plano de contas | A lista de contas contábeis da empresa, com código, descrição e natureza. Uma empresa pode ter mais de um plano ativo, e o balancete diz qual usa. | chart-of-accounts, chartName, planoId |
| Conta analítica | Conta que recebe lançamento e saldo. É a que vai no balancete. | tipo: ANALYTICAL |
| Conta sintética | Conta que só soma outras, como "Ativo Circulante". | tipo: SYNTHETIC |
| Natureza | Se o saldo normal da conta é devedor ou credor. | natureza: DEBIT ou CREDIT |
| Balancete | O saldo de cada conta numa competência: saldo anterior, débitos, créditos e saldo final. Sai do ERP no fechamento do mês. | trial-balances, lineItems |
| Versão do balancete | Reenviar a mesma competência com outro conteúdo cria uma versão nova. A lista mostra a vigente. | versao, reenvio |
| Liberação | O cliente confere o balancete importado e libera. É a liberação que cria as conciliações da competência. | status: RELEASED do balancete |
| Conciliação | A comprovação do saldo de uma conta numa competência: alguém junta extrato, relatório ou planilha que prova que o saldo do balancete está certo, e explica a diferença quando houver. | reconciliations, saldoContabil, saldoConciliado, diferenca, ajustes |
| Conta que exige conciliação | Nem toda conta é conciliada. Só as marcadas no plano entram no balancete importado e ganham conciliação. | exigeConciliacao, ignoradasQueNaoConciliam |
| Etapa | O passo em que a conciliação está: elaboração, revisão da área, supervisão, revisão contábil, aprovação final. Pode ser devolvida para a elaboração em cada passo. | status da conciliação (IN_ELABORATION, AWAITING_FINAL_APPROVAL, APPROVED e os outros da referência) |
| Responsável | A pessoa que tem de agir agora na conciliação, com o papel dela: Elaborador, Revisor Área, Supervisor, Revisor, Aprovador. Na conciliação aprovada, o papel é Concluído. | responsavelNome, responsavelPapel |
| Prazo e SLA | A data limite da etapa atual e se ela está no prazo, vencendo ou vencida. | prazo, slaStatus |
| Fechamento da competência | O cliente encerra a competência quando termina as conciliações. Competência fechada não aceita balancete novo até ser reaberta. | 409 com COMPETENCE_CLOSED ou NEXT_COMPETENCE_CLOSED |
O mesmo dado no envio e na leitura
O envio de balancete usa nomes de campo em inglês, e a leitura usa nomes em português. Os dois descrevem o mesmo dado:
Envio (POST /api/v1/trial-balances) | Leitura (GET /api/v1/trial-balances/{id}/lines) |
|---|---|
companyId | empresaId |
period | competencia |
lineItems[].accountCode | contaCodigo |
lineItems[].accountName | contaDescricao |
lineItems[].previousBalance | saldoAnterior |
lineItems[].debit | debito |
lineItems[].credit | credito |
lineItems[].finalBalance | saldoFinal |
Os nomes da v1 não mudam. Se um dia os dois lados forem unificados, isso vem numa versão nova da API, e a v1 continua respondendo como hoje. Veja mudanças da API.