Lançamentos Contábeis

Endpoints da WebApiAlcance para gerenciar lançamentos contábeis em partidas dobradas - cada lançamento debita uma conta (id_conta_debito) e credita outra (id_conta_credito) por um mesmo valor, dentro de uma competencia (MM/YYYY). Cobrem criação, listagens (todas, por usuário, por cliente, por plano de contas e por período), contadores por status, detalhamento por ID, atualização parcial, exclusão e exportação em TXT no padrão do sistema Domínio (leitura e modo transacional).

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

Base path

/api/v1/lancamentos-contabil

Escopos necessários

  • lancamentos_contabil:read - listagens, contadores, busca por ID, exportações por leitura (GET /exportar-txt, /exportar-csv, /exportar-xlsx) e GET /{lancamento_id}/regras-que-casam
  • lancamentos_contabil:write - criação, atualização, exclusão (individual e em lote), exportação transacional (POST /exportar), reavaliações e operações de lucro por conta

O escopo é derivado da rota: o prefixo /lancamentos-contabil vira o recurso lancamentos_contabil (hífen -> underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).

Endpoints

POST /lancamentos-contabil/

Cria um novo lançamento contábil (partida dobrada débito/crédito). O id_usuario_created é preenchido a partir do usuário autenticado - não é aceito no corpo.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (LancamentoContabilCreate). Campos obrigatórios: id_cliente, id_plano_contas, competencia, data_registro, id_conta_debito, id_conta_credito, valor, codigo_historico, historico_contabil. O status é opcional (default regra_pendente).

Request

{
  "id_cliente": 1234,
  "id_plano_contas": 88,
  "competencia": "01/2026",
  "data_registro": "2026-01-15",
  "id_conta_debito": 501,
  "id_conta_credito": 112,
  "valor": "1234.56",
  "codigo_historico": "0001",
  "historico_contabil": "Pagamento de fornecedor",
  "status": "regra_pendente"
}

Response 201 Created

{
  "status": "success",
  "message": "Lançamento contábil criado com sucesso",
  "data": {
    "id": 4210,
    "id_usuario_created": 7,
    "id_cliente": 1234,
    "id_plano_contas": 88,
    "competencia": "01/2026",
    "data_registro": "2026-01-15",
    "id_conta_debito": 501,
    "id_conta_credito": 112,
    "conta_debito": { "id": 501, "codigo_dominio": "3.1.01.001", "nome": "Despesas com Fornecedores" },
    "conta_credito": { "id": 112, "codigo_dominio": "1.1.01.002", "nome": "Bancos Conta Movimento" },
    "valor": "1234.56",
    "codigo_historico": "0001",
    "historico_contabil": "Pagamento de fornecedor",
    "status": "regra_pendente"
  }
}

Referências inexistentes, acesso negado ou duplicidade retornam 404, 403, 409 ou 422 conforme a mensagem. valor zerado (|valor| < 0,005) retorna 422 com detail[].type = "valor_zerado".

Escopo: lancamentos_contabil:write

GET /lancamentos-contabil/

Lista os lançamentos contábeis (visão compartilhada do escritório). Paginação opt-in: sem page/per_page retorna a lista completa (filtros e ordenação são ignorados); com eles, retorna o envelope paginado {items, total, total_pages, current_page, per_page} aplicando filtros e ordenação server-side. Lista vazia é um estado válido - sempre retorna 200 OK.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
pageintquerynãoPágina (1-based). Ativa a paginação.
per_pageintquerynãoItens por página (máx. 200).
searchstrquerynãoBusca (LIKE) em histórico, nº documento ou código de histórico.
origemstrquerynãoFiltra por origem (manual, import_ofx, ...).
statusstrquerynãoFiltra por status do lançamento.
data_iniciodatequerynãodata_registro >= (YYYY-MM-DD).
data_fimdatequerynãodata_registro <= (YYYY-MM-DD).
id_importacaointquerynãoImportação de origem (>= 1). Combina com origem por AND; id inexistente devolve lista vazia.
id_conta_debitointquerynãoConta de débito (id exato). Vence conta_debito_q.
id_conta_creditointquerynãoConta de crédito (id exato). Vence conta_credito_q.
conta_debito_qstrquerynãoBusca na conta de débito: prefixo em codigo_dominio ou trecho do nome. Ignorado se id_conta_debito vier.
conta_credito_qstrquerynãoBusca na conta de crédito: prefixo em codigo_dominio ou trecho do nome. Ignorado se id_conta_credito vier.
valor_mindecimalquerynãoValor mínimo em módulo (ABS(valor) >=), inclusivo, com ponto decimal. 0 é válido; negativo retorna 422.
valor_maxdecimalquerynãoValor máximo em módulo (ABS(valor) <=), inclusivo. valor_max < valor_min retorna 400; negativo retorna 422.
apenas_conflitoboolquerynãoSó lançamentos com conflito de regras (regras_conflito preenchido). Default false.
id_exportacaointquerynãoSó os lançamentos que foram no TXT desta exportação (>= 1). Exportação antiga (vinculo_lancamentos = false) ou inexistente devolve lista vazia.
sort_bystrquerynãoColuna: data, valor, historico, origem, status, cliente (default data).
sort_dirstrquerynãoasc ou desc (default desc).

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Lançamentos contábeis recuperados com sucesso",
  "data": [
    { "id": 4210, "id_cliente": 1234, "competencia": "01/2026", "valor": "1234.56", "status": "sucesso" },
    { "id": 4211, "id_cliente": 1234, "competencia": "01/2026", "valor": "-50.00", "status": "regra_pendente" }
  ]
}

