{"openapi":"3.0.0","paths":{"/api/v1/trial-balances":{"post":{"description":"Envia o balancete de uma competência em JSON, direto do ERP, sem planilha. Informe a empresa por `companyId` ou por `cnpj`, a competência em `period` (AAAA-MM) e as linhas em `lineItems`, até 20.000 por chamada. A resposta diz quantas linhas vieram, quantas entraram e por que as outras ficaram de fora; avisos não impedem a importação. Escopo: `trial_balances:write`. Limite: 30 chamadas por minuto.\n\nO que acontece no TOPO: o balancete entra na competência da empresa com as mesmas validações da tela (plano de contas, natureza dos saldos, continuidade com o mês anterior) e fica pronto para o cliente liberar as conciliações. Reenviar o mesmo conteúdo não duplica nada: a resposta é 200 com `reenvio: true`. Conteúdo diferente na mesma competência cria uma versão nova.","operationId":"TrialBalanceV1Controller_importar","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportTrialBalanceV1Dto"},"example":{"companyId":12,"cnpj":"12.345.678/0001-90","period":"2026-09","chartName":"Plano de Contas Divisão Logística","lineItems":[{"accountCode":"1.1.01.001","accountName":"Caixa Geral","previousBalance":1000.5,"debit":250,"credit":100,"finalBalance":1150.5}]}}}},"responses":{"200":{"description":"Reenvio igual à versão vigente: nada foi gravado, e `trialBalanceId` é o da versão que já existe (`reenvio: true`). Pode tratar como sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespostaDeImportacaoV1Dto"},"example":{"success":true,"data":{"reenvio":false,"trialBalanceId":318,"enviadas":474,"importadas":207,"ignoradasForaDoPlano":3,"ignoradasQueNaoConciliam":264,"avisos":["Saldo anterior da conta 1.1.01 diferente do saldo final do mês anterior"]}}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"201":{"description":"Balancete importado. Veja as contagens e os avisos em `data`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespostaDeImportacaoV1Dto"},"example":{"success":true,"data":{"reenvio":false,"trialBalanceId":318,"enviadas":474,"importadas":207,"ignoradasForaDoPlano":3,"ignoradasQueNaoConciliam":264,"avisos":["Saldo anterior da conta 1.1.01 diferente do saldo final do mês anterior"]}}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"400":{"description":"A importação foi recusada. Causas comuns: `period` fora do formato AAAA-MM; faltou `companyId` ou `cnpj` (\"Informe companyId ou cnpj.\"); o CNPJ não é o da empresa do `companyId`; o plano de contas não foi encontrado. O corpo traz `success: false`, o motivo em `error` e `code: IMPORTACAO_RECUSADA`. Corrija e envie de novo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"period deve estar no formato AAAA-MM, por exemplo 2026-08."}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada. A resposta é sempre \"Chave de API inválida\", sem dizer o motivo. Confira se a chave vai no cabeçalho e se ela não foi trocada. Se perdeu a chave, peça outra ao suporte TOPO.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Chave de API inválida"}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"403":{"description":"A chave é válida, mas não pode fazer esta chamada. Ou falta o escopo da rota (a mensagem diz qual, por exemplo \"Escopo insuficiente: a chave não tem trial_balances:write\"), ou a empresa não contratou o módulo. Peça ao suporte TOPO uma chave com o escopo certo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Escopo insuficiente: a chave não tem trial_balances:write"}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"404":{"description":"Nenhuma empresa do cliente com aquele CNPJ ou `companyId` neste ambiente. Produção e staging têm cadastros separados.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Nenhuma empresa com o CNPJ 12.345.678/0001-90 está cadastrada neste ambiente."}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"409":{"description":"A competência está encerrada no TOPO, ou é a seguinte a uma encerrada, que a importação alteraria. Quem fecha e reabre competência é o cliente, na tela do TOPO.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"O período 08/2026 desta empresa está fechado (Bloqueado: Sim). Não é possível importar um novo balancete nem mudar o balancete desse período; a conciliação segue liberada. Para importar, um administrador do módulo precisa reabrir o período, com justificativa.","code":"COMPETENCE_CLOSED"}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"429":{"description":"Mais de 30 chamadas por minuto na mesma rota com a mesma chave. Espere um minuto e tente de novo. Numa rotina agendada, espace as chamadas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Muitas requisições em pouco tempo. Aguarde alguns segundos e tente de novo."}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}}},"summary":"Importar balancete","tags":["Balancetes"],"security":[{"bearer":[]},{"x-api-key":[]},{"basic":[]}]},"get":{"description":"Lista os balancetes importados, com competência, versão, status e quem importou. Filtre por `companyId` e por `period` (AAAA-MM, por exemplo 2026-08). Serve para conferir se o balancete que o ERP enviou chegou e foi liberado. Escopo: `trial_balances:read`.\n\nA resposta vem em páginas: `data` traz as linhas e `pagination` diz a página, o tamanho, o total de linhas e o total de páginas. O padrão é 50 linhas por página, e o máximo é 100 (`limit`). Para ler tudo, repita a chamada com `page=1`, `page=2` e assim por diante, até `pagination.pages`. Limite: 30 chamadas por minuto por rota.","operationId":"BiV1Controller_balancetes","parameters":[{"name":"page","required":false,"in":"query","description":"Página, a partir de 1.","schema":{"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Linhas por página, de 1 a 100. Padrão 50.","schema":{"example":100,"type":"number"}},{"name":"companyId","required":false,"in":"query","description":"Id da empresa no TOPO.","schema":{"example":12,"type":"number"}},{"name":"period","required":false,"in":"query","description":"Competência, no formato AAAA-MM.","schema":{"example":"2026-08","type":"string"}}],"responses":{"200":{"description":"Uma página de balancetes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginaDeBalancetesV1Dto"},"example":{"data":[{"id":318,"empresaId":12,"empresaNome":"Transportes Exemplo Ltda","competencia":"2026-08","versao":2,"status":"RELEASED","importadoEm":"2026-09-03T14:12:05.000Z","importadoPor":"Chave de API SAP balancete (a1B2c3D4e5F6g7H8)","linhas":474}],"pagination":{"page":1,"limit":50,"total":132,"pages":3}}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"400":{"description":"`period` fora do formato AAAA-MM (por exemplo 2026-08), ou página inválida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"period deve estar no formato AAAA-MM, por exemplo 2026-08."}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada. A resposta é sempre \"Chave de API inválida\", sem dizer o motivo. Confira se a chave vai no cabeçalho e se ela não foi trocada. Se perdeu a chave, peça outra ao suporte TOPO.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Chave de API inválida"}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"403":{"description":"Falta o escopo `trial_balances:read`, ou a empresa não contratou a conciliação.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Escopo insuficiente: a chave não tem trial_balances:read"}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"429":{"description":"Mais de 30 chamadas por minuto na mesma rota com a mesma chave. Espere um minuto e tente de novo. Numa rotina agendada, espace as chamadas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Muitas requisições em pouco tempo. Aguarde alguns segundos e tente de novo."}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}}},"summary":"Listar balancetes","tags":["Balancetes"],"security":[{"bearer":[]},{"x-api-key":[]},{"basic":[]}]}},"/api/v1/trial-balances/arquivo":{"post":{"description":"Envia o mesmo relatório que o usuário subiria na tela, no campo `file` de um formulário multipart, com `cnpj` ou `companyId`. Use quando o ERP já gera o arquivo e montar o JSON dá mais trabalho. Vale o mapeamento de colunas salvo para a empresa na tela de importação. Competência e plano de contas saem do arquivo quando não vêm no formulário. Escopo: `trial_balances:write`. Limite: 30 chamadas por minuto.\n\nO que acontece no TOPO: o balancete entra na competência da empresa com as mesmas validações da tela (plano de contas, natureza dos saldos, continuidade com o mês anterior) e fica pronto para o cliente liberar as conciliações. Reenviar o mesmo conteúdo não duplica nada: a resposta é 200 com `reenvio: true`. Conteúdo diferente na mesma competência cria uma versão nova.","operationId":"TrialBalanceV1Controller_importarArquivo","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"O relatório do balancete (CSV, TXT delimitado, XML, XLSX ou XLS), até 50 MB."},"companyId":{"type":"integer","description":"Id da empresa no TOPO.","example":12},"cnpj":{"type":"string","description":"CNPJ, com ou sem máscara. Alternativa ao `companyId`.","example":"12.345.678/0001-90"},"period":{"type":"string","description":"Competência AAAA-MM. Sem ela, vale a coluna Competência do arquivo.","example":"2026-08"},"chartName":{"type":"string","description":"Nome do plano de contas. Sem ele, vale a coluna Plano de Contas do arquivo.","example":"Plano de Contas Divisão Logística"}}}}}},"responses":{"200":{"description":"Reenvio igual à versão vigente: nada foi gravado, e `trialBalanceId` é o da versão que já existe (`reenvio: true`). Pode tratar como sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespostaDeImportacaoV1Dto"},"example":{"success":true,"data":{"reenvio":false,"trialBalanceId":318,"enviadas":474,"importadas":207,"ignoradasForaDoPlano":3,"ignoradasQueNaoConciliam":264,"avisos":["Saldo anterior da conta 1.1.01 diferente do saldo final do mês anterior"]}}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"201":{"description":"Balancete importado. Veja as contagens e os avisos em `data`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespostaDeImportacaoV1Dto"},"example":{"success":true,"data":{"reenvio":false,"trialBalanceId":318,"enviadas":474,"importadas":207,"ignoradasForaDoPlano":3,"ignoradasQueNaoConciliam":264,"avisos":["Saldo anterior da conta 1.1.01 diferente do saldo final do mês anterior"]}}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"400":{"description":"Arquivo ausente (\"Envie o arquivo do balancete no campo file.\"), ilegível, ou importação recusada. O corpo traz `success: false` e o motivo em `error`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"period deve estar no formato AAAA-MM, por exemplo 2026-08."}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada. A resposta é sempre \"Chave de API inválida\", sem dizer o motivo. Confira se a chave vai no cabeçalho e se ela não foi trocada. Se perdeu a chave, peça outra ao suporte TOPO.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Chave de API inválida"}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"403":{"description":"A chave é válida, mas não pode fazer esta chamada. Ou falta o escopo da rota (a mensagem diz qual, por exemplo \"Escopo insuficiente: a chave não tem trial_balances:write\"), ou a empresa não contratou o módulo. Peça ao suporte TOPO uma chave com o escopo certo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Escopo insuficiente: a chave não tem trial_balances:write"}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"404":{"description":"Nenhuma empresa do cliente com aquele CNPJ ou `companyId` neste ambiente. Produção e staging têm cadastros separados.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Nenhuma empresa com o CNPJ 12.345.678/0001-90 está cadastrada neste ambiente."}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"409":{"description":"A competência está encerrada no TOPO, ou é a seguinte a uma encerrada, que a importação alteraria. Quem fecha e reabre competência é o cliente, na tela do TOPO.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"O período 08/2026 desta empresa está fechado (Bloqueado: Sim). Não é possível importar um novo balancete nem mudar o balancete desse período; a conciliação segue liberada. Para importar, um administrador do módulo precisa reabrir o período, com justificativa.","code":"COMPETENCE_CLOSED"}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"429":{"description":"Mais de 30 chamadas por minuto na mesma rota com a mesma chave. Espere um minuto e tente de novo. Numa rotina agendada, espace as chamadas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Muitas requisições em pouco tempo. Aguarde alguns segundos e tente de novo."}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}}},"summary":"Importar balancete por arquivo","tags":["Balancetes"],"security":[{"bearer":[]},{"x-api-key":[]},{"basic":[]}]}},"/api/v1/companies":{"get":{"description":"Lista as empresas do cliente da chave, com razão social, CNPJ e regime tributário. Use no começo da integração para descobrir o `id` de cada empresa, que as outras rotas pedem em `companyId`. Só lê: nada muda no TOPO. Escopo: `companies:read`.\n\nA resposta vem em páginas: `data` traz as linhas e `pagination` diz a página, o tamanho, o total de linhas e o total de páginas. O padrão é 50 linhas por página, e o máximo é 100 (`limit`). Para ler tudo, repita a chamada com `page=1`, `page=2` e assim por diante, até `pagination.pages`. Limite: 30 chamadas por minuto por rota.","operationId":"BiV1Controller_empresas","parameters":[{"name":"page","required":false,"in":"query","description":"Página, a partir de 1.","schema":{"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Linhas por página, de 1 a 100. Padrão 50.","schema":{"example":100,"type":"number"}}],"responses":{"200":{"description":"Uma página de empresas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginaDeEmpresasV1Dto"},"example":{"data":[{"id":12,"razaoSocial":"Transportes Exemplo Ltda","nomeFantasia":"Exemplo Logística","cnpj":"12345678000190","regimeTributario":"REAL_PROFIT","status":"ACTIVE","empresaControladoraId":null}],"pagination":{"page":1,"limit":50,"total":132,"pages":3}}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"400":{"description":"Pedido inválido. Um campo faltou ou veio no formato errado (por exemplo, `period` fora do formato AAAA-MM), ou a importação foi recusada pelas validações do balancete. Corrija o que `error` diz e envie de novo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"period deve estar no formato AAAA-MM, por exemplo 2026-08."}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada. A resposta é sempre \"Chave de API inválida\", sem dizer o motivo. Confira se a chave vai no cabeçalho e se ela não foi trocada. Se perdeu a chave, peça outra ao suporte TOPO.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Chave de API inválida"}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"403":{"description":"A chave é válida, mas não pode fazer esta chamada. Ou falta o escopo da rota (a mensagem diz qual, por exemplo \"Escopo insuficiente: a chave não tem trial_balances:write\"), ou a empresa não contratou o módulo. Peça ao suporte TOPO uma chave com o escopo certo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Escopo insuficiente: a chave não tem companies:read"}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"429":{"description":"Mais de 30 chamadas por minuto na mesma rota com a mesma chave. Espere um minuto e tente de novo. Numa rotina agendada, espace as chamadas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Muitas requisições em pouco tempo. Aguarde alguns segundos e tente de novo."}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}}},"summary":"Listar empresas","tags":["Empresas"],"security":[{"bearer":[]},{"x-api-key":[]},{"basic":[]}]}},"/api/v1/chart-of-accounts":{"get":{"description":"Lista os planos de contas da empresa informada em `companyId` (obrigatório). Uma empresa pode ter mais de um plano ativo; o balancete diz qual usar. Use o `id` do plano para ler as contas em `/api/v1/chart-of-accounts/{id}/accounts`. Escopo: `chart_of_accounts:read`.\n\nA resposta vem em páginas: `data` traz as linhas e `pagination` diz a página, o tamanho, o total de linhas e o total de páginas. O padrão é 50 linhas por página, e o máximo é 100 (`limit`). Para ler tudo, repita a chamada com `page=1`, `page=2` e assim por diante, até `pagination.pages`. Limite: 30 chamadas por minuto por rota.","operationId":"BiV1Controller_planos","parameters":[{"name":"page","required":false,"in":"query","description":"Página, a partir de 1.","schema":{"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Linhas por página, de 1 a 100. Padrão 50.","schema":{"example":100,"type":"number"}},{"name":"companyId","required":true,"in":"query","description":"Id da empresa no TOPO.","schema":{"example":12,"type":"number"}}],"responses":{"200":{"description":"Uma página de planos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginaDePlanosV1Dto"},"example":{"data":[{"id":4,"empresaId":12,"nome":"Plano de Contas Divisão Logística","vigenciaInicio":"2026-01-01","vigenciaFim":null,"ativo":true,"versao":1}],"pagination":{"page":1,"limit":50,"total":132,"pages":3}}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"400":{"description":"Faltou `companyId`, ou ele não é um número inteiro.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"period deve estar no formato AAAA-MM, por exemplo 2026-08."}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada. A resposta é sempre \"Chave de API inválida\", sem dizer o motivo. Confira se a chave vai no cabeçalho e se ela não foi trocada. Se perdeu a chave, peça outra ao suporte TOPO.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Chave de API inválida"}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"403":{"description":"A chave é válida, mas não pode fazer esta chamada. Ou falta o escopo da rota (a mensagem diz qual, por exemplo \"Escopo insuficiente: a chave não tem trial_balances:write\"), ou a empresa não contratou o módulo. Peça ao suporte TOPO uma chave com o escopo certo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Escopo insuficiente: a chave não tem chart_of_accounts:read"}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"429":{"description":"Mais de 30 chamadas por minuto na mesma rota com a mesma chave. Espere um minuto e tente de novo. Numa rotina agendada, espace as chamadas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Muitas requisições em pouco tempo. Aguarde alguns segundos e tente de novo."}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}}},"summary":"Listar planos de contas de uma empresa","tags":["Planos de contas"],"security":[{"bearer":[]},{"x-api-key":[]},{"basic":[]}]}},"/api/v1/chart-of-accounts/{id}/accounts":{"get":{"description":"Lista as contas do plano `id`, com código, código reduzido, natureza e se a conta entra na conciliação. Filtre por empresa com `companyId`. Útil para montar o de-para entre o plano do ERP e o do TOPO antes de enviar o balancete. Escopo: `chart_of_accounts:read`.\n\nA resposta vem em páginas: `data` traz as linhas e `pagination` diz a página, o tamanho, o total de linhas e o total de páginas. O padrão é 50 linhas por página, e o máximo é 100 (`limit`). Para ler tudo, repita a chamada com `page=1`, `page=2` e assim por diante, até `pagination.pages`. Limite: 30 chamadas por minuto por rota.","operationId":"BiV1Controller_contas","parameters":[{"name":"id","required":true,"in":"path","description":"Id do plano de contas, o `id` que `GET /api/v1/chart-of-accounts` devolve.","schema":{"example":58,"type":"number"}},{"name":"page","required":false,"in":"query","description":"Página, a partir de 1.","schema":{"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Linhas por página, de 1 a 100. Padrão 50.","schema":{"example":100,"type":"number"}},{"name":"companyId","required":false,"in":"query","description":"Id da empresa no TOPO.","schema":{"example":12,"type":"number"}}],"responses":{"200":{"description":"Uma página de contas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginaDeContasV1Dto"},"example":{"data":[{"id":881,"planoId":4,"empresaId":12,"codigo":"1.1.01.001","codigoReduzido":"1001","descricao":"Caixa Geral","tipo":"ANALYTICAL","natureza":"DEBIT","classificacao":"Ativo Circulante","departamento":"Financeiro","setor":"Tesouraria","exigeConciliacao":true}],"pagination":{"page":1,"limit":50,"total":132,"pages":3}}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"400":{"description":"Pedido inválido. Um campo faltou ou veio no formato errado (por exemplo, `period` fora do formato AAAA-MM), ou a importação foi recusada pelas validações do balancete. Corrija o que `error` diz e envie de novo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"period deve estar no formato AAAA-MM, por exemplo 2026-08."}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada. A resposta é sempre \"Chave de API inválida\", sem dizer o motivo. Confira se a chave vai no cabeçalho e se ela não foi trocada. Se perdeu a chave, peça outra ao suporte TOPO.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Chave de API inválida"}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"403":{"description":"A chave é válida, mas não pode fazer esta chamada. Ou falta o escopo da rota (a mensagem diz qual, por exemplo \"Escopo insuficiente: a chave não tem trial_balances:write\"), ou a empresa não contratou o módulo. Peça ao suporte TOPO uma chave com o escopo certo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Escopo insuficiente: a chave não tem chart_of_accounts:read"}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"429":{"description":"Mais de 30 chamadas por minuto na mesma rota com a mesma chave. Espere um minuto e tente de novo. Numa rotina agendada, espace as chamadas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Muitas requisições em pouco tempo. Aguarde alguns segundos e tente de novo."}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}}},"summary":"Listar contas de um plano","tags":["Planos de contas"],"security":[{"bearer":[]},{"x-api-key":[]},{"basic":[]}]}},"/api/v1/trial-balances/{id}/lines":{"get":{"description":"Devolve as linhas do balancete `id`: conta, saldo anterior, débito, crédito e saldo final. Pegue o `id` na lista de balancetes. É a rota que o Power BI usa para montar a tabela de saldos. Escopo: `trial_balances:read`.\n\nA resposta vem em páginas: `data` traz as linhas e `pagination` diz a página, o tamanho, o total de linhas e o total de páginas. O padrão é 50 linhas por página, e o máximo é 100 (`limit`). Para ler tudo, repita a chamada com `page=1`, `page=2` e assim por diante, até `pagination.pages`. Limite: 30 chamadas por minuto por rota.","operationId":"BiV1Controller_linhas","parameters":[{"name":"id","required":true,"in":"path","description":"Id do balancete, o `id` que `GET /api/v1/trial-balances` devolve.","schema":{"example":65,"type":"number"}},{"name":"page","required":false,"in":"query","description":"Página, a partir de 1.","schema":{"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Linhas por página, de 1 a 100. Padrão 50.","schema":{"example":100,"type":"number"}}],"responses":{"200":{"description":"Uma página de linhas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginaDeLinhasV1Dto"},"example":{"data":[{"balanceteId":318,"empresaId":12,"competencia":"2026-08","contaCodigo":"1.1.01.001","contaDescricao":"Caixa Geral","saldoAnterior":1000.5,"debito":250,"credito":100,"saldoFinal":1150.5}],"pagination":{"page":1,"limit":50,"total":132,"pages":3}}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"400":{"description":"Pedido inválido. Um campo faltou ou veio no formato errado (por exemplo, `period` fora do formato AAAA-MM), ou a importação foi recusada pelas validações do balancete. Corrija o que `error` diz e envie de novo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"period deve estar no formato AAAA-MM, por exemplo 2026-08."}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada. A resposta é sempre \"Chave de API inválida\", sem dizer o motivo. Confira se a chave vai no cabeçalho e se ela não foi trocada. Se perdeu a chave, peça outra ao suporte TOPO.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Chave de API inválida"}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"403":{"description":"A chave é válida, mas não pode fazer esta chamada. Ou falta o escopo da rota (a mensagem diz qual, por exemplo \"Escopo insuficiente: a chave não tem trial_balances:write\"), ou a empresa não contratou o módulo. Peça ao suporte TOPO uma chave com o escopo certo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Escopo insuficiente: a chave não tem trial_balances:read"}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"429":{"description":"Mais de 30 chamadas por minuto na mesma rota com a mesma chave. Espere um minuto e tente de novo. Numa rotina agendada, espace as chamadas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Muitas requisições em pouco tempo. Aguarde alguns segundos e tente de novo."}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}}},"summary":"Linhas de um balancete","tags":["Balancetes"],"security":[{"bearer":[]},{"x-api-key":[]},{"basic":[]}]}},"/api/v1/reconciliations":{"get":{"description":"Lista as conciliações com status, responsável atual, prazo, situação do prazo (SLA) e os saldos contábil, conciliado e a diferença. Filtre por `companyId` e `period`. O responsável é o mesmo nome da coluna Responsável da tela. Escopo: `reconciliations:read`.\n\nA resposta vem em páginas: `data` traz as linhas e `pagination` diz a página, o tamanho, o total de linhas e o total de páginas. O padrão é 50 linhas por página, e o máximo é 100 (`limit`). Para ler tudo, repita a chamada com `page=1`, `page=2` e assim por diante, até `pagination.pages`. Limite: 30 chamadas por minuto por rota.","operationId":"BiV1Controller_conciliacoes","parameters":[{"name":"page","required":false,"in":"query","description":"Página, a partir de 1.","schema":{"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Linhas por página, de 1 a 100. Padrão 50.","schema":{"example":100,"type":"number"}},{"name":"companyId","required":false,"in":"query","description":"Id da empresa no TOPO.","schema":{"example":12,"type":"number"}},{"name":"period","required":false,"in":"query","description":"Competência, no formato AAAA-MM.","schema":{"example":"2026-08","type":"string"}}],"responses":{"200":{"description":"Uma página de conciliações.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginaDeConciliacoesV1Dto"},"example":{"data":[{"id":5120,"empresaId":12,"empresaNome":"Transportes Exemplo Ltda","competencia":"2026-08","contaId":881,"contaCodigo":"1.1.01.001","contaDescricao":"Caixa Geral","status":"IN_ELABORATION","responsavelNome":"Mariana Souza","responsavelPapel":"Elaborador","prazo":"2026-09-05T00:00:00.000Z","slaStatus":"ON_TIME","saldoContabil":1150.5,"saldoConciliado":1150.5,"diferenca":0,"ajustes":0}],"pagination":{"page":1,"limit":50,"total":132,"pages":3}}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"400":{"description":"Pedido inválido. Um campo faltou ou veio no formato errado (por exemplo, `period` fora do formato AAAA-MM), ou a importação foi recusada pelas validações do balancete. Corrija o que `error` diz e envie de novo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"period deve estar no formato AAAA-MM, por exemplo 2026-08."}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada. A resposta é sempre \"Chave de API inválida\", sem dizer o motivo. Confira se a chave vai no cabeçalho e se ela não foi trocada. Se perdeu a chave, peça outra ao suporte TOPO.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Chave de API inválida"}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"403":{"description":"A chave é válida, mas não pode fazer esta chamada. Ou falta o escopo da rota (a mensagem diz qual, por exemplo \"Escopo insuficiente: a chave não tem trial_balances:write\"), ou a empresa não contratou o módulo. Peça ao suporte TOPO uma chave com o escopo certo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Escopo insuficiente: a chave não tem reconciliations:read"}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"429":{"description":"Mais de 30 chamadas por minuto na mesma rota com a mesma chave. Espere um minuto e tente de novo. Numa rotina agendada, espace as chamadas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Muitas requisições em pouco tempo. Aguarde alguns segundos e tente de novo."}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}}},"summary":"Listar conciliações","tags":["Conciliações"],"security":[{"bearer":[]},{"x-api-key":[]},{"basic":[]}]}},"/api/v1/graphql":{"post":{"description":"Os mesmos dados da leitura REST numa chamada só: `empresas`, `planosDeContas`, `contas`, `balancetes`, `linhasDoBalancete` e `conciliacoes`, com os mesmos filtros e a mesma paginação. Envie um JSON com `query` e, se houver, `variables`, com o cabeçalho `Content-Type: application/json`. Não existe mutation: nada muda no TOPO.\n\nOs erros seguem o formato GraphQL: a resposta traz `errors`, cada um com `message` em português e `extensions.code`. Códigos comuns: `SO_LEITURA` (mandou mutation), `PROFUNDIDADE_EXCEDIDA` e `COMPLEXIDADE_EXCEDIDA` (consulta grande demais: peça menos campos ou páginas menores) e `CONTENT_TYPE_INVALIDO` (status 415). Escopo: `analytics:read`. Limite: 30 chamadas por minuto.","operationId":"GraphqlV1Controller_consultar","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"A consulta GraphQL."},"variables":{"type":"object","description":"Os valores das variáveis da consulta."},"operationName":{"type":"string","description":"Qual operação rodar, quando `query` tem mais de uma."}},"example":{"query":"query Saldos($empresa: Int!, $competencia: String!) {\n  balancetes(companyId: $empresa, period: $competencia) {\n    data { id competencia status linhas }\n  }\n}","variables":{"empresa":12,"competencia":"2026-08"}}},"example":{"query":"query Saldos($empresa: Int!, $competencia: String!) {\n  balancetes(companyId: $empresa, period: $competencia) {\n    data { id competencia status linhas }\n  }\n}","variables":{"empresa":12,"competencia":"2026-08"}}}}},"responses":{"200":{"description":"O resultado em `data`. Se parte da consulta falhou, `data` vem com o que deu certo e `errors` explica o resto.","headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"400":{"description":"Consulta inválida: sintaxe, campo que não existe, mutation, ou limite de profundidade ou custo. Veja `errors[].message` e `errors[].extensions.code`.","headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada. A resposta é sempre \"Chave de API inválida\", sem dizer o motivo. Confira se a chave vai no cabeçalho e se ela não foi trocada. Se perdeu a chave, peça outra ao suporte TOPO.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroV1Dto"},"example":{"success":false,"error":"Chave de API inválida"}}},"headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"403":{"description":"A chave é válida, mas não pode fazer esta chamada. Ou falta o escopo da rota (a mensagem diz qual, por exemplo \"Escopo insuficiente: a chave não tem trial_balances:write\"), ou a empresa não contratou o módulo. Peça ao suporte TOPO uma chave com o escopo certo.","headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"415":{"description":"Faltou o cabeçalho `Content-Type: application/json`. O código em `errors[].extensions.code` é `CONTENT_TYPE_INVALIDO`.","headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}},"429":{"description":"Mais de 30 chamadas por minuto na mesma rota com a mesma chave. Espere um minuto e tente de novo. Numa rotina agendada, espace as chamadas.","headers":{"X-Request-Id":{"description":"Id desta requisição. Guarde no log da integração e mande ao suporte TOPO quando abrir um chamado sobre esta chamada.","schema":{"type":"string"}}}}},"summary":"Consulta GraphQL (só leitura)","tags":["GraphQL"],"security":[{"bearer":[]},{"x-api-key":[]},{"basic":[]}]}}},"info":{"title":"API pública do TOPO","description":"API de integração do TOPO. A credencial é uma CHAVE DE API, enviada só no cabeçalho, de um destes jeitos: `Authorization: Bearer <chave>`, `X-API-Key: <chave>` ou `Authorization: Basic` com a chave na senha (ou no usuário, com senha vazia). Na query string ela é recusada.\n\nCada chave carrega ESCOPOS, e a rota exige os seus. Escopo insuficiente responde 403 dizendo qual falta. Chave ausente, inválida ou revogada responde sempre o mesmo 401. Além do escopo, valem as regras da tela: a chave só alcança empresas do próprio cliente e só os módulos que a empresa contratou.\n\nA chave é gerada pela equipe TOPO: peça ao suporte TOPO, dizendo qual sistema vai usá-la e o que ele precisa ler ou enviar. O segredo aparece uma vez só; o TOPO guarda apenas o hash SHA-256 dele. Mensagens de erro e avisos saem em português. O guia completo, com exemplos, está na seção Desenvolvedores da central de documentação.","version":"1","contact":{}},"tags":[{"name":"Empresas","description":"As empresas do cliente que a chave alcança."},{"name":"Planos de contas","description":"Os planos de contas de cada empresa e as contas deles."},{"name":"Balancetes","description":"Enviar o balancete do ERP e ler os balancetes importados."},{"name":"Conciliações","description":"Status, responsável, prazo e saldos de cada conciliação."},{"name":"GraphQL","description":"Os mesmos dados de leitura, numa consulta só."}],"servers":[{"url":"https://api.topocontabil.com.br","description":"Produção"}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Authorization: Bearer <chave>"},"x-api-key":{"type":"apiKey","in":"header","name":"X-API-Key","description":"X-API-Key: <chave>"},"basic":{"type":"http","scheme":"basic","description":"Usuário `topo` e senha igual à chave (ou a chave no usuário, com senha vazia)."}},"schemas":{"TrialBalanceLineV1Dto":{"type":"object","properties":{"accountCode":{"type":"string","description":"Código da conta, igual ao do plano de contas no TOPO. Conta que não existe no plano é ignorada e contada em `ignoradasForaDoPlano`.","example":"1.1.01.001"},"accountName":{"type":"string","description":"Nome da conta","example":"Caixa Geral"},"previousBalance":{"type":"number","description":"Saldo no fim da competência anterior.","example":1000.5},"debit":{"type":"number","description":"Soma dos débitos da competência.","example":250},"credit":{"type":"number","description":"Soma dos créditos da competência.","example":100},"finalBalance":{"type":"number","description":"Saldo no fim da competência.","example":1150.5}},"required":["accountCode","accountName","previousBalance","debit","credit","finalBalance"]},"ImportTrialBalanceV1Dto":{"type":"object","properties":{"companyId":{"type":"integer","description":"Id da empresa no TOPO. Informe este campo ou `cnpj`. Com os dois, vale o id, e o CNPJ tem de ser o dessa empresa (senão a importação é recusada, como na tela).","example":12},"cnpj":{"type":"string","description":"CNPJ da empresa, com ou sem máscara. Alternativa ao `companyId` para quem integra pelo ERP e não conhece o id interno do TOPO.","example":"12.345.678/0001-90"},"period":{"type":"string","description":"Competência do balancete, no formato AAAA-MM. Agosto de 2026 é `2026-08`.","example":"2026-09"},"chartName":{"type":"string","description":"Nome do plano de contas a usar, igual ao cadastrado no TOPO. Uma empresa pode ter mais de um plano vigente. Nome que não bate com nenhum plano ativo da empresa recusa a importação.","example":"Plano de Contas Divisão Logística"},"lineItems":{"description":"As linhas do balancete, uma por conta. De 1 a 20.000 linhas por chamada.","maxItems":20000,"type":"array","items":{"$ref":"#/components/schemas/TrialBalanceLineV1Dto"}}},"required":["period","lineItems"]},"DadosDaImportacaoV1Dto":{"type":"object","properties":{"reenvio":{"type":"boolean","description":"Verdadeiro quando o conteúdo é igual ao da versão vigente: nada foi gravado, o status é 200 e o id é o da versão que já existe","example":false},"trialBalanceId":{"type":"integer","description":"Id do balancete criado ou atualizado no TOPO","example":318},"enviadas":{"type":"integer","description":"Quantas linhas vieram na chamada (corpo ou arquivo)","example":474},"importadas":{"type":"integer","description":"Quantas linhas entraram no balancete. Pode ser menor que \"enviadas\"","example":207},"ignoradasForaDoPlano":{"type":"integer","description":"Linhas ignoradas porque a conta não existe no plano de contas da empresa","example":3},"ignoradasQueNaoConciliam":{"type":"integer","description":"Linhas ignoradas porque a conta não é conciliável no plano de contas","example":264},"avisos":{"description":"Avisos da validação. Aviso não impede a importação","example":["Saldo anterior da conta 1.1.01 diferente do saldo final do mês anterior"],"type":"array","items":{"type":"string"}}},"required":["reenvio","enviadas","importadas","ignoradasForaDoPlano","ignoradasQueNaoConciliam","avisos"]},"RespostaDeImportacaoV1Dto":{"type":"object","properties":{"success":{"type":"boolean","description":"Sempre verdadeiro na resposta 2xx. A recusa sai com status 400, \"success\" falso e o motivo em \"error\"","example":true},"data":{"description":"Números da importação. As contagens vêm só na importação que gravou","allOf":[{"$ref":"#/components/schemas/DadosDaImportacaoV1Dto"}]}},"required":["success","data"]},"ErroV1Dto":{"type":"object","properties":{"success":{"type":"boolean","description":"Sempre falso numa resposta de erro.","example":false},"error":{"type":"string","description":"O motivo, em português, para mostrar a quem opera a integração. Não dependa do texto exato: use o status HTTP e o `code`.","example":"Nenhuma empresa com o CNPJ 12.345.678/0001-90 está cadastrada neste ambiente."},"code":{"type":"string","description":"Código estável da recusa, quando existe. `IMPORTACAO_RECUSADA` no 400 da importação; `COMPETENCE_CLOSED` ou `NEXT_COMPETENCE_CLOSED` no 409. 401, 403, 404 e 429 ainda saem sem código.","example":"IMPORTACAO_RECUSADA"}},"required":["success","error"]},"EmpresaBiV1Dto":{"type":"object","properties":{"id":{"type":"number","description":"Id da empresa no TOPO.","example":12},"razaoSocial":{"type":"string","example":"Transportes Exemplo Ltda"},"nomeFantasia":{"type":"string","nullable":true,"example":"Exemplo Logística"},"cnpj":{"type":"string","description":"Só os 14 dígitos.","example":"12345678000190"},"regimeTributario":{"type":"string","description":"SIMPLES_NACIONAL, PRESUMED_PROFIT ou REAL_PROFIT.","nullable":true,"example":"REAL_PROFIT"},"status":{"type":"string","description":"ACTIVE ou INACTIVE.","example":"ACTIVE"},"empresaControladoraId":{"type":"number","description":"Id da controladora, quando a empresa é de um grupo.","nullable":true,"example":null}},"required":["id","razaoSocial","cnpj","status"]},"PaginacaoV1Dto":{"type":"object","properties":{"page":{"type":"number","description":"Página devolvida, a partir de 1.","example":1},"limit":{"type":"number","description":"Linhas por página pedidas.","example":50},"total":{"type":"number","description":"Total de linhas do filtro.","example":132},"pages":{"type":"number","description":"Total de páginas. Para ler tudo, peça `page` de 1 até este número.","example":3}},"required":["page","limit","total","pages"]},"PaginaDeEmpresasV1Dto":{"type":"object","properties":{"data":{"description":"As linhas desta página.","type":"array","items":{"$ref":"#/components/schemas/EmpresaBiV1Dto"}},"pagination":{"description":"Onde esta página está no total.","allOf":[{"$ref":"#/components/schemas/PaginacaoV1Dto"}]}},"required":["data","pagination"]},"PlanoDeContasBiV1Dto":{"type":"object","properties":{"id":{"type":"number","example":4},"empresaId":{"type":"number","nullable":true,"example":12},"nome":{"type":"string","example":"Plano de Contas Divisão Logística"},"vigenciaInicio":{"type":"string","description":"Data AAAA-MM-DD.","example":"2026-01-01"},"vigenciaFim":{"type":"string","nullable":true,"example":null},"ativo":{"type":"boolean","example":true},"versao":{"type":"number","example":1}},"required":["id","nome","vigenciaInicio","ativo","versao"]},"PaginaDePlanosV1Dto":{"type":"object","properties":{"data":{"description":"As linhas desta página.","type":"array","items":{"$ref":"#/components/schemas/PlanoDeContasBiV1Dto"}},"pagination":{"description":"Onde esta página está no total.","allOf":[{"$ref":"#/components/schemas/PaginacaoV1Dto"}]}},"required":["data","pagination"]},"ContaBiV1Dto":{"type":"object","properties":{"id":{"type":"number","example":881},"planoId":{"type":"number","example":4},"empresaId":{"type":"number","example":12},"codigo":{"type":"string","example":"1.1.01.001"},"codigoReduzido":{"type":"string","example":"1001"},"descricao":{"type":"string","example":"Caixa Geral"},"tipo":{"type":"string","description":"SYNTHETIC (sintética) ou ANALYTICAL (analítica).","example":"ANALYTICAL"},"natureza":{"type":"string","description":"DEBIT (devedora) ou CREDIT (credora).","example":"DEBIT"},"classificacao":{"type":"string","description":"Classificação contábil, texto do cadastro.","example":"Ativo Circulante"},"departamento":{"type":"string","nullable":true,"example":"Financeiro"},"setor":{"type":"string","nullable":true,"example":"Tesouraria"},"exigeConciliacao":{"type":"boolean","description":"Verdadeiro quando a conta entra na conciliação.","example":true}},"required":["id","planoId","empresaId","codigo","codigoReduzido","descricao","tipo","natureza","classificacao","exigeConciliacao"]},"PaginaDeContasV1Dto":{"type":"object","properties":{"data":{"description":"As linhas desta página.","type":"array","items":{"$ref":"#/components/schemas/ContaBiV1Dto"}},"pagination":{"description":"Onde esta página está no total.","allOf":[{"$ref":"#/components/schemas/PaginacaoV1Dto"}]}},"required":["data","pagination"]},"BalanceteBiV1Dto":{"type":"object","properties":{"id":{"type":"number","description":"Id do balancete no TOPO.","example":318},"empresaId":{"type":"number","example":12},"empresaNome":{"type":"string","nullable":true,"example":"Transportes Exemplo Ltda"},"competencia":{"type":"string","description":"AAAA-MM.","example":"2026-08"},"versao":{"type":"number","description":"Cada reimportação da competência cria uma versão nova.","example":2},"status":{"type":"string","description":"DRAFT, VALIDATED, RELEASED (liberado) ou CANCELLED.","example":"RELEASED"},"importadoEm":{"type":"string","description":"Data e hora ISO 8601.","example":"2026-09-03T14:12:05.000Z"},"importadoPor":{"type":"string","description":"Quem importou. Pela API, o nome da chave: \"Chave de API <nome> (<prefixo>)\".","nullable":true,"example":"Chave de API SAP balancete (a1B2c3D4e5F6g7H8)"},"linhas":{"type":"number","description":"Quantidade de linhas.","example":474}},"required":["id","empresaId","competencia","versao","status","importadoEm","linhas"]},"PaginaDeBalancetesV1Dto":{"type":"object","properties":{"data":{"description":"As linhas desta página.","type":"array","items":{"$ref":"#/components/schemas/BalanceteBiV1Dto"}},"pagination":{"description":"Onde esta página está no total.","allOf":[{"$ref":"#/components/schemas/PaginacaoV1Dto"}]}},"required":["data","pagination"]},"LinhaDeBalanceteBiV1Dto":{"type":"object","properties":{"balanceteId":{"type":"number","example":318},"empresaId":{"type":"number","example":12},"competencia":{"type":"string","example":"2026-08"},"contaCodigo":{"type":"string","example":"1.1.01.001"},"contaDescricao":{"type":"string","example":"Caixa Geral"},"saldoAnterior":{"type":"number","example":1000.5},"debito":{"type":"number","example":250},"credito":{"type":"number","example":100},"saldoFinal":{"type":"number","example":1150.5}},"required":["balanceteId","empresaId","competencia","contaCodigo","contaDescricao","saldoAnterior","debito","credito","saldoFinal"]},"PaginaDeLinhasV1Dto":{"type":"object","properties":{"data":{"description":"As linhas desta página.","type":"array","items":{"$ref":"#/components/schemas/LinhaDeBalanceteBiV1Dto"}},"pagination":{"description":"Onde esta página está no total.","allOf":[{"$ref":"#/components/schemas/PaginacaoV1Dto"}]}},"required":["data","pagination"]},"ConciliacaoBiV1Dto":{"type":"object","properties":{"id":{"type":"number","example":5120},"empresaId":{"type":"number","example":12},"empresaNome":{"type":"string","nullable":true,"example":"Transportes Exemplo Ltda"},"competencia":{"type":"string","example":"2026-08"},"contaId":{"type":"number","example":881},"contaCodigo":{"type":"string","nullable":true,"example":"1.1.01.001"},"contaDescricao":{"type":"string","nullable":true,"example":"Caixa Geral"},"status":{"type":"string","description":"Estado da conciliação no fluxo. IN_ELABORATION: com o elaborador. AWAITING_* e IN_*_REVIEW/SUPERVISION: na revisão da área, na supervisão ou na revisão contábil. AWAITING_FINAL_APPROVAL: com o aprovador. REJECTED_BY_*: devolvida ao elaborador. APPROVED: concluída. REOPENED: reaberta. CANCELLED: o balancete foi cancelado.","enum":["DRAFT","APPROVED","CANCELLED","IN_ELABORATION","AWAITING_ACCOUNTING_REVIEW","IN_ACCOUNTING_REVIEW","AWAITING_FINAL_APPROVAL","REJECTED_BY_ACCOUNTING_REVIEWER","REJECTED_BY_FINAL_APPROVER","REOPENED","AWAITING_AREA_REVIEW","IN_AREA_REVIEW","REJECTED_BY_AREA_REVIEWER","AWAITING_AREA_SUPERVISION","IN_AREA_SUPERVISION","REJECTED_BY_AREA_SUPERVISOR"],"example":"IN_ELABORATION"},"responsavelNome":{"type":"string","description":"O nome que aparece na coluna Responsável da tela.","nullable":true,"example":"Mariana Souza"},"responsavelPapel":{"type":"string","description":"Papel de quem responde agora: Elaborador, Revisor, Aprovador etc. Na conciliação aprovada, Concluído.","example":"Elaborador"},"prazo":{"type":"string","description":"Prazo da etapa atual, data e hora ISO 8601.","example":"2026-09-05T00:00:00.000Z"},"slaStatus":{"type":"string","description":"Situação do prazo: ON_TIME (no prazo), APPROACHING_DEADLINE (vencendo), OVERDUE (vencido), COMPLETED_ON_TIME (concluída no prazo) ou COMPLETED_LATE (concluída com atraso).","enum":["ON_TIME","APPROACHING_DEADLINE","OVERDUE","COMPLETED_ON_TIME","COMPLETED_LATE"],"example":"ON_TIME"},"saldoContabil":{"type":"number","description":"Saldo da conta no balancete.","example":1150.5},"saldoConciliado":{"type":"number","description":"Saldo comprovado na conciliação.","example":1150.5},"diferenca":{"type":"number","description":"Saldo contábil menos o conciliado.","example":0},"ajustes":{"type":"number","description":"Soma dos ajustes lançados.","example":0}},"required":["id","empresaId","competencia","contaId","status","responsavelPapel","prazo","slaStatus","saldoContabil","saldoConciliado","diferenca","ajustes"]},"PaginaDeConciliacoesV1Dto":{"type":"object","properties":{"data":{"description":"As linhas desta página.","type":"array","items":{"$ref":"#/components/schemas/ConciliacaoBiV1Dto"}},"pagination":{"description":"Onde esta página está no total.","allOf":[{"$ref":"#/components/schemas/PaginacaoV1Dto"}]}},"required":["data","pagination"]}}}}