Quickstart

Este guia mostra como configurar sua chave de API e fazer sua primeira requisicao em menos de 5 minutos.

1. Obter sua chave de API

Acesse o painel administrativo da Topo Contabil e navegue ate Configuracoes > Chaves de API. Clique em Gerar nova chave e copie o token gerado.

!

Importante

Guarde sua chave em local seguro. Ela nao sera exibida novamente apos o fechamento do modal. Caso perca a chave, sera necessario gerar uma nova.

As chaves seguem o formato topo_sk_ seguido de uma string alfanumerica. Exemplo:

Formato da chavetext
topo_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

2. Configurar o ambiente

Recomendamos comecar pelo ambiente Sandbox, que possui dados de teste e nao afeta sua conta de producao. Consulte o guia de Ambientes para mais detalhes.

AmbienteURL Base
Sandboxhttps://api-sandbox.topocontabil.com.br
Producaohttps://api.topocontabil.com.br

3. Fazer sua primeira requisicao

Vamos listar os tenants disponiveis para verificar que a autenticacao esta funcionando. Substitua SUA_CHAVE_API pela chave obtida no passo 1.

Listar tenantsbash
curl -X GET https://api-sandbox.topocontabil.com.br/v1/tenants \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "Content-Type: application/json"

Se tudo estiver correto, voce recebera uma resposta como esta:

Respostajson
{
  "data": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "name": "Grupo Exemplo S.A.",
      "slug": "grupo-exemplo",
      "plan": "professional",
      "status": "active",
      "createdAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-01-15T10:30:00Z"
    }
  ],
  "cursor": null,
  "hasMore": false
}

4. Listar conciliacoes

Agora que a autenticacao esta funcionando, vamos buscar as conciliacoes do periodo atual.

Listar conciliacoesbash
curl -X GET "https://api-sandbox.topocontabil.com.br/v1/reconciliations?period=2026-01&limit=10" \
  -H "Authorization: Bearer SUA_CHAVE_API"

5. Importar um balancete

Para importar dados, envie o arquivo como multipart/form-data. Inclua o header Idempotency-Key para evitar duplicacoes.

Importar balancetebash
curl -X POST https://api-sandbox.topocontabil.com.br/v1/imports \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "type=trial_balance" \
  -F "companyId=550e8400-e29b-41d4-a716-446655440000" \
  -F "period=2026-01" \
  -F "file=@balancete-jan-2026.xlsx"
i

Processamento assincrono

Importacoes sao processadas em segundo plano. A API retorna status 202 Accepted imediatamente. Configure um webhook para ser notificado quando o processamento finalizar.

Proximos passos