Quando não há lançamentos, retorna data: [] com a mensagem "Nenhum lançamento contábil encontrado.".

Escopo: lancamentos_contabil:read

GET /lancamentos-contabil/contadores

Retorna a contagem e a soma em R$ dos lançamentos agrupadas por status, aplicando os mesmos filtros da listagem (exceto o próprio status). Alimenta os cards da UI (Sucesso / Regra pendente / Exportados / Total) sem carregar as linhas. Lançamentos zerados não entram nas contagens.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
id_clienteintquerynãoFiltra por cliente.
id_plano_contasintquerynãoFiltra por plano de contas.
searchstrquerynãoBusca (LIKE) em histórico, nº documento ou código de histórico.
origemstrquerynãoFiltra por origem (manual, import_ofx, ...).
data_iniciodatequerynãodata_registro >= (YYYY-MM-DD).
data_fimdatequerynãodata_registro <= (YYYY-MM-DD).
id_importacaointquerynãoImportação de origem (>= 1). Combina com origem por AND; id inexistente devolve lista vazia.
id_conta_debitointquerynãoConta de débito (id exato). Vence conta_debito_q.
id_conta_creditointquerynãoConta de crédito (id exato). Vence conta_credito_q.
conta_debito_qstrquerynãoBusca na conta de débito: prefixo em codigo_dominio ou trecho do nome. Ignorado se id_conta_debito vier.
conta_credito_qstrquerynãoBusca na conta de crédito: prefixo em codigo_dominio ou trecho do nome. Ignorado se id_conta_credito vier.
valor_mindecimalquerynãoValor mínimo em módulo (ABS(valor) >=), inclusivo, com ponto decimal. 0 é válido; negativo retorna 422.
valor_maxdecimalquerynãoValor máximo em módulo (ABS(valor) <=), inclusivo. valor_max < valor_min retorna 400; negativo retorna 422.
apenas_conflitoboolquerynãoSó lançamentos com conflito de regras (regras_conflito preenchido). Default false.
id_exportacaointquerynãoSó os lançamentos que foram no TXT desta exportação (>= 1). Exportação antiga (vinculo_lancamentos = false) ou inexistente devolve lista vazia.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Contadores recuperados com sucesso",
  "data": {
    "sucesso": 128,
    "regra_pendente": 14,
    "exportado": 302,
    "error": 3,
    "valor_total": "152340.55",
    "valor_sucesso": "20410.00",
    "valor_regra_pendente": "-1230.45",
    "valor_exportado": "133000.00",
    "valor_error": "161.00",
    "valor_regra_pendente_conflito": "-300.00"
  }
}

Os campos valor_* são strings decimais com ponto e com sinal (soma do valor, não do módulo; "0.00" quando ausente), então valor_total pode ser negativo. valor_regra_pendente_conflito é um subconjunto de valor_regra_pendente (só os lançamentos em conflito) e não deve ser somado ao total.

Escopo: lancamentos_contabil:read

GET /lancamentos-contabil/usuario/{usuario_id}

Lista os lançamentos contábeis de um usuário específico (apenas o próprio - acesso a outro usuário é negado).

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
usuario_idintpathsimID do usuário criador

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Lançamentos contábeis recuperados com sucesso",
  "data": [
    { "id": 4210, "id_cliente": 1234, "competencia": "01/2026", "valor": "1234.56", "status": "sucesso" }
  ]
}

Sem lançamentos, retorna data: [] com a mensagem "Nenhum lançamento contábil encontrado.".

Escopo: lancamentos_contabil:read

GET /lancamentos-contabil/cliente/{id_cliente}

Lista os lançamentos de um cliente específico (restrito aos do usuário autenticado). Paginação opt-in (os filtros e a ordenação só valem no caminho paginado).

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
id_clienteintpathsimID do cliente.
pageintquerynãoPágina (1-based). Ativa a paginação.
per_pageintquerynãoItens por página (máx. 200).
searchstrquerynãoBusca (LIKE) em histórico, nº documento ou código de histórico.
origemstrquerynãoFiltra por origem (manual, import_ofx, ...).
statusstrquerynãoFiltra por status do lançamento.
data_iniciodatequerynãodata_registro >= (YYYY-MM-DD).
data_fimdatequerynãodata_registro <= (YYYY-MM-DD).
id_importacaointquerynãoImportação de origem (>= 1). Combina com origem por AND; id inexistente devolve lista vazia.
id_conta_debitointquerynãoConta de débito (id exato). Vence conta_debito_q.
id_conta_creditointquerynãoConta de crédito (id exato). Vence conta_credito_q.
conta_debito_qstrquerynãoBusca na conta de débito: prefixo em codigo_dominio ou trecho do nome. Ignorado se id_conta_debito vier.
conta_credito_qstrquerynãoBusca na conta de crédito: prefixo em codigo_dominio ou trecho do nome. Ignorado se id_conta_credito vier.
valor_mindecimalquerynãoValor mínimo em módulo (ABS(valor) >=), inclusivo, com ponto decimal. 0 é válido; negativo retorna 422.
valor_maxdecimalquerynãoValor máximo em módulo (ABS(valor) <=), inclusivo. valor_max < valor_min retorna 400; negativo retorna 422.
apenas_conflitoboolquerynãoSó lançamentos com conflito de regras (regras_conflito preenchido). Default false.
sort_bystrquerynãoColuna: data, valor, historico, origem, status, cliente (default data).
sort_dirstrquerynãoasc ou desc (default desc).

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Lançamentos contábeis recuperados com sucesso",
  "data": [
    { "id": 4210, "id_cliente": 1234, "competencia": "01/2026", "valor": "1234.56", "status": "sucesso" }
  ]
}

