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-lucro

Escopos necessários

  • lancamento_lucro:read - listagens, resumo fiscal, mapa de competência, export e detalhamento
  • lancamento_lucro:write - criação, atualização, exclusão, recálculo de competência e POST /simular-fiscal (que não grava, mas é POST e por isso exige write)

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âmetroTipoLocalObrigatórioDescrição
competenciastrquerynãoFiltro por competência (MM/YYYY)
pageint >= 1querynãoPágina 1-based
per_pageint 1..500querynãoItens 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âmetroTipoLocalObrigatórioDescrição
customer_idintpathsimID do cliente
competenciastrquerynãoFiltro por competência (MM/YYYY)
statusstrquerynãoFiltro por status (ex.: Em processamento)
pageint >= 1querynãoPágina 1-based
per_pageint 1..500querynãoItens 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âmetroTipoLocalObrigatórioDescrição
data_iniciodatequerysimInício do período
data_fimdatequerysimFim do período
id_clienteintquerynãoRestringe a agregação a um cliente
id_grupointquerynãoRestringe ao grupo de carteira
meusboolquerynãoSó clientes em que o usuário logado é responsável pelo serviço Contábil
id_usuariointquerynãoSó clientes cujo serviço Contábil está sob o usuário informado
sem_responsavelboolquerynãoSó clientes ativos sem responsável pelo setor Contábil
id_qsa_clienteintquerynãoRestringe a um sócio
competenciastrquerynãoRestringe a uma competência (MM/YYYY)
statusstrquerynãoRestringe ao status do lançamento (muda a soma mensal por sócio e, com ela, o teto e o IR)
data_pagamento_iniciodatequerynãodata_pagamento >= (YYYY-MM-DD)
data_pagamento_fimdatequerynãodata_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
}
CampoTipoObrigatórioObservações
id_clienteintsimCliente, > 0.
competenciastrsimYYYY-MM ou MM/YYYY; outro formato retorna 422.
valor_liquidoDecimalsimValor líquido do lançamento em edição, >= 0.
id_qsa_clienteintnãoSócio. Omitido: sem acumulação mensal, a base é só a do próprio lançamento.
valor_ata_utilizadaDecimalnãoIsenção por ata neste lançamento, >= 0. Default 0.
excluir_idintnãoModo 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 }
CampoTipoObrigatórioObservações
id_clienteintsimCliente, > 0.
competenciastrsimYYYY-MM ou MM/YYYY; outro formato retorna 422.
id_qsa_clienteintnãoSó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âmetroTipoLocalObrigatórioDescrição
anoint 2000..2100querysimAno de referência
mesint 1..12querysimMês de referência
id_grupointquerynãoRestringe ao grupo de carteira
meusboolquerynãoSó clientes em que o usuário logado é responsável pelo serviço Contábil
id_usuariointquerynãoSó clientes cujo serviço Contábil está sob o usuário informado
sem_responsavelboolquerynãoSó 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âmetroTipoLocalObrigatórioDescrição
anoint 2000..2100querysimAno de referência
mesint 1..12querysimMês de referência
formatostrquerynãocsv (default) ou xlsx
statusstrquerynãoFiltro por status do cliente: pendentes, sem-movimento ou ok
id_grupointquerynãoRestringe ao grupo de carteira
meusboolquerynãoSó clientes em que o usuário logado é responsável pelo serviço Contábil
id_usuariointquerynãoSó clientes cujo serviço Contábil está sob o usuário informado
sem_responsavelboolquerynãoSó 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=pendentes

Response 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âmetroTipoLocalObrigatórioDescrição
lancamento_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
lancamento_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
lancamento_idintpathsimID 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.

