Lançamento Plano Saúde

Endpoints da WebApiAlcance para gerenciar lançamentos de plano de saúde - os registros mensais de valores de plano de saúde por cliente, sócio (QSA) e operadora, usados como base para dedução de IRPF e para a apuração da Reinf (aba Plano de Saúde). Cobrem criação, listagem por usuário logado, listagem por cliente, o mapa de competência agregado (visão org-wide), exportação em CSV/XLSX, detalhamento por ID, atualização parcial e exclusão.

Base path

/api/v1/lancamento-plano-saude

Escopos necessários

• lancamento_plano_saude:read - listagem por usuário, listagem por cliente, mapa de competência, exportação e detalhamento
• lancamento_plano_saude:write - criação, atualização e exclusão

O escopo é derivado da rota: o prefixo /lancamento-plano-saude vira o recurso lancamento_plano_saude (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).

Endpoints

POST /lancamento-plano-saude/

Cria um novo lançamento de plano de saúde. O id_usuario_created é derivado do usuário autenticado - não é enviado no body.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (LancamentoPlanoSaudeCreate). Campos obrigatórios: id_cliente, id_qsa_cliente, id_operadora_saude, competencia, data_registro e valor.

Request

{
  "id_cliente": 1234,
  "id_qsa_cliente": 45,
  "id_operadora_saude": 3,
  "competencia": "01/2026",
  "data_registro": "2026-01-10",
  "valor": "540.00"
}

Response 201 Created

{
  "success": true,
  "message": "Lançamento de plano de saúde criado com sucesso!",
  "data": {
    "id": 88,
    "id_cliente": 1234,
    "id_qsa_cliente": 45,
    "id_dependente": null,
    "id_operadora_saude": 3,
    "competencia": "01/2026",
    "data_registro": "2026-01-10",
    "data_pagamento": null,
    "valor": "540.00",
    "natureza_rendimento": null,
    "status": "pendente",
    "observacao": null,
    "nome_socio": "João da Silva",
    "nome_dependente": null,
    "nome_operadora": "Unimed",
    "id_usuario_created": 7,
    "data_hora_criacao": "2026-01-10T14:32:00"
  }
}

Erros de validação de negócio retornam código conforme a mensagem: 404 Not Found (registro não encontrado), 409 Conflict (duplicado), 403 Forbidden (acesso negado) ou 422 Unprocessable Entity (demais casos). Escopo: lancamento_plano_saude:write

GET /lancamento-plano-saude/by-user

Lista os lançamentos criados pelo usuário logado. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhum lançamento de plano de saúde encontrado.".

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Lançamentos recuperados com sucesso!",
  "data": [
    {
      "id": 88,
      "id_cliente": 1234,
      "id_qsa_cliente": 45,
      "id_dependente": null,
      "id_operadora_saude": 3,
      "competencia": "01/2026",
      "data_registro": "2026-01-10",
      "data_pagamento": null,
      "valor": "540.00",
      "natureza_rendimento": null,
      "status": "pendente",
      "observacao": null,
      "nome_socio": "João da Silva",
      "nome_dependente": null,
      "nome_operadora": "Unimed",
      "id_usuario_created": 7,
      "data_hora_criacao": "2026-01-10T14:32:00"
    }
  ]
}

Escopo: lancamento_plano_saude:read

GET /lancamento-plano-saude/by-customer/{customer_id}

Lista os lançamentos de um cliente específico. Lista vazia retorna 200 OK com data: [].

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Lançamentos recuperados com sucesso!",
  "data": [
    {
      "id": 88,
      "id_cliente": 1234,
      "id_qsa_cliente": 45,
      "id_dependente": null,
      "id_operadora_saude": 3,
      "competencia": "01/2026",
      "data_registro": "2026-01-10",
      "data_pagamento": null,
      "valor": "540.00",
      "natureza_rendimento": null,
      "status": "pendente",
      "observacao": null,
      "nome_socio": "João da Silva",
      "nome_dependente": null,
      "nome_operadora": "Unimed",
      "id_usuario_created": 7,
      "data_hora_criacao": "2026-01-10T14:32:00"
    }
  ]
}

Erros de validação seguem o mapeamento de status descrito no POST. Escopo: lancamento_plano_saude:read

GET /lancamento-plano-saude/mapa-competencia

Gera o mapa de competência da Reinf (aba Plano de Saúde): agrega, por competência (ano/mês), os clientes elegíveis (com sócios) junto de seus sócios, operadoras ativas, dependentes e lançamentos do mês. Visão org-wide.

Parâmetros

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": "6480.00",
      "qtd_lancamentos": 15,
      "socios_contemplados": 10,
      "socios_pendentes": 5
    },
    "comparativo_mes_anterior": {
      "valor_distribuido_delta_pct": "+12.5",
      "lancamentos_delta": 3
    },
    "clientes": [
      {
        "id_cliente": 1234,
        "nome": "Cliente Exemplo LTDA",
        "status": "ok",
        "socios": [{ "id": 45, "nome": "João da Silva" }],
        "operadoras_ativas": [{ "id": 3, "razao_social": "Operadora Saúde S.A." }],
        "dependentes": [],
        "lancamentos": [
          {
            "id": 88,
            "id_cliente": 1234,
            "id_qsa_cliente": 45,
            "id_dependente": null,
            "id_operadora_saude": 3,
            "competencia": "01/2026",
            "data_registro": "2026-01-10",
            "data_pagamento": null,
            "valor": "540.00",
            "natureza_rendimento": null,
            "status": "pendente",
            "observacao": null,
            "nome_socio": "João da Silva",
            "nome_dependente": null,
            "nome_operadora": "Unimed",
            "id_usuario_created": 7,
            "data_hora_criacao": "2026-01-10T14:32:00"
          }
        ]
      }
    ]
  }
}