Escopo: lancamentos_contabil:read

GET /lancamentos-contabil/plano-contas/{id_plano_contas}

Lista os lançamentos vinculados a um plano de contas (restrito aos do usuário autenticado). Paginação opt-in (os filtros e a ordenação só valem no caminho paginado).

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
id_plano_contasintpathsimID do plano de contas.
pageintquerynãoPágina (1-based). Ativa a paginação.
per_pageintquerynãoItens por página (máx. 200).
searchstrquerynãoBusca (LIKE) em histórico, nº documento ou código de histórico.
origemstrquerynãoFiltra por origem (manual, import_ofx, ...).
statusstrquerynãoFiltra por status do lançamento.
data_iniciodatequerynãodata_registro >= (YYYY-MM-DD).
data_fimdatequerynãodata_registro <= (YYYY-MM-DD).
id_importacaointquerynãoImportação de origem (>= 1). Combina com origem por AND; id inexistente devolve lista vazia.
id_conta_debitointquerynãoConta de débito (id exato). Vence conta_debito_q.
id_conta_creditointquerynãoConta de crédito (id exato). Vence conta_credito_q.
conta_debito_qstrquerynãoBusca na conta de débito: prefixo em codigo_dominio ou trecho do nome. Ignorado se id_conta_debito vier.
conta_credito_qstrquerynãoBusca na conta de crédito: prefixo em codigo_dominio ou trecho do nome. Ignorado se id_conta_credito vier.
valor_mindecimalquerynãoValor mínimo em módulo (ABS(valor) >=), inclusivo, com ponto decimal. 0 é válido; negativo retorna 422.
valor_maxdecimalquerynãoValor máximo em módulo (ABS(valor) <=), inclusivo. valor_max < valor_min retorna 400; negativo retorna 422.
apenas_conflitoboolquerynãoSó lançamentos com conflito de regras (regras_conflito preenchido). Default false.
sort_bystrquerynãoColuna: data, valor, historico, origem, status, cliente (default data).
sort_dirstrquerynãoasc ou desc (default desc).

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Lançamentos contábeis recuperados com sucesso",
  "data": [
    { "id": 4210, "id_cliente": 1234, "id_plano_contas": 88, "valor": "1234.56", "status": "sucesso" }
  ]
}

Escopo: lancamentos_contabil:read

GET /lancamentos-contabil/periodo

Lista os lançamentos com data_registro no intervalo [inicio, fim] (inclusivo), restrito aos do usuário autenticado. Se fim for anterior a inicio, retorna 400 Bad Request com detail: "'fim' não pode ser anterior a 'inicio'.". Paginação opt-in (filtros e ordenação só valem no caminho paginado).

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
iniciodatequerysimData inicial (YYYY-MM-DD).
fimdatequerysimData final (YYYY-MM-DD).
pageintquerynãoPágina (1-based). Ativa a paginação.
per_pageintquerynãoItens por página (máx. 200).
searchstrquerynãoBusca (LIKE) em histórico, nº documento ou código de histórico.
origemstrquerynãoFiltra por origem (manual, import_ofx, ...).
statusstrquerynãoFiltra por status do lançamento.
id_importacaointquerynãoImportação de origem (>= 1). Combina com origem por AND; id inexistente devolve lista vazia.
id_conta_debitointquerynãoConta de débito (id exato). Vence conta_debito_q.
id_conta_creditointquerynãoConta de crédito (id exato). Vence conta_credito_q.
conta_debito_qstrquerynãoBusca na conta de débito: prefixo em codigo_dominio ou trecho do nome. Ignorado se id_conta_debito vier.
conta_credito_qstrquerynãoBusca na conta de crédito: prefixo em codigo_dominio ou trecho do nome. Ignorado se id_conta_credito vier.
valor_mindecimalquerynãoValor mínimo em módulo (ABS(valor) >=), inclusivo, com ponto decimal. 0 é válido; negativo retorna 422.
valor_maxdecimalquerynãoValor máximo em módulo (ABS(valor) <=), inclusivo. valor_max < valor_min retorna 400; negativo retorna 422.
apenas_conflitoboolquerynãoSó lançamentos com conflito de regras (regras_conflito preenchido). Default false.
sort_bystrquerynãoColuna: data, valor, historico, origem, status, cliente (default data).
sort_dirstrquerynãoasc ou desc (default desc).

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Lançamentos contábeis recuperados com sucesso",
  "data": [
    { "id": 4210, "id_cliente": 1234, "data_registro": "2026-01-15", "valor": "1234.56", "status": "sucesso" }
  ]
}