CampoTipoObrigatórioObservações
id_clienteintsimID do cliente ao qual o lançamento pertence.
id_qsa_clienteintnãoID do sócio do quadro societário (customer_qsa.id).
competenciastrsimCompetência no formato MM/YYYY (mês 01-12, ano 4 dígitos).
data_registrodatesimData de registro do lançamento (sem hora).
data_pagamentodatenãoData de pagamento do lucro (sem hora).
valor_liquidoDecimalsimValor líquido distribuído, não-negativo. Decimal com 2 casas.
valor_brutoDecimalnãoValor bruto do rendimento (Reinf). Ausente: considera-se igual ao líquido.
valor_ir_retidoDecimalnãoIR retido na fonte, não-negativo. Default 0.
id_lancamento_contabilintnãoLançamento contábil de origem (mesmo cliente). Único por lançamento: duplicado retorna 409. Imutável.
id_ataintnãoID da ata (customer_ata.id) usada como isenção.
valor_ata_utilizadaDecimalnãoValor da ata usado como isenção (não-negativo). Default 0.
natureza_rendimentostrsimNatureza do rendimento distribuído (1-100 caracteres).
statusstrnãoEm processamento (default), processado, cancelado ou Via e-CAC (declarado manualmente no e-CAC; ignorado pela transmissão EFD-Reinf).
observacaostrnãoObservaçã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).

CampoTipoObservações
id_qsa_clienteintTroca o sócio (do mesmo cliente). Ausente: não altera; null: desvincula.
competenciastrNova competência MM/YYYY.
data_registrodateNova data de registro.
data_pagamentodateNova data de pagamento.
valor_liquidoDecimalNovo valor líquido (não-negativo).
valor_brutoDecimalNovo valor bruto (não-negativo).
valor_ir_retidoDecimalNovo IR retido (não-negativo).
id_ataintReassocia a isenção a outra ata.
valor_ata_utilizadaDecimalAjusta o valor da ata utilizado (não-negativo).
natureza_rendimentostrNova natureza do rendimento (1-100 caracteres).
statusstrEm processamento, processado, cancelado ou Via e-CAC (recusado para lançamento Transmitido ou Em retificação).
observacaostrNova 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.

CampoTipoNotas
idintID do lançamento de lucro.
nome_sociostr | nullNome 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_reinfstr | nullTipo de evento Reinf derivado do documento do sócio: R4010 (CPF), R4020 (CNPJ) ou R4040 (sem sócio ou documento inválido).
id_usuario_createdintUsuário interno que criou (auditoria). null quando criado pelo Portal.
id_portal_user_createdintUsuário do Portal (portal_user.id) que criou. null quando criado internamente.
data_hora_criacaodatetimeTimestamp de criação (server-side).

ResumoFiscalSocio

Resultado agregado da regra fiscal por (sócio, competência). Decimais são serializados como string.

CampoTipoNotas
id_qsa_clienteintID do sócio (customer_qsa.id).
nome_sociostrNome do sócio.
competenciastrCompetência MM/YYYY.
total_liquidoDecimalSoma de valor_liquido do grupo.
total_isencao_ataDecimalSoma de valor_ata_utilizada do grupo (isenção).
base_tributavelDecimaltotal_liquido − total_isencao_ata.
incide_irbooltrue quando base_tributavel > 50.000.
valor_brutoDecimalValor bruto reconstituído (base / 0,9 quando incide IR).
valor_irDecimalImposto 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.

CampoTipoNotas
anointAno de referência.
mesintMês de referência.
competenciastrCompetência MM/YYYY.
resumoMapaResumoLucroContadores/KPIs do topo da planilha.
comparativo_mes_anteriorMapaComparativoLucroComparativo com o mês anterior (null se não houver).
clientesList[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 (ok quando há ≥ 1 lançamento no mês, sem_movimento quando foi declarado que não houve movimento, pendente nos 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 como 422 com { "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-competencia e GET /mapa-competencia/export são declaradas antes da rota dinâmica GET /{lancamento_id}, para que by-user, resumo-fiscal etc. não sejam interpretados como um lancamento_id.
  • competencia sempre no formato MM/YYYY (mês 01-12, ano 4 dígitos); valor_liquido e valor_ata_utilizada são não-negativos e limitados a < 10.000.000.000.000 (decimal com 2 casas).
  • GET /mapa-competencia/export devolve um arquivo binário (CSV/XLSX), diferente dos demais endpoints que retornam o envelope JSON.