Primeira chamada

Este guia é para quem vai testar a API pela primeira vez. No fim você terá listado as empresas do cliente, enviado um balancete de uma conta e visto que reenviar não duplica nada. Cada passo tem o comando em curl, JavaScript (Node 18 ou mais novo) e Python (com requests).

Faça o teste em staging. Os cadastros de lá são separados dos de produção, e nada do que você enviar em staging chega aos dados reais do cliente.

Antes de começar: a chaveCopiar link da seção

A chave de API é gerada pela equipe TOPO, a pedido do cliente. Se você é de uma empresa que integra o sistema de um cliente do TOPO, peça a quem administra o TOPO nesse cliente que abra um chamado ao suporte TOPO, com três informações:

1. o nome do sistema que vai usar a chave, por exemplo "SAP balancete";
2. o ambiente: staging para este teste;
3. os escopos. Para este guia: companies:read, chart_of_accounts:read, trial_balances:write e trial_balances:read.

O suporte entrega a chave uma vez só. A de staging começa com topo_test_. Guarde-a numa variável do terminal, para não repetir o segredo em cada comando:

export TOPO_CHAVE='topo_test_...'
export TOPO_API='https://api-staging.kinho.dev'

A partir daqui, os cinco minutos começam.

1. Liste as empresasCopiar link da seção

curl -s "$TOPO_API/api/v1/companies?limit=2" \
  -H "Authorization: Bearer $TOPO_CHAVE"

Resultado esperado (status 200):

{
  "data": [
    {
      "id": 12,
      "razaoSocial": "Transportes Exemplo Ltda",
      "nomeFantasia": "Exemplo Logística",
      "cnpj": "12345678000190",
      "regimeTributario": "REAL_PROFIT",
      "status": "ACTIVE",
      "empresaControladoraId": null
    }
  ],
  "pagination": { "page": 1, "limit": 2, "total": 1, "pages": 1 }
}

Anote o id e o cnpj da empresa. As outras rotas aceitam um ou outro.

2. Descubra um código de contaCopiar link da seção

O balancete só aceita contas que existem no plano de contas da empresa no TOPO e que entram na conciliação (exigeConciliacao: true). Pegue o nome do plano e uma conta dele:

curl -s "$TOPO_API/api/v1/chart-of-accounts?companyId=12" \
  -H "Authorization: Bearer $TOPO_CHAVE"
# pegue o "id" do plano e liste as contas dele
curl -s "$TOPO_API/api/v1/chart-of-accounts/58/accounts?limit=5" \
  -H "Authorization: Bearer $TOPO_CHAVE"

Sem o escopo chart_of_accounts:read, pule este passo e use o código de uma conta que você já sabe que existe no plano da empresa.

3. Envie um balanceteCopiar link da seção

O balancete vai em JSON, com a competência em period (AAAA-MM), o nome do plano em chartName e uma linha por conta. Troque o CNPJ, o plano e o código da conta pelos que você anotou. Mande sempre o chartName: uma empresa pode ter mais de um plano ativo, e o TOPO usa o plano que o balancete indica.

curl -s -X POST "$TOPO_API/api/v1/trial-balances" \
  -H "Authorization: Bearer $TOPO_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "cnpj": "12.345.678/0001-90",
    "period": "2026-08",
    "chartName": "Plano de Contas Exemplo",
    "lineItems": [
      { "accountCode": "1.1.01.001", "accountName": "Caixa Geral",
        "previousBalance": 1000, "debit": 250, "credit": 100, "finalBalance": 1150 }
    ]
  }'

Resultado esperado (status 201):

{
  "success": true,
  "data": {
    "trialBalanceId": 318,
    "reenvio": false,
    "enviadas": 1,
    "importadas": 1,
    "ignoradasForaDoPlano": 0,
    "ignoradasQueNaoConciliam": 0,
    "avisos": []
  }
}

enviadas é quantas linhas vieram, e importadas é quantas entraram no balancete. Conta que não existe no plano fica de fora e aparece em ignoradasForaDoPlano.

4. Reenvie e veja que nada duplicaCopiar link da seção

Mande o mesmo comando outra vez. Como o conteúdo é igual, o TOPO não grava nada e responde 200 com reenvio: true e o mesmo trialBalanceId. Trate 200 e 201 como sucesso. Veja reenvio e versões.

5. Confira que o balancete chegouCopiar link da seção

curl -s "$TOPO_API/api/v1/trial-balances?companyId=12&period=2026-08" \
  -H "Authorization: Bearer $TOPO_CHAVE"

A resposta mostra a versão vigente, o status e quem importou. No TOPO, o balancete fica na competência 08/2026 da empresa até o cliente conferir e liberar as conciliações. Para acompanhar as conciliações depois, use GET /api/v1/reconciliations (escopo reconciliations:read), como na receita de BI.

Quando der erradoCopiar link da seção

Toda resposta traz o cabeçalho X-Request-Id. Guarde esse valor no log da integração: com ele o suporte TOPO acha a sua chamada. A lista completa está em erros e códigos.