Escopo: lancamentos_contabil:read

GET /lancamentos-contabil/exportar-txt

Gera o arquivo TXT no padrão do sistema Domínio para o cliente informado. Retorna text/plain (não o envelope JSON), com header Content-Disposition: attachment. Por padrão inclui apenas lançamentos com status='sucesso'. Os filtros temporais são mutuamente exclusivos: use competencia ou o par data_inicio/data_fim.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
id_clienteintquerysimID do cliente.
competenciastrquerynãoCompetência MM/YYYY. Exclusivo com data_inicio/data_fim.
data_iniciodatequerynãoData inicial (YYYY-MM-DD), em conjunto com data_fim.
data_fimdatequerynãoData final (YYYY-MM-DD), em conjunto com data_inicio.
statusstrquerynãoStatus a incluir. Default sucesso. Aceita sucesso, error ou regra_pendente para diagnóstico.

Request

Sem corpo de requisição.

GET /api/v1/lancamentos-contabil/exportar-txt?id_cliente=1234&competencia=01/2026
GET /api/v1/lancamentos-contabil/exportar-txt?id_cliente=1234&data_inicio=2026-01-01&data_fim=2026-01-31

Response 200 OK

Content-Type: text/plain; charset=utf-8
Content-Disposition: attachment; filename="Extrato_012026.txt"
 
<conteúdo do arquivo TXT no layout do sistema Domínio>

O nome do arquivo é Extrato_MMYYYY.txt (por competência) ou Extrato_YYYYMMDD_YYYYMMDD.txt (por período). Cliente inexistente -> 404; cliente sem conta configurada -> 422; demais erros de filtro -> 400.

Escopo: lancamentos_contabil:read

GET /lancamentos-contabil/exportar-csv

Extração dos lançamentos do cliente em CSV (UTF-8 com BOM, separador ;, vírgula decimal). Leitura pura: não grava histórico de exportação e não altera o status de nenhum lançamento, então pode ser baixado quantas vezes for preciso. Retorna o arquivo (não o envelope JSON), com Content-Disposition: attachment.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
id_clienteintquerysimID do cliente.
competenciastrquerynãoCompetência MM/YYYY. Exclusivo com data_inicio/data_fim.
data_iniciodatequerynãoData inicial (YYYY-MM-DD), em conjunto com data_fim.
data_fimdatequerynãoData final (YYYY-MM-DD), em conjunto com data_inicio.
statusstrquerynãoStatus a incluir. Omitido = sucesso + exportado.

Request

Sem corpo de requisição.

Response 200 OK

Content-Type: text/csv; charset=utf-8
Content-Disposition: attachment; filename="Extrato_012026.csv"
 
<conteúdo do arquivo CSV>

Cliente inexistente -> 404; período sem lançamento elegível ou cliente sem conta configurada -> 422; competencia fora do formato MM/YYYY -> 422; demais erros de filtro -> 400.

Escopo: lancamentos_contabil:read

GET /lancamentos-contabil/exportar-xlsx

Mesma extração do exportar-csv, em XLSX: Valor vai como número e Data como data na planilha. Leitura pura, sem efeito sobre o status dos lançamentos.

Parâmetros

Os mesmos de GET /lancamentos-contabil/exportar-csv.

Request

Sem corpo de requisição.

Response 200 OK

Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename="Extrato_012026.xlsx"
 
<conteúdo do arquivo XLSX>

Erros iguais aos do exportar-csv.

Escopo: lancamentos_contabil:read

POST /lancamentos-contabil/exportar

Exportação oficial por período (modo transacional). Seleciona os lançamentos status='sucesso' do cliente no período, gera o TXT (padrão Domínio), grava o arquivo em disco, cria um registro de histórico em exportacao (para re-download) e vira os lançamentos selecionados para status='exportado' - tudo numa única transação. Retorna o próprio TXT (text/plain, download).

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
id_clienteintquerysimID do cliente.
data_iniciodatequerysimData inicial (YYYY-MM-DD).
data_fimdatequerysimData final (YYYY-MM-DD).

Request

Sem corpo de requisição (os parâmetros vão na query).

POST /api/v1/lancamentos-contabil/exportar?id_cliente=1234&data_inicio=2026-01-01&data_fim=2026-01-31

Response 200 OK

Content-Type: text/plain; charset=utf-8
Content-Disposition: attachment; filename="Extrato_20260101_20260131.txt"
X-Exportacao-Id: 57
X-Exportacao-Qtd: 42
 
<conteúdo do arquivo TXT no layout do sistema Domínio>

Os headers X-Exportacao-Id (ID da exportação criada) e X-Exportacao-Qtd (quantidade de lançamentos incluídos) são expostos via Access-Control-Expose-Headers. Se data_fim < data_inicio -> 400. Período sem nenhum lançamento elegível -> 422 ("nada a exportar"; nenhum registro é criado e nenhum status é alterado). Cliente inexistente -> 404; cliente sem conta configurada -> 422.

Escopo: lancamentos_contabil:write

POST /lancamentos-contabil/cliente/{id_cliente}/reavaliar-pendentes

