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.

Base path

/api/v1/balancetes-dominio

Escopos necessários

• balancetes_dominio:read - listagem, status por período e detalhamento
• balancetes_dominio:write - upload de PDF

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).

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

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

{
  "success": true,
  "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 limite (IMPORTACAO_MAX_UPLOAD_BYTES) 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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "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

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

{
  "success": true,
  "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/{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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "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

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "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

Schemas

BalanceteDominioRead

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

BalanceteDominioLinhaRead

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

BalanceteDominioDetail

Detalhe completo: estende BalanceteDominioRead com o array de linhas.

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).

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

Notas

• Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
• 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 é declarado antes da rota dinâmica 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, Numeric(15,2)) são serializados como string no JSON para preservar a precisão contábil.
• O campo interno nome_arquivo_armazenado (caminho em disco) é omitido de propósito das respostas.