Balancete Domínio

Endpoints da WebApiAlcance para os balancetes contábeis importados do sistema Domínio. A criação ocorre por upload de PDF (layout Domínio) - o arquivo é parseado, o CNPJ extraído resolve o cliente e o balancete é persistido (cabeçalho + linhas). Os demais endpoints cobrem a listagem do histórico por cliente, a agregação de status de conferência por período e o detalhamento completo de um balancete.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key.

Base path

/api/v1/balancetes-dominio

Escopos necessários

  • balancetes_dominio:read - listagem, status por período, resumo de validações, validações, download do PDF e detalhamento
  • balancetes_dominio:write - upload de PDF, reprocessamento (individual e em lote) e exclusão

O escopo é derivado da rota: o prefixo /balancetes-dominio vira o recurso balancetes_dominio (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/DELETE).

Endpoints

POST /balancetes-dominio/upload

Recebe o PDF do Balancete Contábil (layout Domínio), extrai o CNPJ para resolver o cliente e persiste o balancete (cabeçalho + linhas). O tamanho é validado antes da leitura do corpo, como defesa contra excesso de memória.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
arquivoUploadFileformsimPDF do Balancete Contábil (layout Domínio).

Request

Requisição multipart/form-data (não é JSON). Envie um único campo de formulário arquivo com o PDF do Balancete Contábil.

Content-Type: multipart/form-data; boundary=----WebApiAlcance
 
------WebApiAlcance
Content-Disposition: form-data; name="arquivo"; filename="balancete_janeiro.pdf"
Content-Type: application/pdf
 
<conteúdo binário do PDF>
------WebApiAlcance--

Response 201 Created

{
  "status": "success",
  "message": "Balancete importado com sucesso",
  "data": {
    "id": 42,
    "id_usuario_created": 7,
    "id_cliente": 1234,
    "periodo_inicio": "2026-01-01",
    "periodo_fim": "2026-01-31",
    "data_emissao": "2026-02-05",
    "razao_social": "ACME SERVICOS LTDA",
    "cnpj": "12345678000199",
    "nome_arquivo_original": "balancete_janeiro.pdf",
    "tamanho_bytes": 84213,
    "hash_arquivo": "9f2c...",
    "data_hora_criacao": "2026-02-05T10:22:00-03:00",
    "linhas": [
      {
        "id": 1,
        "id_balancete": 42,
        "codigo_interno": "1",
        "classificacao": "1",
        "descricao": "ATIVO",
        "saldo_anterior": "0.00",
        "saldo_anterior_natureza": "D",
        "debito": "10000.00",
        "credito": "2000.00",
        "saldo_atual": "8000.00",
        "saldo_atual_natureza": "D",
        "nivel": 1,
        "ordem": 1
      }
    ]
  }
}

PDF inválido / não parseável retorna 400 Bad Request (ValueError); arquivo duplicado para o mesmo cliente retorna 409 Conflict (BalanceteDuplicadoError); arquivo acima do tamanho máximo permitido retorna 413 Request Entity Too Large; CNPJ do PDF sem cliente correspondente retorna 422 Unprocessable Entity (ClienteNaoEncontradoError).

Escopo: balancetes_dominio:write

GET /balancetes-dominio/

Lista o histórico de balancetes (visão compartilhada do escritório). Aceita filtro opcional por cliente e paginação. Lista vazia é estado válido - retorna 200 OK com data: [] e a mensagem "Nenhum balancete encontrado.".

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
id_clienteintquerynãoID do cliente.
limitintquerynãoPadrão 50. Faixa 1..500.
offsetintquerynãoPadrão 0. Mínimo 0.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Balancetes recuperados com sucesso",
  "data": [
    {
      "id": 42,
      "id_cliente": 1234,
      "periodo_inicio": "2026-01-01",
      "periodo_fim": "2026-01-31",
      "razao_social": "ACME SERVICOS LTDA",
      "cnpj": "12345678000199",
      "nome_arquivo_original": "balancete_janeiro.pdf",
      "tamanho_bytes": 84213,
      "data_hora_criacao": "2026-02-05T10:22:00-03:00"
    }
  ]
}