Reaplica as regras de-para existentes aos lançamentos em status='regra_pendente' do cliente e promove a sucesso os que passarem a ter conta de débito e crédito. Não re-parseia arquivo - usa o mesmo motor de regras da importação. Escopo forward-only estrito: só toca regra_pendente; lançamentos sucesso, exportado e error ficam intactos. Útil após criar/ajustar regras, para reclassificar pendentes sem reimportar.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
id_clienteintpathsimID do cliente.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Reavaliação de pendentes concluída",
  "data": {
    "reavaliados": 37,
    "promovidos": 29,
    "qtd_lucros_gerados": 2,
    "lucros_por_conta": null
  }
}

reavaliados é o total de lançamentos regra_pendente analisados; promovidos é quantos passaram a ter débito e crédito e viraram sucesso; qtd_lucros_gerados é quantos lançamentos de lucro foram criados para os promovidos por regra com sócio; lucros_por_conta é o resumo dos promovidos que debitam conta com sócio (ou null quando não há). Cliente inexistente -> 404.

Escopo: lancamentos_contabil:write

POST /lancamentos-contabil/cliente/{id_cliente}/lucros-por-conta/gerar

Gera o lançamento de lucro dos lançamentos que debitam uma conta vinculada a sócio ativo do cliente. Idempotente: não duplica lucro já existente.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
id_clienteintpathsimID do cliente.

Request (IdsLucrosPorContaRequest)

{ "ids": [4210, 4211] }

ids é obrigatório (1 a 500 inteiros positivos) e funciona como sugestão: o servidor recalcula o recorte elegível, e ids de outro cliente ou fora do recorte são ignorados sem erro.

Response 200 OK

{
  "status": "success",
  "message": "Lucros por conta: 2 criado(s), 0 já existente(s), 0 pulado(s)",
  "data": { "avaliados": 2, "candidatos": 2, "criados": 2, "pulados": 0, "existentes": 0 }
}

avaliados são os lançamentos do recorte, candidatos os que têm sócio na conta, criados os lucros novos, existentes os que já tinham lucro e pulados os não gerados. Body inválido ou mais de 500 ids -> 422.

Escopo: lancamentos_contabil:write

POST /lancamentos-contabil/cliente/{id_cliente}/lucros-por-conta/trocar-socio

Troca o sócio do lucro gerado por regra para o sócio da conta de débito, sem criar nem apagar lucro.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
id_clienteintpathsimID do cliente.

Request (IdsLucrosPorContaRequest)

{ "ids": [4210, 4211] }

ids é obrigatório (1 a 500 inteiros positivos) e funciona como sugestão: o servidor recalcula o recorte elegível, e ids de outro cliente ou fora do recorte são ignorados sem erro.

Response 200 OK

{
  "status": "success",
  "message": "Troca de sócio por conta: 1 trocado(s), 0 pulado(s)",
  "data": { "avaliados": 1, "candidatos": 1, "trocados": 1, "pulados": 0 }
}

trocados são os lucros que mudaram de sócio e pulados os ignorados (lucro manual, já declarado à Receita ou já no mesmo sócio). Body inválido ou mais de 500 ids -> 422.

Escopo: lancamentos_contabil:write

POST /lancamentos-contabil/cliente/{id_cliente}/lucros-por-conta/desfazer

Exclui o lucro gerado por regra que já está no sócio da conta de débito. Só afeta lucros que ainda não foram enviados à Reinf.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
id_clienteintpathsimID do cliente.

Request (IdsLucrosPorContaRequest)

{ "ids": [4210, 4211] }

ids é obrigatório (1 a 500 inteiros positivos) e funciona como sugestão: o servidor recalcula o recorte elegível, e ids de outro cliente ou fora do recorte são ignorados sem erro.

Response 200 OK

{
  "status": "success",
  "message": "Desfazer lucros por conta: 1 excluído(s), 0 pulado(s)",
  "data": { "avaliados": 1, "candidatos": 1, "excluidos": 1, "pulados": 0 }
}

excluidos são os lucros apagados; excluidos menor que o número de ids enviados não é erro, pois lucros manuais, em processamento ou já declarados são ignorados. Body inválido ou mais de 500 ids -> 422.

Escopo: lancamentos_contabil:write

POST /lancamentos-contabil/cliente/{id_cliente}/lucros-por-conta/mover

Religa aos lançamentos informados o lucro que já existe no mesmo lançamento de outra importação do mesmo arquivo, mantendo um lucro por pagamento (nada é criado nem apagado).

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
id_clienteintpathsimID do cliente.

Request (IdsLucrosPorContaRequest)

{ "ids": [4210, 4211] }

ids é obrigatório (1 a 500 inteiros positivos) e funciona como sugestão: o servidor recalcula o recorte elegível, e ids de outro cliente ou fora do recorte são ignorados sem erro.

Response 200 OK

{
  "status": "success",
  "message": "Mover lucros duplicados: 1 movido(s), 0 pulado(s)",
  "data": { "avaliados": 1, "candidatos": 1, "movidos": 1, "pulados": 0 }
}

movidos são os lucros religados e pulados os ignorados (outro cliente, já declarado à Receita ou lançamento novo que já tem lucro). Body inválido ou mais de 500 ids -> 422.

Escopo: lancamentos_contabil:write

POST /lancamentos-contabil/cliente/{id_cliente}/reavaliar-periodo/simular

