Layouts de importação
Os arquivos que o TOPO aceita e as colunas de cada um.
Esta página é para quem prepara arquivos para importar no TOPO, pela tela ou pela rota POST /api/v1/trial-balances/arquivo. Ela lista os formatos aceitos e as colunas de cada importação.
Formatos
- Todas as importações aceitam
.xlsx,.xlse.csv. - O balancete aceita também
.txt(separado por;,|, tabulação ou vírgula) e.xml. - A codificação pode ser UTF-8 ou Latin-1, e o negativo pode vir antes ou depois do número.
- O arquivo do balancete pode ter até 50 MB.
Quando o ERP usa outros nomes de coluna, o cliente configura o mapeamento de colunas na tela de importação do balancete. O mapeamento fica salvo para a empresa e vale também na API.
Nas planilhas de cadastro, as colunas são reconhecidas pelo nome do cabeçalho, em qualquer ordem. Colunas desconhecidas são ignoradas. Cada tela de importação tem o modelo para baixar e mostra a prévia com as recusas antes de gravar.
Colunas de cada importação
| Importação | Obrigatórias | Opcionais |
|---|---|---|
| Balancete | Conta, Descrição, Saldo anterior, Débito, Crédito, Saldo atual | Plano de Contas, Empresa, Competência |
| Plano de contas | Código da Conta, Nome, Tipo, Natureza, Classificação, Macro Conta | |
| Empresas | CNPJ, Razão Social, Regime Tributário e o endereço completo (para empresa nova) | Nome Fantasia, Tipo, Complemento, Moeda Padrão, Antecedência do alerta, Status, Módulos |
| Usuários | E-mail, Módulos, Papel, Nome (para usuário novo) | Empresas, Administrador do sistema |
| Checklists | Descrição, Departamento, Nível de Aprovação, Elaborador, prazo | Código, Empresa, Comentário, Setor, Evidência obrigatória, Revisor, Aprovador |
| Saldos de referência | Conta, Saldo | Empresa (CNPJ), Descrição |
| Notas explicativas | Código da nota, Título da nota | Ordem da nota, Código da linha, Descrição da linha, Ordem da linha, Contas (separadas por ;), Fórmula |
No balancete, o plano de contas usado é o indicado na coluna Plano de Contas. Uma empresa pode ter mais de um plano ativo.
Os papéis aceitos na planilha de usuários são Admin, Revisor, Elaborador, Aprovador e Auditor. A planilha de checklists vale para Gestão de Processos, Auditoria Externa, Obrigações Acessórias e CND.
Exemplo: balancete em CSV pela API
Este arquivo, com a competência no formulário, entrou pela API com status 201:
Conta;Descricao;Saldo Anterior;Debito;Credito;Saldo Final
1.1.01.001;Caixa Geral;1000,00;250,00;100,00;1150,00curl -s -X POST "$TOPO_API/api/v1/trial-balances/arquivo" \
-H "Authorization: Bearer $TOPO_CHAVE" \
-F "file=@balancete-2026-08.csv" \
-F "cnpj=12.345.678/0001-90" \
-F "period=2026-08"