Escopo: balancetes_dominio:read

GET /balancetes-dominio/status

Agrega o status real de conferência de cada cliente (com plano de contas) para o período: movimento, conferência, presença de balancete da Domínio e divergências. Agregação org-wide (visão compartilhada do escritório) que alimenta a página Análise.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
periodo_iniciodatequerysimInício do período (YYYY-MM-DD).
periodo_fimdatequerysimFim do período (YYYY-MM-DD).
id_clienteintquerynãoRestringe a um cliente (> 0).

Valida periodo_inicio <= periodo_fim; caso contrário retorna 422 com detail: "A data de inicio nao pode ser posterior a data de fim.".

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Status de balancete recuperado com sucesso",
  "data": [
    {
      "id_cliente": 1234,
      "razao_social": "ACME SERVICOS LTDA",
      "cpfecnpj": "12345678000199",
      "tem_movimento": true,
      "tem_dominio": true,
      "dominio_data_import": "2026-02-05",
      "conferido": true,
      "divergencias": 0,
      "status": "ok"
    }
  ]
}

Escopo: balancetes_dominio:read

GET /balancetes-dominio/resumo-validacoes

Resumo de validações por balancete: roda as regras de análise em lote e devolve só os contadores (erro, alerta e ok) de cada balancete, sem precisar chamar /{balancete_id}/validacoes uma vez por linha. A paginação espelha a de GET /balancetes-dominio/, para casar as duas respostas por id_balancete.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
id_clienteint (>0)querynãoRestringe a um cliente. Ausente = todos.
limitintquerynãoItens por página. Default 50, de 1 a 100.
offsetintquerynãoDeslocamento. Default 0.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Resumo de validacoes recuperado com sucesso",
  "data": [
    { "id_balancete": 42, "erros": 1, "alertas": 2, "ok": 9, "total": 12 }
  ]
}

total = 0 significa "nenhuma regra aplicável", e não "tudo ok". Sem balancetes, retorna data: [] com a mensagem "Nenhum balancete encontrado.". A rota é sujeita a limite de tentativas; ao exceder, 429 com Retry-After.

Escopo: balancetes_dominio:read

POST /balancetes-dominio/reprocessar-lote

Reprocessa os balancetes de um cliente: relê os PDFs já armazenados e aplica as correções do leitor ao que já foi importado. Não existe modo para todos os clientes. Uma falha em um balancete não aborta o lote: cada item vira uma linha do relatório e a resposta é sempre 200.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
id_clienteint (>0)querysimCliente.
limiteintquerynãoMáximo de balancetes por chamada. Default e máximo 20.
offsetintquerynãoDeslocamento, para percorrer históricos maiores que o limite. Default 0.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "1 de 2 balancetes reprocessados",
  "data": {
    "total": 2,
    "sucesso": 1,
    "falha": 1,
    "itens": [
      { "id_balancete": 42, "status": "ok", "linhas_antes": 74, "linhas_depois": 147, "erro": null },
      { "id_balancete": 43, "status": "erro", "linhas_antes": null, "linhas_depois": null, "erro": "mensagem do motivo da falha" }
    ]
  }
}

status de cada item é ok ou erro; erro só vem preenchido em erro. A rota é sujeita a limite de tentativas; ao exceder, 429 com Retry-After.

Escopo: balancetes_dominio:write

POST /balancetes-dominio/{balancete_id}/reprocessar

Relê o PDF original armazenado e substitui o conteúdo do balancete, preservando o id e o id_cliente. Serve para aplicar correções do leitor sem novo upload (o mesmo arquivo seria recusado como duplicado).

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
balancete_idintpathsimID interno do balancete

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Balancete reprocessado: 74 -> 147 linhas",
  "data": {
    "id": 42,
    "id_cliente": 1234,
    "periodo_inicio": "2026-01-01",
    "periodo_fim": "2026-01-31",
    "nome_arquivo_original": "balancete_janeiro.pdf",
    "linhas": [],
    "linhas_antes": 74,
    "linhas_depois": 147
  }
}