Pré-visualiza o que a reavaliação por período mudaria, sem gravar nada. Recebe o mesmo corpo de .../aplicar.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
id_clienteintpathsimID do cliente.

Request (ReavaliarPeriodoRequest)

{
  "data_inicio": "2026-01-01",
  "data_fim": "2026-01-31",
  "id_importacao": 90,
  "incluir_classificados_manualmente": false
}

Informe o par data_inicio + data_fim e/ou id_importacao (pelo menos um recorte; combinam por AND). incluir_classificados_manualmente (default false) inclui também contas digitadas à mão. Campos fora do schema retornam 422.

Response 200 OK

{
  "status": "success",
  "message": "Simulação da reavaliação por período",
  "data": {
    "simulado": true,
    "recorte_aplicado": {
      "data_inicio": "2026-01-01",
      "data_fim": "2026-01-31",
      "id_importacao": 90,
      "status_considerados": ["sucesso", "regra_pendente", "exportado"]
    },
    "incluir_classificados_manualmente": false,
    "elegiveis": 120,
    "afetados": 14,
    "sem_mudanca": 100,
    "preservados": 6,
    "preservados_por_motivo": {
      "ja_exportado": { "qtd": 6, "motivo": "Já exportado - reclassificar divergiria do arquivo entregue ao Domínio" }
    },
    "slots_manuais_preservados": 0,
    "amostra": [],
    "amostra_limite": 1000,
    "amostra_truncada": false
  }
}

Os contadores são sempre completos; amostra traz o de-para (contas, plano, status, regras e histórico, já em rótulo legível) dos afetados e preservados e pode vir truncada em amostra_limite. Lançamento exportado é sempre preservado, e o plano de contas nunca muda (regra com conta de outro plano preserva o lançamento com motivo plano_divergente).

Sem recorte, data_inicio sem data_fim (ou o inverso) ou recorte acima de 20.000 lançamentos -> 422; data_fim anterior a data_inicio -> 400; cliente inexistente -> 404.

Escopo: lancamentos_contabil:write

POST /lancamentos-contabil/cliente/{id_cliente}/reavaliar-periodo/aplicar

Grava a reclassificação por regras dos lançamentos do recorte. Mesmo corpo e mesma resposta da simulação (com simulado: false e a mensagem "Reavaliação por período aplicada"); afetados vale o número desta resposta, que pode diferir da simulação se algo mudou entre as chamadas.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
id_clienteintpathsimID do cliente.

Request

Mesmo ReavaliarPeriodoRequest do simular.

Response 200 OK

{
  "status": "success",
  "message": "Reavaliação por período aplicada",
  "data": { "simulado": false, "elegiveis": 120, "afetados": 14, "sem_mudanca": 100, "preservados": 6 }
}

O exemplo omite os campos idênticos aos da simulação. A gravação ocorre em lotes e a operação é idempotente: uma falha depois de lotes já gravados retorna 500 informando quantos lançamentos foram gravados, e basta repetir a chamada. Erros de recorte iguais aos do simular.

Escopo: lancamentos_contabil:write

POST /lancamentos-contabil/excluir-lote

Exclui vários lançamentos em uma única transação (tudo ou nada).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os ids vão no corpo.

Request (ExcluirLoteLancamentosRequest)

{ "ids": [4210, 4211, 9999] }

ids é obrigatório (1 a 500 inteiros positivos); duplicados são desconsiderados.

Response 200 OK

{
  "status": "success",
  "message": "Exclusão em lote processada com sucesso",
  "data": { "solicitados": 3, "removidos": [4210, 4211], "nao_encontrados": [9999] }
}

Ids inexistentes não são erro: vêm em nao_encontrados. Se algum lançamento tiver lucro vinculado, o lote inteiro é recusado com 409 e nada é apagado. Body inválido -> 422.

Escopo: lancamentos_contabil:write

GET /lancamentos-contabil/{lancamento_id}/regras-que-casam

Simula o motor de regras contra o lançamento agora e informa, por conta (débito e crédito), qual regra a preencheria. Não grava nada. Regras inativas e regras de ignorar não entram; padrões de regra por banco entram com origem = "padrao_regra_banco".

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
lancamento_idintpathsimID interno do lançamento

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Regras que casam com o lançamento",
  "data": {
    "id_lancamento": 4210,
    "motor": "padrao_importacao",
    "escopo": { "id_estrutura": 5, "id_klingo_layout": null, "id_banco": null },
    "usou_fallback": null,
    "slots": {
      "conta_debito": {
        "coberto": true,
        "conflito": false,
        "regras": [
          {
            "id": 15,
            "nome": "Tarifa bancaria",
            "origem": "regra_lancamento",
            "escopo": "estrutura",
            "id_estrutura": 5,
            "id_klingo_layout": null,
            "id_banco": null,
            "campo_destino": "conta_debito",
            "id_conta": 501
          }
        ]
      },
      "conta_credito": { "coberto": false, "conflito": false, "regras": [] }
    }
  }
}

motor é padrao_importacao ou escopo_klingo (importação de layout Klingo; usou_fallback indica se só regras gerais foram usadas). escopo da regra: geral, estrutura, klingo_layout ou banco. Em conflito, o slot vem com conflito: true, coberto: false e as regras disputantes. Lançamento inexistente -> 404.

