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-contabilEscopos necessários
lancamentos_contabil:read- listagens, contadores, busca por ID, exportações por leitura (GET /exportar-txt,/exportar-csv,/exportar-xlsx) eGET /{lancamento_id}/regras-que-casamlancamentos_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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
page | int | query | não | Página (1-based). Ativa a paginação. |
per_page | int | query | não | Itens por página (máx. 200). |
search | str | query | não | Busca (LIKE) em histórico, nº documento ou código de histórico. |
origem | str | query | não | Filtra por origem (manual, import_ofx, ...). |
status | str | query | não | Filtra por status do lançamento. |
data_inicio | date | query | não | data_registro >= (YYYY-MM-DD). |
data_fim | date | query | não | data_registro <= (YYYY-MM-DD). |
id_importacao | int | query | não | Importação de origem (>= 1). Combina com origem por AND; id inexistente devolve lista vazia. |
id_conta_debito | int | query | não | Conta de débito (id exato). Vence conta_debito_q. |
id_conta_credito | int | query | não | Conta de crédito (id exato). Vence conta_credito_q. |
conta_debito_q | str | query | não | Busca na conta de débito: prefixo em codigo_dominio ou trecho do nome. Ignorado se id_conta_debito vier. |
conta_credito_q | str | query | não | Busca na conta de crédito: prefixo em codigo_dominio ou trecho do nome. Ignorado se id_conta_credito vier. |
valor_min | decimal | query | não | Valor mínimo em módulo (ABS(valor) >=), inclusivo, com ponto decimal. 0 é válido; negativo retorna 422. |
valor_max | decimal | query | não | Valor máximo em módulo (ABS(valor) <=), inclusivo. valor_max < valor_min retorna 400; negativo retorna 422. |
apenas_conflito | bool | query | não | Só lançamentos com conflito de regras (regras_conflito preenchido). Default false. |
id_exportacao | int | query | não | Só os lançamentos que foram no TXT desta exportação (>= 1). Exportação antiga (vinculo_lancamentos = false) ou inexistente devolve lista vazia. |
sort_by | str | query | não | Coluna: data, valor, historico, origem, status, cliente (default data). |
sort_dir | str | query | não | asc 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
id_cliente | int | query | não | Filtra por cliente. |
id_plano_contas | int | query | não | Filtra por plano de contas. |
search | str | query | não | Busca (LIKE) em histórico, nº documento ou código de histórico. |
origem | str | query | não | Filtra por origem (manual, import_ofx, ...). |
data_inicio | date | query | não | data_registro >= (YYYY-MM-DD). |
data_fim | date | query | não | data_registro <= (YYYY-MM-DD). |
id_importacao | int | query | não | Importação de origem (>= 1). Combina com origem por AND; id inexistente devolve lista vazia. |
id_conta_debito | int | query | não | Conta de débito (id exato). Vence conta_debito_q. |
id_conta_credito | int | query | não | Conta de crédito (id exato). Vence conta_credito_q. |
conta_debito_q | str | query | não | Busca na conta de débito: prefixo em codigo_dominio ou trecho do nome. Ignorado se id_conta_debito vier. |
conta_credito_q | str | query | não | Busca na conta de crédito: prefixo em codigo_dominio ou trecho do nome. Ignorado se id_conta_credito vier. |
valor_min | decimal | query | não | Valor mínimo em módulo (ABS(valor) >=), inclusivo, com ponto decimal. 0 é válido; negativo retorna 422. |
valor_max | decimal | query | não | Valor máximo em módulo (ABS(valor) <=), inclusivo. valor_max < valor_min retorna 400; negativo retorna 422. |
apenas_conflito | bool | query | não | Só lançamentos com conflito de regras (regras_conflito preenchido). Default false. |
id_exportacao | int | query | não | Só 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
usuario_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
id_cliente | int | path | sim | ID do cliente. |
page | int | query | não | Página (1-based). Ativa a paginação. |
per_page | int | query | não | Itens por página (máx. 200). |
search | str | query | não | Busca (LIKE) em histórico, nº documento ou código de histórico. |
origem | str | query | não | Filtra por origem (manual, import_ofx, ...). |
status | str | query | não | Filtra por status do lançamento. |
data_inicio | date | query | não | data_registro >= (YYYY-MM-DD). |
data_fim | date | query | não | data_registro <= (YYYY-MM-DD). |
id_importacao | int | query | não | Importação de origem (>= 1). Combina com origem por AND; id inexistente devolve lista vazia. |
id_conta_debito | int | query | não | Conta de débito (id exato). Vence conta_debito_q. |
id_conta_credito | int | query | não | Conta de crédito (id exato). Vence conta_credito_q. |
conta_debito_q | str | query | não | Busca na conta de débito: prefixo em codigo_dominio ou trecho do nome. Ignorado se id_conta_debito vier. |
conta_credito_q | str | query | não | Busca na conta de crédito: prefixo em codigo_dominio ou trecho do nome. Ignorado se id_conta_credito vier. |
valor_min | decimal | query | não | Valor mínimo em módulo (ABS(valor) >=), inclusivo, com ponto decimal. 0 é válido; negativo retorna 422. |
valor_max | decimal | query | não | Valor máximo em módulo (ABS(valor) <=), inclusivo. valor_max < valor_min retorna 400; negativo retorna 422. |
apenas_conflito | bool | query | não | Só lançamentos com conflito de regras (regras_conflito preenchido). Default false. |
sort_by | str | query | não | Coluna: data, valor, historico, origem, status, cliente (default data). |
sort_dir | str | query | não | asc 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
id_plano_contas | int | path | sim | ID do plano de contas. |
page | int | query | não | Página (1-based). Ativa a paginação. |
per_page | int | query | não | Itens por página (máx. 200). |
search | str | query | não | Busca (LIKE) em histórico, nº documento ou código de histórico. |
origem | str | query | não | Filtra por origem (manual, import_ofx, ...). |
status | str | query | não | Filtra por status do lançamento. |
data_inicio | date | query | não | data_registro >= (YYYY-MM-DD). |
data_fim | date | query | não | data_registro <= (YYYY-MM-DD). |
id_importacao | int | query | não | Importação de origem (>= 1). Combina com origem por AND; id inexistente devolve lista vazia. |
id_conta_debito | int | query | não | Conta de débito (id exato). Vence conta_debito_q. |
id_conta_credito | int | query | não | Conta de crédito (id exato). Vence conta_credito_q. |
conta_debito_q | str | query | não | Busca na conta de débito: prefixo em codigo_dominio ou trecho do nome. Ignorado se id_conta_debito vier. |
conta_credito_q | str | query | não | Busca na conta de crédito: prefixo em codigo_dominio ou trecho do nome. Ignorado se id_conta_credito vier. |
valor_min | decimal | query | não | Valor mínimo em módulo (ABS(valor) >=), inclusivo, com ponto decimal. 0 é válido; negativo retorna 422. |
valor_max | decimal | query | não | Valor máximo em módulo (ABS(valor) <=), inclusivo. valor_max < valor_min retorna 400; negativo retorna 422. |
apenas_conflito | bool | query | não | Só lançamentos com conflito de regras (regras_conflito preenchido). Default false. |
sort_by | str | query | não | Coluna: data, valor, historico, origem, status, cliente (default data). |
sort_dir | str | query | não | asc 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
inicio | date | query | sim | Data inicial (YYYY-MM-DD). |
fim | date | query | sim | Data final (YYYY-MM-DD). |
page | int | query | não | Página (1-based). Ativa a paginação. |
per_page | int | query | não | Itens por página (máx. 200). |
search | str | query | não | Busca (LIKE) em histórico, nº documento ou código de histórico. |
origem | str | query | não | Filtra por origem (manual, import_ofx, ...). |
status | str | query | não | Filtra por status do lançamento. |
id_importacao | int | query | não | Importação de origem (>= 1). Combina com origem por AND; id inexistente devolve lista vazia. |
id_conta_debito | int | query | não | Conta de débito (id exato). Vence conta_debito_q. |
id_conta_credito | int | query | não | Conta de crédito (id exato). Vence conta_credito_q. |
conta_debito_q | str | query | não | Busca na conta de débito: prefixo em codigo_dominio ou trecho do nome. Ignorado se id_conta_debito vier. |
conta_credito_q | str | query | não | Busca na conta de crédito: prefixo em codigo_dominio ou trecho do nome. Ignorado se id_conta_credito vier. |
valor_min | decimal | query | não | Valor mínimo em módulo (ABS(valor) >=), inclusivo, com ponto decimal. 0 é válido; negativo retorna 422. |
valor_max | decimal | query | não | Valor máximo em módulo (ABS(valor) <=), inclusivo. valor_max < valor_min retorna 400; negativo retorna 422. |
apenas_conflito | bool | query | não | Só lançamentos com conflito de regras (regras_conflito preenchido). Default false. |
sort_by | str | query | não | Coluna: data, valor, historico, origem, status, cliente (default data). |
sort_dir | str | query | não | asc 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
id_cliente | int | query | sim | ID do cliente. |
competencia | str | query | não | Competência MM/YYYY. Exclusivo com data_inicio/data_fim. |
data_inicio | date | query | não | Data inicial (YYYY-MM-DD), em conjunto com data_fim. |
data_fim | date | query | não | Data final (YYYY-MM-DD), em conjunto com data_inicio. |
status | str | query | não | Status 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-31Response 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
id_cliente | int | query | sim | ID do cliente. |
competencia | str | query | não | Competência MM/YYYY. Exclusivo com data_inicio/data_fim. |
data_inicio | date | query | não | Data inicial (YYYY-MM-DD), em conjunto com data_fim. |
data_fim | date | query | não | Data final (YYYY-MM-DD), em conjunto com data_inicio. |
status | str | query | não | Status 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
id_cliente | int | query | sim | ID do cliente. |
data_inicio | date | query | sim | Data inicial (YYYY-MM-DD). |
data_fim | date | query | sim | Data 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-31Response 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
id_cliente | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
id_cliente | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
id_cliente | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
id_cliente | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
id_cliente | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
id_cliente | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
id_cliente | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
lancamento_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
lancamento_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
lancamento_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
lancamento_id | int | path | sim | ID do lançamento |
Request
Sem corpo de requisição.
Response 204 No Content
(sem corpo)Escopo: lancamentos_contabil:write
Schemas
LancamentoContabilCreate
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
id_cliente | int | sim | ID do cliente ao qual o lançamento pertence. |
id_plano_contas | int | sim | ID do plano de contas que organiza o lançamento. |
id_fixo | int | não | Vincula o lançamento a um lançamento fixo. |
linha_arquivo | int | não | Linha do arquivo de origem (quando importado de TXT/CSV). |
competencia | str | sim | Formato MM/YYYY (ex.: 01/2026). 7 caracteres. |
data_registro | date | sim | Data contábil do registro (YYYY-MM-DD, sem hora). |
id_conta_debito | int | sim | ID da conta debitada (contas.id). |
id_conta_credito | int | sim | ID da conta creditada (contas.id). |
valor | str | sim | Valor 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_historico | str | sim | Código do histórico contábil padrão. Máx. 50. |
historico_contabil | str | sim | Descrição/histórico do lançamento. Máx. 500. |
numero_documento | str | não | Número do documento de origem (nota, recibo). Máx. 50. |
codigo_filial | str | não | Código da filial (espelho Fivelabs/Domínio). Máx. 50. |
lancamento_scp | str | não | Identificação SCP (espelho Fivelabs/Domínio). Máx. 50. |
campo_auxiliar_1 | str | não | Campo auxiliar 1 (espelho Fivelabs/Domínio). Máx. 300. |
campo_auxiliar_2 | str | não | Campo auxiliar 2 (espelho Fivelabs/Domínio). Máx. 300. |
campo_auxiliar_3 | str | não | Campo auxiliar 3 (espelho Fivelabs/Domínio). Máx. 300. |
status | str | não | Um de sucesso, error, regra_pendente, exportado. Default regra_pendente. |
observacao | str | não | Observaçã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.
| Campo | Tipo | Observações |
|---|---|---|
linha_arquivo | int | Linha do arquivo de origem. |
competencia | str | Formato MM/YYYY. |
data_registro | date | Data contábil do registro. |
id_plano_contas | int | > 0. Aceito apenas quando o lançamento está órfão (id_plano_contas IS NULL); trocar plano definido é bloqueado com 422. |
id_conta_debito | int | Reatribui a conta debitada. |
id_conta_credito | int | Reatribui a conta creditada. |
valor | str | Mesmas regras de validação do Create (inclusive a recusa de zero com 422). |
codigo_historico | str | Máx. 50. |
historico_contabil | str | Máx. 500. |
numero_documento | str | Máx. 50. |
codigo_filial | str | Máx. 50. |
lancamento_scp | str | Máx. 50. |
campo_auxiliar_1 | str | Máx. 300. |
campo_auxiliar_2 | str | Máx. 300. |
campo_auxiliar_3 | str | Máx. 300. |
status | str | Um de sucesso, error, regra_pendente, exportado. |
observacao | str | Observação livre. |
LancamentoContabilRead
| Campo | Tipo | Notas |
|---|---|---|
id | int | Identificador do lançamento. |
id_usuario_created | int | Usuário que criou o lançamento. |
id_cliente | int | Cliente. |
id_plano_contas | int | null | Nullable - lançamentos importados em regra_pendente ficam sem plano até a atribuição por regra. |
data_hora_criacao | datetime | Convertido para o fuso America/Sao_Paulo. |
id_fixo | int | null | Vínculo a lançamento fixo. |
linha_arquivo | int | null | Linha do arquivo de origem. |
competencia | str | MM/YYYY. |
data_registro | date | Data contábil. |
id_conta_debito | int | null | Conta debitada. |
id_conta_credito | int | null | Conta creditada. |
conta_debito | ContaResumo | null | Resumo 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_credito | ContaResumo | null | Resumo denormalizado da conta de crédito. Mesma semântica de conta_debito. |
valor | str | Valor monetário normalizado. |
codigo_historico | str | Código do histórico. |
historico_contabil | str | Descrição do lançamento. |
numero_documento | str | null | Documento de origem. |
codigo_filial | str | null | Código da filial. |
lancamento_scp | str | null | Identificação SCP. |
campo_auxiliar_1..3 | str | null | Campos auxiliares (espelho Fivelabs/Domínio). |
status | str | sucesso, error, regra_pendente ou exportado. |
observacao | str | null | Observação livre. |
origem | str | null | Origem do lançamento (default manual). |
id_importacao | int | null | Importação que originou o lançamento (quando aplicável). |
regras_aplicadas | RegraAplicadaInfo[] | Regras que classificaram o lançamento na importação, já resolvidas ({id, ordem, nome, campo_destino}). Lista vazia para lançamentos manuais/legados. |
regras_conflito | RegraAplicadaInfo[] | 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.
| Campo | Tipo | Notas |
|---|---|---|
id | int | ID da conta. |
codigo_dominio | str | Código Domínio da conta. |
nome | str | Nome da conta. |
Notas
- Toda resposta JSON segue o envelope
{ status, message, data }(ou{ "message": ... }em erro de negócio e{ "detail": [...] }em422de validação). As rotas de exportação (GET /exportar-txt,GET /exportar-csv,GET /exportar-xlsxePOST /exportar) fogem ao padrão: devolvem o arquivo como download (não o envelope), e a transacional expõeX-Exportacao-Id/X-Exportacao-Qtdnos headers. - Partidas dobradas: todo lançamento debita
id_conta_debitoe creditaid_conta_creditopelo mesmovalor. - 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 quandopage/per_pagesão informados; nesse caso odataé 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);errorfica à parte (falha de processamento). Apenasstatus='sucesso'é elegível para a exportação TXT; a exportação transacional vira os selecionados paraexportado, 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 /exportarePOST /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 umlancamento_id). - Relaciona-se com Customers (
id_cliente) e com os domínios de contas e plano de contas que fornecemid_conta_debito,id_conta_creditoeid_plano_contas.