data segue o detalhe do balancete (BalanceteDominioDetail) mais linhas_antes e linhas_depois (quantidade de contas antes e depois, que prova o ganho). O exemplo omite campos já descritos no detalhe. Balancete inexistente -> 404; PDF original indisponível -> 409; PDF ilegível ou não reconhecido como balancete -> 422 (o registro permanece intacto). A rota é sujeita a limite de tentativas; ao exceder, 429 com Retry-After.

Escopo: balancetes_dominio:write

GET /balancetes-dominio/{balancete_id}/validacoes

Executa o motor de regras de análise sobre o balancete (linhas + guias fiscais do cliente no período) e retorna o resultado de cada validação. Quando o balancete não é encontrado, retorna 404 Not Found.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
balancete_idintpathsimID interno do balancete

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Validações executadas com sucesso",
  "data": [
    {
      "id_regra": 3,
      "nome": "ATIVO igual a PASSIVO + PL",
      "tipo": "igualdade",
      "gravidade": "alta",
      "origem": "sistema",
      "status": "passou",
      "evidencia": "Ativo (8000.00) confere com Passivo + Patrimônio Líquido.",
      "ocorrencias": []
    }
  ]
}

Escopo: balancetes_dominio:read

GET /balancetes-dominio/{balancete_id}/arquivo

Baixa o PDF original do balancete (application/pdf), servido como anexo com o nome original do arquivo. Quando o balancete não é encontrado, retorna 404 Not Found (ValueError).

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
balancete_idintpathsimID interno do balancete

Request

Sem corpo de requisição.

Response 200 OK

Retorna o binário do PDF (Content-Type: application/pdf), não o envelope JSON. O cabeçalho Content-Disposition traz o nome original do arquivo (nome_arquivo_original).

Escopo: balancetes_dominio:read

GET /balancetes-dominio/{balancete_id}

Detalha um balancete pelo ID inteiro, incluindo as linhas. Quando não encontrado, retorna 404 Not Found (ValueError).

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
balancete_idintpathsimID interno do balancete

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Balancete recuperado com sucesso",
  "data": {
    "id": 42,
    "id_usuario_created": 7,
    "id_cliente": 1234,
    "periodo_inicio": "2026-01-01",
    "periodo_fim": "2026-01-31",
    "data_emissao": "2026-02-05",
    "razao_social": "ACME SERVICOS LTDA",
    "cnpj": "12345678000199",
    "nome_arquivo_original": "balancete_janeiro.pdf",
    "tamanho_bytes": 84213,
    "hash_arquivo": "9f2c...",
    "data_hora_criacao": "2026-02-05T10:22:00-03:00",
    "linhas": [
      {
        "id": 1,
        "id_balancete": 42,
        "codigo_interno": "1",
        "classificacao": "1",
        "descricao": "ATIVO",
        "saldo_anterior": "0.00",
        "saldo_anterior_natureza": "D",
        "debito": "10000.00",
        "credito": "2000.00",
        "saldo_atual": "8000.00",
        "saldo_atual_natureza": "D",
        "nivel": 1,
        "ordem": 1
      }
    ]
  }
}

Escopo: balancetes_dominio:read

DELETE /balancetes-dominio/{balancete_id}

Exclui o balancete: linhas, cabeçalho e o PDF armazenado. Retorna 204 mesmo se o arquivo já não estivesse mais disponível.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
balancete_idintpathsimID interno do balancete

Request

Sem corpo de requisição.

Response 204 No Content

Sem corpo de resposta. Balancete inexistente -> 404 Not Found.

Escopo: balancetes_dominio:write

Schemas

BalanceteDominioRead

Cabeçalho do balancete (item de lista; sem as linhas). Somente leitura.