Escopo: lancamentos_contabil:read

GET /lancamentos-contabil/{lancamento_id}

Detalha um lançamento contábil pelo ID inteiro (restrito ao usuário autenticado). Quando não encontrado, retorna 404 Not Found.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
lancamento_idintpathsimID interno do lançamento

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Lançamento contábil encontrado com sucesso",
  "data": {
    "id": 4210,
    "id_usuario_created": 7,
    "id_cliente": 1234,
    "id_plano_contas": 88,
    "competencia": "01/2026",
    "data_registro": "2026-01-15",
    "id_conta_debito": 501,
    "id_conta_credito": 112,
    "conta_debito": { "id": 501, "codigo_dominio": "3.1.01.001", "nome": "Despesas com Fornecedores" },
    "conta_credito": { "id": 112, "codigo_dominio": "1.1.01.002", "nome": "Bancos Conta Movimento" },
    "valor": "1234.56",
    "codigo_historico": "0001",
    "historico_contabil": "Pagamento de fornecedor",
    "status": "sucesso",
    "origem": "manual",
    "regras_aplicadas": [],
    "regras_conflito": []
  }
}

Escopo: lancamentos_contabil:read

PUT /lancamentos-contabil/{lancamento_id}

Atualiza um lançamento existente. O corpo é um LancamentoContabilUpdate com campos parciais - somente o que vier preenchido é alterado. id_cliente, id_fixo, id_usuario_created, id e data_hora_criacao são imutáveis (não aparecem no schema). id_plano_contas só é aceito para lançamentos órfãos (id_plano_contas IS NULL); trocar um plano já definido por outro é bloqueado com 422.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
lancamento_idintpathsimID do lançamento

Request (LancamentoContabilUpdate - todos os campos opcionais)

{
  "valor": "1500.00",
  "historico_contabil": "Pagamento de fornecedor (ajustado)",
  "status": "sucesso"
}

Response 200 OK

{
  "status": "success",
  "message": "Lançamento contábil atualizado com sucesso",
  "data": {
    "id": 4210,
    "id_usuario_created": 7,
    "id_cliente": 1234,
    "id_plano_contas": 88,
    "competencia": "01/2026",
    "data_registro": "2026-01-15",
    "id_conta_debito": 501,
    "id_conta_credito": 112,
    "conta_debito": { "id": 501, "codigo_dominio": "3.1.01.001", "nome": "Despesas com Fornecedores" },
    "conta_credito": { "id": 112, "codigo_dominio": "1.1.01.002", "nome": "Bancos Conta Movimento" },
    "valor": "1500.00",
    "codigo_historico": "0001",
    "historico_contabil": "Pagamento de fornecedor (ajustado)",
    "status": "sucesso"
  }
}

Referência inexistente, acesso negado ou conflito -> 404, 403, 409 ou 422.

Escopo: lancamentos_contabil:write

DELETE /lancamentos-contabil/{lancamento_id}

Remove permanentemente um lançamento contábil pelo ID. Quando não encontrado, retorna 404 Not Found; lançamento com lucro vinculado retorna 409 Conflict (exclua o lucro antes).

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
lancamento_idintpathsimID do lançamento

Request

Sem corpo de requisição.

Response 204 No Content

(sem corpo)

Escopo: lancamentos_contabil:write

Schemas

LancamentoContabilCreate

CampoTipoObrigatórioObservações
id_clienteintsimID do cliente ao qual o lançamento pertence.
id_plano_contasintsimID do plano de contas que organiza o lançamento.
id_fixointnãoVincula o lançamento a um lançamento fixo.
linha_arquivointnãoLinha do arquivo de origem (quando importado de TXT/CSV).
competenciastrsimFormato MM/YYYY (ex.: 01/2026). 7 caracteres.
data_registrodatesimData contábil do registro (YYYY-MM-DD, sem hora).
id_conta_debitointsimID da conta debitada (contas.id).
id_conta_creditointsimID da conta creditada (contas.id).
valorstrsimValor monetário como string, 1-2 casas decimais. Aceita negativos (ex.: 1234.56, -50,00); zero (|valor| < 0,005) retorna 422. , é normalizado para .; limite |valor| < 10.000.000.000.000.
codigo_historicostrsimCódigo do histórico contábil padrão. Máx. 50.
historico_contabilstrsimDescrição/histórico do lançamento. Máx. 500.
numero_documentostrnãoNúmero do documento de origem (nota, recibo). Máx. 50.
codigo_filialstrnãoCódigo da filial (espelho Fivelabs/Domínio). Máx. 50.
lancamento_scpstrnãoIdentificação SCP (espelho Fivelabs/Domínio). Máx. 50.
campo_auxiliar_1strnãoCampo auxiliar 1 (espelho Fivelabs/Domínio). Máx. 300.
campo_auxiliar_2strnãoCampo auxiliar 2 (espelho Fivelabs/Domínio). Máx. 300.
campo_auxiliar_3strnãoCampo auxiliar 3 (espelho Fivelabs/Domínio). Máx. 300.
statusstrnãoUm de sucesso, error, regra_pendente, exportado. Default regra_pendente.
observacaostrnãoObservação livre (texto, sem limite).

LancamentoContabilUpdate

