Lançamento Lucro
Endpoints da WebApiAlcance para gerenciar lançamentos de lucro - registros de distribuição de lucros por cliente e sócio. Cobrem a criação de lançamentos, listagem do usuário autenticado, listagem por cliente (com filtros de competência e status), o resumo fiscal por sócio (regra de isenção mensal de R$ 50 mil), o mapa de competência da feature Reinf (com export CSV/XLSX), além de detalhamento por ID, atualização parcial e exclusão.
Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key.
Base path
/api/v1/lancamento-lucroEscopos necessários
lancamento_lucro:read- listagens, resumo fiscal, mapa de competência, export e detalhamentolancamento_lucro:write- criação, atualização, exclusão, recálculo de competência ePOST /simular-fiscal(que não grava, mas é POST e por isso exigewrite)
O escopo é derivado da rota: o prefixo /lancamento-lucro vira o recurso lancamento_lucro (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).
Endpoints
POST /lancamento-lucro/
Cria um novo lançamento de lucro. O usuário criador (id_usuario_created) é derivado do usuário autenticado - não vem no payload.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (LancamentoLucroCreate). Campos obrigatórios: id_cliente, competencia (MM/YYYY), data_registro, valor_liquido (não-negativo) e natureza_rendimento. O sócio (id_qsa_cliente) é opcional, mas quando informado deve pertencer ao mesmo cliente. id_lancamento_contabil vincula o lucro ao lançamento contábil de origem (do mesmo cliente); cada lançamento contábil gera no máximo um lucro.
Request
{
"id_cliente": 1,
"id_qsa_cliente": 10,
"competencia": "01/2026",
"data_registro": "2026-01-15",
"data_pagamento": "2026-01-20",
"valor_liquido": "1234.56",
"id_ata": 5,
"valor_ata_utilizada": "0",
"natureza_rendimento": "Distribuição de lucros",
"status": "Em processamento",
"observacao": "Distribuição referente ao resultado do mês."
}Response 201 Created
{
"status": "success",
"message": "Lançamento de lucro criado com sucesso!",
"data": {
"id": 1,
"id_cliente": 1,
"id_qsa_cliente": 10,
"competencia": "01/2026",
"data_registro": "2026-01-15",
"data_pagamento": "2026-01-20",
"valor_liquido": "1234.56",
"id_ata": 5,
"valor_ata_utilizada": "0",
"natureza_rendimento": "Distribuição de lucros",
"status": "Em processamento",
"observacao": "Distribuição referente ao resultado do mês.",
"nome_socio": "João da Silva",
"id_usuario_created": 42,
"id_portal_user_created": null,
"data_hora_criacao": "2026-01-15T10:30:00"
}
}Erros possíveis: 404 quando o cliente ou o sócio não existe; 409 quando o lançamento contábil de origem já tem lucro; 422 em falha de validação (competencia fora do formato MM/YYYY, valor_liquido negativo) ou sócio de outro cliente.
Escopo: lancamento_lucro:write
GET /lancamento-lucro/by-user
Lista todos os lançamentos do usuário autenticado, com filtro opcional por competência e paginação. Lista vazia é um estado válido - sempre retorna 200 OK com data: [].
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
competencia | str | query | não | Filtro por competência (MM/YYYY) |
page | int >= 1 | query | não | Página 1-based |
per_page | int 1..500 | query | não | Itens por página |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Lançamentos de lucro recuperados com sucesso!",
"data": [
{
"id": 1,
"id_cliente": 1,
"id_qsa_cliente": 10,
"competencia": "01/2026",
"data_registro": "2026-01-15",
"data_pagamento": "2026-01-20",
"valor_liquido": "1234.56",
"id_ata": 5,
"valor_ata_utilizada": "0",
"natureza_rendimento": "Distribuição de lucros",
"status": "Em processamento",
"observacao": "Distribuição referente ao resultado do mês.",
"nome_socio": "João da Silva",
"id_usuario_created": 42,
"id_portal_user_created": null,
"data_hora_criacao": "2026-01-15T10:30:00"
}
]
}Sem lançamentos, retorna 200 OK com data: [] e a mensagem "Nenhum lançamento de lucro encontrado.".
Escopo: lancamento_lucro:read
GET /lancamento-lucro/by-customer/{customer_id}
Caso de uso primário do front: lista os lançamentos de um cliente, opcionalmente filtrados por competência e status, com paginação.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
customer_id | int | path | sim | ID do cliente |
competencia | str | query | não | Filtro por competência (MM/YYYY) |
status | str | query | não | Filtro por status (ex.: Em processamento) |
page | int >= 1 | query | não | Página 1-based |
per_page | int 1..500 | query | não | Itens por página |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Lançamentos de lucro recuperados com sucesso!",
"data": [
{
"id": 1,
"id_cliente": 1,
"id_qsa_cliente": 10,
"competencia": "01/2026",
"data_registro": "2026-01-15",
"data_pagamento": "2026-01-20",
"valor_liquido": "1234.56",
"id_ata": 5,
"valor_ata_utilizada": "0",
"natureza_rendimento": "Distribuição de lucros",
"status": "Em processamento",
"observacao": "Distribuição referente ao resultado do mês.",
"nome_socio": "João da Silva",
"id_usuario_created": 42,
"id_portal_user_created": null,
"data_hora_criacao": "2026-01-15T10:30:00"
}
]
}Quando não há lançamentos, retorna 200 OK com data: []. Quando o cliente não existe, retorna 404 Not Found.
Escopo: lancamento_lucro:read
GET /lancamento-lucro/resumo-fiscal
Agrega valor_liquido e valor_ata_utilizada por (sócio, competência) no período informado e aplica a regra fiscal de isenção mensal de R$ 50 mil. Sem filtros de escopo, cobre o escritório inteiro. Os filtros de escopo seguem a precedência id_grupo > sem_responsavel > id_usuario > meus. data_inicio posterior a data_fim ou janela acima de 366 dias retorna 422.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
data_inicio | date | query | sim | Início do período |
data_fim | date | query | sim | Fim do período |
id_cliente | int | query | não | Restringe a agregação a um cliente |
id_grupo | int | query | não | Restringe ao grupo de carteira |
meus | bool | query | não | Só clientes em que o usuário logado é responsável pelo serviço Contábil |
id_usuario | int | query | não | Só clientes cujo serviço Contábil está sob o usuário informado |
sem_responsavel | bool | query | não | Só clientes ativos sem responsável pelo setor Contábil |
id_qsa_cliente | int | query | não | Restringe a um sócio |
competencia | str | query | não | Restringe a uma competência (MM/YYYY) |
status | str | query | não | Restringe ao status do lançamento (muda a soma mensal por sócio e, com ela, o teto e o IR) |
data_pagamento_inicio | date | query | não | data_pagamento >= (YYYY-MM-DD) |
data_pagamento_fim | date | query | não | data_pagamento <= (YYYY-MM-DD) |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Resumo fiscal gerado com sucesso!",
"data": [
{
"id_qsa_cliente": 10,
"nome_socio": "João da Silva",
"competencia": "01/2026",
"total_liquido": "60000.00",
"total_isencao_ata": "0",
"base_tributavel": "60000.00",
"incide_ir": true,
"valor_bruto": "66666.67",
"valor_ir": "6666.67"
}
]
}Regra por grupo (id_qsa_cliente + competencia): base_tributavel = Σ(valor_liquido) - Σ(valor_ata_utilizada). Se base_tributavel > 50000, então valor_bruto = base / 0,9 e valor_ir = valor_bruto - base; caso contrário, valor_bruto = base e valor_ir = 0.
Escopo: lancamento_lucro:read
POST /lancamento-lucro/simular-fiscal
Calcula o bruto e o IR de um lançamento ainda não salvo, para o formulário exibi-los como campos derivados. Consulta pura: não grava nada. É POST para manter valor e sócio fora da query string; por isso exige o escopo lancamento_lucro:write.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo (SimulacaoFiscalRequest).
Request
{
"id_cliente": 10,
"competencia": "2026-01",
"valor_liquido": "30000.00",
"id_qsa_cliente": 10,
"valor_ata_utilizada": "0",
"excluir_id": 7
}| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
id_cliente | int | sim | Cliente, > 0. |
competencia | str | sim | YYYY-MM ou MM/YYYY; outro formato retorna 422. |
valor_liquido | Decimal | sim | Valor líquido do lançamento em edição, >= 0. |
id_qsa_cliente | int | não | Sócio. Omitido: sem acumulação mensal, a base é só a do próprio lançamento. |
valor_ata_utilizada | Decimal | não | Isenção por ata neste lançamento, >= 0. Default 0. |
excluir_id | int | não | Modo edição: id do lançamento editado, para não contá-lo duas vezes. |
Response 200 OK
{
"status": "success",
"message": "Simulação fiscal gerada com sucesso!",
"data": {
"base_mensal_outros": "30000.00",
"base_tributavel": "60000.00",
"incide_ir": true,
"motivo_isencao": null,
"valor_bruto": "33333.33",
"valor_ir_retido": "3333.33",
"valor_bruto_mensal": "66666.67",
"valor_ir_mensal": "6666.67"
}
}Valores monetários vêm como string com 2 casas. valor_bruto e valor_ir_retido são do lançamento simulado; valor_bruto_mensal e valor_ir_mensal são do mês inteiro do sócio e servem só de contexto. motivo_isencao é pessoa_juridica ou abaixo_do_limite quando não incide IR (null caso contrário). Cliente ou sócio inexistente -> 404; competência malformada ou sócio de outro cliente -> 422.
Escopo: lancamento_lucro:write
POST /lancamento-lucro/recalcular-competencia
Grava. Reescreve valor_bruto e valor_ir_retido dos lançamentos do cliente na competência (todos os sócios, ou só o informado) para o que a regra fiscal exige hoje, e devolve o relatório. Idempotente.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo (RecalculoCompetenciaRequest).
Request
{ "id_cliente": 10, "competencia": "05/2026", "id_qsa_cliente": 5 }| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
id_cliente | int | sim | Cliente, > 0. |
competencia | str | sim | YYYY-MM ou MM/YYYY; outro formato retorna 422. |
id_qsa_cliente | int | não | Sócio. Omitido: todos os sócios do cliente na competência. |
Response 200 OK
{
"status": "success",
"message": "Competência recalculada com sucesso!",
"data": {
"competencia": "05/2026",
"total": 3,
"atualizados": [
{ "id": 11, "valor_bruto_anterior": "30000.00", "valor_ir_retido_anterior": "0.00", "valor_bruto": "33333.33", "valor_ir_retido": "3333.33" }
],
"inalterados": [12],
"pulados": [
{
"id": 13,
"motivo": "Lançamento já transmitido",
"status": "Transmitido",
"valor_bruto": "30000.00",
"valor_ir_retido": "0.00",
"valor_bruto_esperado": "33333.33",
"valor_ir_retido_esperado": "3333.33",
"divergente": true
}
]
}
}total é a soma de atualizados, inalterados e pulados. Não são reescritos os lançamentos Transmitido, Em retificação, Via e-CAC, cancelado, sem sócio ou com natureza diferente de 12001; pulados[].divergente = true indica um lançamento já declarado que a competência deixou de sustentar (exige retificação). Valores monetários vêm como string com 2 casas. Cliente ou sócio inexistente -> 404; competência malformada ou sócio de outro cliente -> 422.
Escopo: lancamento_lucro:write
GET /lancamento-lucro/mapa-competencia
Mapa de competência da feature Reinf (aba Lucro). Agrega, por competência (ano/mês), os clientes elegíveis (ativos e matriz pessoa jurídica; ter sócio cadastrado não é exigido) com seus sócios, atas (para isenção) e os lançamentos do mês. Sem filtros de escopo, cobre o escritório inteiro.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
ano | int 2000..2100 | query | sim | Ano de referência |
mes | int 1..12 | query | sim | Mês de referência |
id_grupo | int | query | não | Restringe ao grupo de carteira |
meus | bool | query | não | Só clientes em que o usuário logado é responsável pelo serviço Contábil |
id_usuario | int | query | não | Só clientes cujo serviço Contábil está sob o usuário informado |
sem_responsavel | bool | query | não | Só clientes ativos sem responsável pelo setor Contábil |
Precedência dos filtros de escopo: id_grupo > sem_responsavel > id_usuario > meus.
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Mapa de competência gerado com sucesso!",
"data": {
"ano": 2026,
"mes": 1,
"competencia": "01/2026",
"resumo": {
"clientes_total": 12,
"clientes_pendentes": 4,
"clientes_ok": 8,
"valor_distribuido": "180000.00",
"qtd_lancamentos": 15,
"socios_contemplados": 10,
"socios_pendentes": 3
},
"comparativo_mes_anterior": {
"valor_distribuido_delta_pct": "+12.5",
"lancamentos_delta": 2
},
"clientes": [
{
"id_cliente": 1,
"nome": "Empresa Exemplo LTDA",
"status": "ok",
"socios": [{ "id": 10, "nome": "João da Silva" }],
"atas": [{ "id": 5, "descricao": "Ata 01/2026", "saldo": "0.00" }],
"lancamentos": [
{
"id": 1,
"id_cliente": 1,
"id_qsa_cliente": 10,
"competencia": "01/2026",
"data_registro": "2026-01-15",
"data_pagamento": "2026-01-20",
"valor_liquido": "1234.56",
"id_ata": 5,
"valor_ata_utilizada": "0",
"natureza_rendimento": "Distribuição de lucros",
"status": "Em processamento",
"observacao": "Distribuição referente ao resultado do mês.",
"nome_socio": "João da Silva",
"id_usuario_created": 42,
"id_portal_user_created": null,
"data_hora_criacao": "2026-01-15T10:30:00"
}
]
}
]
}
}Escopo: lancamento_lucro:read
GET /lancamento-lucro/mapa-competencia/export
Exporta o mapa de competência de lucro como arquivo (CSV ou XLSX). A resposta é binária (Content-Disposition: attachment), não o envelope JSON.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
ano | int 2000..2100 | query | sim | Ano de referência |
mes | int 1..12 | query | sim | Mês de referência |
formato | str | query | não | csv (default) ou xlsx |
status | str | query | não | Filtro por status do cliente: pendentes, sem-movimento ou ok |
id_grupo | int | query | não | Restringe ao grupo de carteira |
meus | bool | query | não | Só clientes em que o usuário logado é responsável pelo serviço Contábil |
id_usuario | int | query | não | Só clientes cujo serviço Contábil está sob o usuário informado |
sem_responsavel | bool | query | não | Só clientes ativos sem responsável pelo setor Contábil |
Request
Sem corpo de requisição.
GET /api/v1/lancamento-lucro/mapa-competencia/export?ano=2026&mes=1&formato=xlsx&status=pendentesResponse 200 OK
Arquivo binário (CSV ou XLSX) com Content-Disposition: attachment, não o envelope JSON, com o mesmo recorte de escopo do mapa. Valores inválidos de formato (fora de csv/xlsx) ou de status (fora de pendentes/sem-movimento/ok) retornam 422 Unprocessable Entity.
Escopo: lancamento_lucro:read
GET /lancamento-lucro/{lancamento_id}
Detalha um lançamento pelo ID inteiro.
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 de lucro encontrado!",
"data": {
"id": 1,
"id_cliente": 1,
"id_qsa_cliente": 10,
"competencia": "01/2026",
"data_registro": "2026-01-15",
"data_pagamento": "2026-01-20",
"valor_liquido": "1234.56",
"id_ata": 5,
"valor_ata_utilizada": "0",
"natureza_rendimento": "Distribuição de lucros",
"status": "Em processamento",
"observacao": "Distribuição referente ao resultado do mês.",
"nome_socio": "João da Silva",
"id_usuario_created": 42,
"id_portal_user_created": null,
"data_hora_criacao": "2026-01-15T10:30:00"
}
}Quando não encontrado, retorna 404 Not Found.
Escopo: lancamento_lucro:read
PUT /lancamento-lucro/{lancamento_id}
Atualiza um lançamento existente. O body é um LancamentoLucroUpdate com campos parciais - somente o que vier preenchido é alterado. id_cliente e id_lancamento_contabil são imutáveis. id_qsa_cliente pode ser trocado (o sócio deve ser do mesmo cliente; null desvincula) e o lançamento Transmitido não aceita alterações.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
lancamento_id | int | path | sim | ID do lançamento |
Request (LancamentoLucroUpdate - todos os campos opcionais)
{
"valor_liquido": "1500.00",
"status": "processado",
"observacao": "Valor ajustado após conferência."
}Response 200 OK
{
"status": "success",
"message": "Lançamento de lucro atualizado!",
"data": {
"id": 1,
"id_cliente": 1,
"id_qsa_cliente": 10,
"competencia": "01/2026",
"data_registro": "2026-01-15",
"data_pagamento": "2026-01-20",
"valor_liquido": "1500.00",
"id_ata": 5,
"valor_ata_utilizada": "0",
"natureza_rendimento": "Distribuição de lucros",
"status": "processado",
"observacao": "Valor ajustado após conferência.",
"nome_socio": "João da Silva",
"id_usuario_created": 42,
"id_portal_user_created": null,
"data_hora_criacao": "2026-01-15T10:30:00"
}
}Quando não encontrado, retorna 404 Not Found; lançamento Transmitido retorna 409 Conflict; sócio de outro cliente retorna 422.
Escopo: lancamento_lucro:write
DELETE /lancamento-lucro/{lancamento_id}
Remove um lançamento de lucro pelo ID.
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 200 OK
{
"status": "success",
"message": "Lançamento de lucro removido!",
"data": null
}Quando não encontrado, retorna 404 Not Found.
Escopo: lancamento_lucro:write
Schemas
LancamentoLucroCreate
Herda de LancamentoLucroBase.
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
id_cliente | int | sim | ID do cliente ao qual o lançamento pertence. |
id_qsa_cliente | int | não | ID do sócio do quadro societário (customer_qsa.id). |
competencia | str | sim | Competência no formato MM/YYYY (mês 01-12, ano 4 dígitos). |
data_registro | date | sim | Data de registro do lançamento (sem hora). |
data_pagamento | date | não | Data de pagamento do lucro (sem hora). |
valor_liquido | Decimal | sim | Valor líquido distribuído, não-negativo. Decimal com 2 casas. |
valor_bruto | Decimal | não | Valor bruto do rendimento (Reinf). Ausente: considera-se igual ao líquido. |
valor_ir_retido | Decimal | não | IR retido na fonte, não-negativo. Default 0. |
id_lancamento_contabil | int | não | Lançamento contábil de origem (mesmo cliente). Único por lançamento: duplicado retorna 409. Imutável. |
id_ata | int | não | ID da ata (customer_ata.id) usada como isenção. |
valor_ata_utilizada | Decimal | não | Valor da ata usado como isenção (não-negativo). Default 0. |
natureza_rendimento | str | sim | Natureza do rendimento distribuído (1-100 caracteres). |
status | str | não | Em processamento (default), processado, cancelado ou Via e-CAC (declarado manualmente no e-CAC; ignorado pela transmissão EFD-Reinf). |
observacao | str | não | Observação livre do lançamento. |
LancamentoLucroUpdate
Todos os campos são opcionais; apenas os enviados são atualizados. id_cliente e id_lancamento_contabil não aparecem aqui (imutáveis).
| Campo | Tipo | Observações |
|---|---|---|
id_qsa_cliente | int | Troca o sócio (do mesmo cliente). Ausente: não altera; null: desvincula. |
competencia | str | Nova competência MM/YYYY. |
data_registro | date | Nova data de registro. |
data_pagamento | date | Nova data de pagamento. |
valor_liquido | Decimal | Novo valor líquido (não-negativo). |
valor_bruto | Decimal | Novo valor bruto (não-negativo). |
valor_ir_retido | Decimal | Novo IR retido (não-negativo). |
id_ata | int | Reassocia a isenção a outra ata. |
valor_ata_utilizada | Decimal | Ajusta o valor da ata utilizado (não-negativo). |
natureza_rendimento | str | Nova natureza do rendimento (1-100 caracteres). |
status | str | Em processamento, processado, cancelado ou Via e-CAC (recusado para lançamento Transmitido ou Em retificação). |
observacao | str | Nova observação. |
LancamentoLucroRead
Herda de LancamentoLucroBase e adiciona os campos gerenciados abaixo. O status pode trazer ainda Transmitido e Em retificação, gerenciados pelo sistema.
| Campo | Tipo | Notas |
|---|---|---|
id | int | ID do lançamento de lucro. |
nome_socio | str | null | Nome do sócio (customer_qsa.nome) denormalizado de id_qsa_cliente, resolvido em lote no service. null quando não há sócio vinculado ou o sócio foi removido. |
tipo_evento_reinf | str | null | Tipo de evento Reinf derivado do documento do sócio: R4010 (CPF), R4020 (CNPJ) ou R4040 (sem sócio ou documento inválido). |
id_usuario_created | int | Usuário interno que criou (auditoria). null quando criado pelo Portal. |
id_portal_user_created | int | Usuário do Portal (portal_user.id) que criou. null quando criado internamente. |
data_hora_criacao | datetime | Timestamp de criação (server-side). |
ResumoFiscalSocio
Resultado agregado da regra fiscal por (sócio, competência). Decimais são serializados como string.
| Campo | Tipo | Notas |
|---|---|---|
id_qsa_cliente | int | ID do sócio (customer_qsa.id). |
nome_socio | str | Nome do sócio. |
competencia | str | Competência MM/YYYY. |
total_liquido | Decimal | Soma de valor_liquido do grupo. |
total_isencao_ata | Decimal | Soma de valor_ata_utilizada do grupo (isenção). |
base_tributavel | Decimal | total_liquido − total_isencao_ata. |
incide_ir | bool | true quando base_tributavel > 50.000. |
valor_bruto | Decimal | Valor bruto reconstituído (base / 0,9 quando incide IR). |
valor_ir | Decimal | Imposto de renda (valor_bruto − base_tributavel). |
MapaCompetenciaLucro
Payload completo da planilha de competência (aba Lucro). Valores monetários são serializados como string com 2 casas.
| Campo | Tipo | Notas |
|---|---|---|
ano | int | Ano de referência. |
mes | int | Mês de referência. |
competencia | str | Competência MM/YYYY. |
resumo | MapaResumoLucro | Contadores/KPIs do topo da planilha. |
comparativo_mes_anterior | MapaComparativoLucro | Comparativo com o mês anterior (null se não houver). |
clientes | List[MapaClienteLucro] | Clientes elegíveis com sócios, atas e lançamentos. |
Estruturas aninhadas:
MapaResumoLucro-clientes_total,clientes_pendentes,clientes_ok(int);valor_distribuido(string, 2 casas);qtd_lancamentos,socios_contemplados,socios_pendentes(int).MapaComparativoLucro-valor_distribuido_delta_pct(string, ex.:"+12.5");lancamentos_delta(int).MapaClienteLucro-id_cliente,nome;status(okquando há ≥ 1 lançamento no mês,sem_movimentoquando foi declarado que não houve movimento,pendentenos demais casos);socios(List[MapaSocioItem]);atas(List[MapaAtaItem]);lancamentos(List[LancamentoLucroRead]).MapaSocioItem-id,nome.MapaAtaItem-id,descricao,saldo(string, 2 casas).
Notas
- Toda resposta segue o envelope
{ status, message, data }(erros de negócio vêm como{ "message": ... }e a validação de entrada como422com{ "detail": [...] }). Códigos HTTP refletem semântica REST padrão. - Ordem de rotas (FastAPI). As rotas estáticas
GET /by-user,GET /by-customer/{customer_id},GET /resumo-fiscal,POST /simular-fiscal,POST /recalcular-competencia,GET /mapa-competenciaeGET /mapa-competencia/exportsão declaradas antes da rota dinâmicaGET /{lancamento_id}, para queby-user,resumo-fiscaletc. não sejam interpretados como umlancamento_id. competenciasempre no formatoMM/YYYY(mês 01-12, ano 4 dígitos);valor_liquidoevalor_ata_utilizadasão não-negativos e limitados a< 10.000.000.000.000(decimal com 2 casas).GET /mapa-competencia/exportdevolve um arquivo binário (CSV/XLSX), diferente dos demais endpoints que retornam o envelope JSON.