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

Base path

/api/v1/lancamentos-contabil

Escopos necessários

• lancamentos_contabil:read - listagens, contadores, busca por ID e exportação por leitura (GET /exportar-txt)
• lancamentos_contabil:write - criação, atualização, exclusão e exportação transacional (POST /exportar)

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

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "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 de lançamentos agrupada por status, aplicando os mesmos filtros da listagem (exceto o próprio status). Alimenta os cards da UI (Sucesso / Regra pendente / Exportados) sem carregar as linhas.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Contadores recuperados com sucesso",
  "data": {
    "sucesso": 128,
    "regra_pendente": 14,
    "exportado": 302,
    "error": 3
  }
}

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

Request

Sem corpo de requisição.

Response 200 OK

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

Request

Sem corpo de requisição.

Response 200 OK

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

Request

Sem corpo de requisição.

Response 200 OK

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

Request

Sem corpo de requisição.

Response 200 OK

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

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

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

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Reavaliação de pendentes concluída",
  "data": {
    "reavaliados": 37,
    "promovidos": 29
  }
}

reavaliados é o total de lançamentos regra_pendente analisados; promovidos é quantos passaram a ter débito e crédito e viraram sucesso. Cliente inexistente -> 404. Escopo: lancamentos_contabil:write

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

Request

Sem corpo de requisição.

Response 200 OK

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

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

Request (LancamentoContabilUpdate - todos os campos opcionais)

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

Response 200 OK

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

Parâmetros

Request

Sem corpo de requisição.

Response 204 No Content

(sem corpo)

Escopo: lancamentos_contabil:write

Schemas

LancamentoContabilCreate

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.

LancamentoContabilRead

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.

Notas

• Toda resposta JSON segue o envelope { success, message, data } (ou { success: false, message, details } em erro). As rotas de exportação (GET /exportar-txt e POST /exportar) fogem ao padrão: devolvem text/plain 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 e POST /exportar são declaradas antes da rota dinâmica GET /{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.