Todos os campos são opcionais; apenas os enviados são atualizados. Campos imutáveis (id_cliente, id_fixo, id_usuario_created, id, data_hora_criacao) não fazem parte do schema.

CampoTipoObservações
linha_arquivointLinha do arquivo de origem.
competenciastrFormato MM/YYYY.
data_registrodateData contábil do registro.
id_plano_contasint> 0. Aceito apenas quando o lançamento está órfão (id_plano_contas IS NULL); trocar plano definido é bloqueado com 422.
id_conta_debitointReatribui a conta debitada.
id_conta_creditointReatribui a conta creditada.
valorstrMesmas regras de validação do Create (inclusive a recusa de zero com 422).
codigo_historicostrMáx. 50.
historico_contabilstrMáx. 500.
numero_documentostrMáx. 50.
codigo_filialstrMáx. 50.
lancamento_scpstrMáx. 50.
campo_auxiliar_1strMáx. 300.
campo_auxiliar_2strMáx. 300.
campo_auxiliar_3strMáx. 300.
statusstrUm de sucesso, error, regra_pendente, exportado.
observacaostrObservação livre.

LancamentoContabilRead

CampoTipoNotas
idintIdentificador do lançamento.
id_usuario_createdintUsuário que criou o lançamento.
id_clienteintCliente.
id_plano_contasint | nullNullable - lançamentos importados em regra_pendente ficam sem plano até a atribuição por regra.
data_hora_criacaodatetimeConvertido para o fuso America/Sao_Paulo.
id_fixoint | nullVínculo a lançamento fixo.
linha_arquivoint | nullLinha do arquivo de origem.
competenciastrMM/YYYY.
data_registrodateData contábil.
id_conta_debitoint | nullConta debitada.
id_conta_creditoint | nullConta creditada.
conta_debitoContaResumo | nullResumo denormalizado da conta de débito ({id, codigo_dominio, nome}), resolvido em batch. null quando a FK é nula ou a conta não existe mais.
conta_creditoContaResumo | nullResumo denormalizado da conta de crédito. Mesma semântica de conta_debito.
valorstrValor monetário normalizado.
codigo_historicostrCódigo do histórico.
historico_contabilstrDescrição do lançamento.
numero_documentostr | nullDocumento de origem.
codigo_filialstr | nullCódigo da filial.
lancamento_scpstr | nullIdentificação SCP.
campo_auxiliar_1..3str | nullCampos auxiliares (espelho Fivelabs/Domínio).
statusstrsucesso, error, regra_pendente ou exportado.
observacaostr | nullObservação livre.
origemstr | nullOrigem do lançamento (default manual).
id_importacaoint | nullImportação que originou o lançamento (quando aplicável).
regras_aplicadasRegraAplicadaInfo[]Regras que classificaram o lançamento na importação, já resolvidas ({id, ordem, nome, campo_destino}). Lista vazia para lançamentos manuais/legados.
regras_conflitoRegraAplicadaInfo[]Regras que disputaram o mesmo slot de conta sem vencedor (importação Klingo). Vazio = sem conflito; preenchido = lançamento regra_pendente aguardando resolução.

ContaResumo

Resumo denormalizado de uma conta contábil, embutido em conta_debito/conta_credito do LancamentoContabilRead para o frontend exibir débito/crédito sem carregar o plano de contas inteiro. Resolvido em batch na camada de serviço (1 query por página, anti-N+1); é aditivo e retrocompatível.

CampoTipoNotas
idintID da conta.
codigo_dominiostrCódigo Domínio da conta.
nomestrNome da conta.

Notas

  • Toda resposta JSON segue o envelope { status, message, data } (ou { "message": ... } em erro de negócio e { "detail": [...] } em 422 de validação). As rotas de exportação (GET /exportar-txt, GET /exportar-csv, GET /exportar-xlsx e POST /exportar) fogem ao padrão: devolvem o arquivo como download (não o envelope), e a transacional expõe X-Exportacao-Id/X-Exportacao-Qtd nos headers.
  • Partidas dobradas: todo lançamento debita id_conta_debito e credita id_conta_credito pelo mesmo valor.
  • Paginação opt-in: as listagens (GET /, GET /cliente/{id_cliente}, GET /plano-contas/{id_plano_contas}, GET /periodo) só aplicam filtros e ordenação quando page/per_page são informados; nesse caso o data é o envelope {items, total, total_pages, current_page, per_page}. Sem eles, retornam a lista completa (retrocompatível).
  • Ciclo de vida do status: regra_pendente -> sucesso -> exportado (estados mutuamente exclusivos); error fica à parte (falha de processamento). Apenas status='sucesso' é elegível para a exportação TXT; a exportação transacional vira os selecionados para exportado, evitando duplicidade em re-exportações.
  • Armadilha de roteamento FastAPI. As rotas estáticas (GET /contadores, GET /periodo, GET /exportar-txt, GET /exportar-csv, GET /exportar-xlsx, POST /exportar e POST /excluir-lote) são declaradas antes das rotas dinâmicas /{lancamento_id}, então são resolvidas como estáticas (e não interpretadas como um lancamento_id).
  • Relaciona-se com Customers (id_cliente) e com os domínios de contas e plano de contas que fornecem id_conta_debito, id_conta_credito e id_plano_contas.