CampoTipoNotas
idintIdentificador do balancete.
id_usuario_createdintUsuário que fez o upload.
id_clienteintCliente resolvido pelo CNPJ.
periodo_iniciodateInício do período do balancete.
periodo_fimdateFim do período do balancete.
data_emissaodate?Data de emissão do PDF (opcional).
razao_socialstr?Razão social extraída do PDF (opcional).
cnpjstr?CNPJ extraído do PDF (opcional).
nome_arquivo_originalstrNome original do arquivo enviado.
tamanho_bytesintTamanho do arquivo em bytes.
hash_arquivostr?Hash do arquivo (deduplicação; opcional).
data_hora_criacaodatetimeData/hora do upload, normalizada para America/Sao_Paulo.

BalanceteDominioLinhaRead

Linha (conta) do balancete. Os valores monetários (decimal com 2 casas) são expostos como Decimal e serializados como string em JSON, preservando a precisão contábil.

CampoTipoNotas
idintIdentificador da linha.
id_balanceteintBalancete ao qual a linha pertence.
codigo_internostr?Código interno da conta (opcional).
classificacaostrClassificação contábil (ex.: 1.1.01).
descricaostrDescrição da conta.
saldo_anteriorDecimalSaldo anterior (string em JSON).
saldo_anterior_naturezastr?Natureza do saldo anterior (D/C).
debitoDecimalTotal de débitos (string em JSON).
creditoDecimalTotal de créditos (string em JSON).
saldo_atualDecimalSaldo atual (string em JSON).
saldo_atual_naturezastr?Natureza do saldo atual (D/C).
nivelintNível hierárquico da conta.
ordemintOrdem de exibição.

BalanceteDominioDetail

Detalhe completo: estende BalanceteDominioRead com o array de linhas.

CampoTipoNotas
(herda todos os campos de BalanceteDominioRead)
linhasList[BalanceteDominioLinhaRead]Linhas do balancete (default []).

BalanceteResumoValidacoesRead

Item de GET /balancetes-dominio/resumo-validacoes.

CampoTipoNotas
id_balanceteintBalancete resumido.
errosintValidações com erro.
alertasintValidações com alerta.
okintValidações que passaram.
totalintTotal de regras aplicáveis (0 = nenhuma regra).

BalanceteStatusClienteRead

Status de conferência de balancete de um cliente para um período. Item da resposta de GET /balancetes-dominio/status (um item por cliente que possui plano de contas).

CampoTipoNotas
id_clienteintCliente.
razao_socialstrRazão social do cliente.
cpfecnpjstr?CPF/CNPJ do cliente (opcional).
tem_movimentoboolHá lançamento no período.
tem_dominioboolHá balancete importado da Domínio.
dominio_data_importdate?Data de importação do balancete da Domínio (opcional).
conferidoboolMovimento conferido.
divergenciasint?Quantidade de divergências (opcional).
statusstrEstado derivado (ver tabela abaixo).

Valores possíveis de status (derivados no service):

ValorSignificado
sem_movimentoNão há lançamento no período.
pendenteTem movimento mas não está conferido (lançamento órfão: plano/contas inválidos).
okTem movimento, conferido, há balancete da Domínio e divergencias == 0.
andamentoTem movimento, conferido, mas sem balancete da Domínio ou com divergencias > 0.

Notas

  • Toda resposta segue o envelope { status, message, data } (erros de negócio vêm como { "message": ... } e a validação de entrada como 422 com { "detail": [...] }).
  • Não há endpoints Create/Update em JSON: a criação acontece exclusivamente via POST /balancetes-dominio/upload (multipart). Os schemas são somente leitura.
  • GET /balancetes-dominio/status, GET /balancetes-dominio/resumo-validacoes e POST /balancetes-dominio/reprocessar-lote são declarados antes das rotas dinâmicas GET /balancetes-dominio/{balancete_id}, então status é resolvido como rota estática (e não interpretado como um balancete_id).
  • Os valores monetários (Decimal, 2 casas) são serializados como string no JSON para preservar a precisão contábil.