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. O Swagger oficial está em api.contabilidadealcance.com.br/docs.

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 e exclusão

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.

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

{
  "success": true,
  "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 não existe; 422 em falha de validação (competencia fora do formato MM/YYYY, valor_liquido negativo).

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

{
  "success": true,
  "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 (customer.id)
`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

{
  "success": true,
  "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. Visão org-wide.

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

Request

Sem corpo de requisição.

Response 200 OK

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

`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 (com sócios cadastrados) com seus sócios, atas (para isenção) e os lançamentos do mês. Visão org-wide.

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

Request

Sem corpo de requisição.

Response 200 OK

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

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. Valores inválidos de formato (fora de csv/xlsx) ou de status (fora de pendentes/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

{
  "success": true,
  "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. Os vínculos id_cliente e id_qsa_cliente são imutáveis e não podem ser reatribuídos via update.

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

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

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

{
  "success": true,
  "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 (customer.id) 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. Compatível com `Numeric(15,2)`.
`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` ou `cancelado`.
`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_qsa_cliente não aparecem aqui (imutáveis, bloqueio de mass-assignment).

Campo	Tipo	Observações
`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).
`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` ou `cancelado`.
`observacao`	`str`	Nova observação.

`LancamentoLucroRead`

Herda de LancamentoLucroBase e adiciona os campos gerenciados abaixo.

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.
`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 (ok quando há ≥ 1 lançamento no mês, pendente quando 0); 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 { success, message, data } (ou { success: false, message, details } em erro). 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, 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 (compatível com Numeric(15,2)).
GET /mapa-competencia/export devolve um arquivo binário (CSV/XLSX), diferente dos demais endpoints que retornam o envelope JSON.