Escopo: lancamento_plano_saude:read

GET /lancamento-plano-saude/mapa-competencia/export

Exporta o mapa de competência em CSV ou XLSX. Devolve o arquivo diretamente (Content-Disposition: attachment), não o envelope JSON.

Parâmetros

formato fora de csv/xlsx ou status fora de pendentes/ok retornam 422 Unprocessable Entity.

Request

Sem corpo de requisição.

Response 200 OK

GET /api/v1/lancamento-plano-saude/mapa-competencia/export?ano=2026&mes=1&formato=xlsx&status=pendentes
 
Content-Disposition: attachment; filename="mapa-competencia-plano-saude-2026-01.xlsx"
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
 
<conteúdo binário do arquivo>

Escopo: lancamento_plano_saude:read

GET /lancamento-plano-saude/{lancamento_id}

Detalha um lançamento pelo ID inteiro. Quando não encontrado, retorna 404 Not Found.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Lançamento de plano de saúde encontrado!",
  "data": {
    "id": 88,
    "id_cliente": 1234,
    "id_qsa_cliente": 45,
    "id_dependente": null,
    "id_operadora_saude": 3,
    "competencia": "01/2026",
    "data_registro": "2026-01-10",
    "data_pagamento": null,
    "valor": "540.00",
    "natureza_rendimento": null,
    "status": "pendente",
    "observacao": null,
    "nome_socio": "João da Silva",
    "nome_dependente": null,
    "nome_operadora": "Unimed",
    "id_usuario_created": 7,
    "data_hora_criacao": "2026-01-10T14:32:00"
  }
}

Escopo: lancamento_plano_saude:read

PUT /lancamento-plano-saude/{lancamento_id}

Atualiza um lançamento existente. O body é um LancamentoPlanoSaudeUpdate com campos parciais - somente o que vier preenchido é alterado. Os campos id, id_usuario_created, id_cliente e data_hora_criacao são imutáveis.

Parâmetros

Request (LancamentoPlanoSaudeUpdate - todos os campos opcionais)

{
  "valor": "620.00",
  "status": "pago",
  "data_pagamento": "2026-01-15"
}

Response 200 OK

{
  "success": true,
  "message": "Lançamento de plano de saúde atualizado!",
  "data": {
    "id": 88,
    "id_cliente": 1234,
    "id_qsa_cliente": 45,
    "id_dependente": null,
    "id_operadora_saude": 3,
    "competencia": "01/2026",
    "data_registro": "2026-01-10",
    "data_pagamento": "2026-01-15",
    "valor": "620.00",
    "natureza_rendimento": null,
    "status": "pago",
    "observacao": null,
    "nome_socio": "João da Silva",
    "nome_dependente": null,
    "nome_operadora": "Unimed",
    "id_usuario_created": 7,
    "data_hora_criacao": "2026-01-10T14:32:00"
  }
}

Escopo: lancamento_plano_saude:write

DELETE /lancamento-plano-saude/{lancamento_id}

Remove um lançamento de plano de saúde pelo ID.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Lançamento de plano de saúde removido!",
  "data": null
}

Escopo: lancamento_plano_saude:write

Schemas

LancamentoPlanoSaudeCreate

Herda todos os campos de LancamentoPlanoSaudeBase. O id_usuario_created é derivado do usuário autenticado (não enviado no body).

LancamentoPlanoSaudeUpdate

Todos os campos são opcionais; apenas os enviados são atualizados. Campos imutáveis (id, id_usuario_created, id_cliente, data_hora_criacao) não aparecem aqui.

LancamentoPlanoSaudeRead

Herda LancamentoPlanoSaudeBase e acrescenta os campos de leitura.

MapaCompetenciaPlanoSaude

Payload do mapa de competência mensal (Reinf - aba Plano de Saúde).

MapaResumoPlanoSaude: clientes_total, clientes_pendentes, clientes_ok (int), valor_distribuido (soma do mês, serializado como string com 2 casas), qtd_lancamentos, socios_contemplados, socios_pendentes (int).

MapaComparativoPlanoSaude: valor_distribuido_delta_pct (str, ex.: "+12.5"), lancamentos_delta (int).

MapaClientePlanoSaude: id_cliente (int), nome (str), status ("ok" | "pendente" - ok quando há ≥ 1 lançamento no mês), socios (List[MapaSocioItem]), operadoras_ativas (List[MapaOperadoraItem]), dependentes (List[MapaDependenteItem]) e lancamentos (List[LancamentoPlanoSaudeRead]).

Os itens auxiliares carregam apenas identificação: MapaSocioItem = { id, nome }, MapaOperadoraItem = { id, razao_social }, MapaDependenteItem = { id, nome }.

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.
• As rotas estáticas GET /by-user, GET /by-customer/{customer_id}, GET /mapa-competencia e GET /mapa-competencia/export são declaradas antes da rota dinâmica GET /{lancamento_id}, então são resolvidas corretamente (e não interpretadas como um lancamento_id).
• Valores monetários do mapa de competência (valor_distribuido) são serializados como string com 2 casas decimais.
• competencia sempre segue o formato MM/YYYY; valor não pode ser negativo e deve ser menor que 10.000.000.000.000.
• Lançamentos criados pelo Portal do Cliente têm id_usuario_created = null (a autoria é registrada por outra coluna interna, id_portal_user_created).
• GET /mapa-competencia/export devolve o arquivo binário (CSV/XLSX) com Content-Disposition: attachment, não o envelope JSON.