Customer Plano Saúde

Endpoints da WebApiAlcance para gerenciar o vínculo do cliente a planos de saúde - cada registro associa um cliente (id_cliente) a, opcionalmente, uma operadora cadastrada em operadora_saude (id_operadora_saude), com datas de contrato e status de ciclo de vida. Cobrem criação, listagem dos planos do usuário autenticado, listagem por cliente, detalhamento por ID, atualização 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/customer-plano-saude

Escopos necessários

customer_plano_saude:read - listagem por usuário, listagem por cliente e detalhamento
customer_plano_saude:write - criação, atualização e exclusão

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

Endpoints

`POST /customer-plano-saude/`

Cria um novo plano de saúde vinculado a um cliente. O campo 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 (CustomerPlanoSaudeCreate): id_cliente (obrigatório), id_operadora_saude, inicio_contrato, fim_contrato (opcionais) e status (opcional, default "ativo").

Request

{
  "id_cliente": 1,
  "id_operadora_saude": 10,
  "inicio_contrato": "2026-01-01",
  "fim_contrato": "2026-12-31",
  "status": "ativo"
}

Response 201 Created

{
  "success": true,
  "message": "Plano de saúde criado com sucesso!",
  "data": {
    "id": 1,
    "id_cliente": 1,
    "id_operadora_saude": 10,
    "inicio_contrato": "2026-01-01",
    "fim_contrato": "2026-12-31",
    "status": "ativo",
    "id_usuario_created": 42,
    "data_hora_criacao": "2026-01-01T09:00:00"
  }
}

Cliente inexistente ou operadora que não pertence ao usuário retornam 404 Not Found; validações de negócio (ex.: status inválido) retornam 422 Unprocessable Entity. Escopo: customer_plano_saude:write

`GET /customer-plano-saude/by-user`

Lista todos os planos de saúde do usuário autenticado, com filtros opcionais. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhum plano de saúde encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`status`	`str`	query	não	Filtro por status do vínculo (ex.: `ativo`).
`page`	`int`	query	não	Página (1-based, `>= 1`).
`per_page`	`int`	query	não	Itens por página (`1` a `500`).

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Planos de saúde recuperados com sucesso!",
  "data": [
    {
      "id": 1,
      "id_cliente": 1,
      "id_operadora_saude": 10,
      "inicio_contrato": "2026-01-01",
      "fim_contrato": "2026-12-31",
      "status": "ativo",
      "id_usuario_created": 42,
      "data_hora_criacao": "2026-01-01T09:00:00"
    }
  ]
}

Escopo: customer_plano_saude:read

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

Lista os planos de saúde de um cliente específico, opcionalmente filtrados por status. É o caso de uso primário do front.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`customer_id`	`int`	path	sim	ID do cliente (`customer.id`).
`status`	`str`	query	não	Filtro por status do vínculo (ex.: `ativo`).
`page`	`int`	query	não	Página (1-based, `>= 1`).
`per_page`	`int`	query	não	Itens por página (`1` a `500`).

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Planos de saúde recuperados com sucesso!",
  "data": [
    {
      "id": 1,
      "id_cliente": 1,
      "id_operadora_saude": 10,
      "inicio_contrato": "2026-01-01",
      "fim_contrato": "2026-12-31",
      "status": "ativo",
      "id_usuario_created": 42,
      "data_hora_criacao": "2026-01-01T09:00:00"
    }
  ]
}

Quando o cliente não é encontrado, retorna 404 Not Found; acesso negado retorna 403 Forbidden. Escopo: customer_plano_saude:read

`GET /customer-plano-saude/{plano_id}`

Detalha um plano de saúde pelo ID inteiro. Quando não encontrado, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`plano_id`	`int`	path	sim	ID interno do plano.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Plano de saúde encontrado!",
  "data": {
    "id": 1,
    "id_cliente": 1,
    "id_operadora_saude": 10,
    "inicio_contrato": "2026-01-01",
    "fim_contrato": "2026-12-31",
    "status": "ativo",
    "id_usuario_created": 42,
    "data_hora_criacao": "2026-01-01T09:00:00"
  }
}

Escopo: customer_plano_saude:read

`PUT /customer-plano-saude/{plano_id}`

Atualiza um plano existente. O body é um CustomerPlanoSaudeUpdate 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 e não aparecem no schema (proteção contra mass-assignment).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`plano_id`	`int`	path	sim	ID do plano.

Request (CustomerPlanoSaudeUpdate - todos os campos opcionais)

{
  "id_operadora_saude": 12,
  "status": "suspenso"
}

Response 200 OK

{
  "success": true,
  "message": "Plano de saúde atualizado!",
  "data": {
    "id": 1,
    "id_cliente": 1,
    "id_operadora_saude": 12,
    "inicio_contrato": "2026-01-01",
    "fim_contrato": "2026-12-31",
    "status": "suspenso",
    "id_usuario_created": 42,
    "data_hora_criacao": "2026-01-01T09:00:00"
  }
}

Escopo: customer_plano_saude:write

`DELETE /customer-plano-saude/{plano_id}`

Remove um plano de saúde pelo ID. Quando não encontrado, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`plano_id`	`int`	path	sim	ID do plano.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Plano de saúde removido!",
  "data": null
}

Escopo: customer_plano_saude:write

Schemas

`CustomerPlanoSaudeCreate`

Campo	Tipo	Obrigatório	Observações
`id_cliente`	`int`	sim	ID do cliente (`customer.id`) ao qual o plano pertence.
`id_operadora_saude`	`int`	não	ID da operadora de saúde (`operadora_saude.id`). Default `null`.
`inicio_contrato`	`date`	não	Data de início do contrato (sem hora). Default `null`.
`fim_contrato`	`date`	não	Data de fim do contrato (sem hora). Default `null`.
`status`	`str`	não	Status do vínculo. Default `"ativo"`. Valores aceitos abaixo.

id_usuario_created é derivado do usuário autenticado e não faz parte do payload.

`CustomerPlanoSaudeUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. id, id_usuario_created, id_cliente e data_hora_criacao são imutáveis.

Campo	Tipo	Observações
`id_operadora_saude`	`int`	Re-vincula a operadora (revalidado por ownership no service).
`inicio_contrato`	`date`	Nova data de início.
`fim_contrato`	`date`	Nova data de fim.
`status`	`str`	Novo status do vínculo. Valores aceitos abaixo.

`CustomerPlanoSaudeRead`

Campo	Tipo	Notas
`id`	`int`	Identificador do plano de saúde do cliente.
`id_cliente`	`int`	Cliente vinculado.
`id_operadora_saude`	`int`	Operadora vinculada (pode ser `null`).
`inicio_contrato`	`date`	Data de início do contrato (pode ser `null`).
`fim_contrato`	`date`	Data de fim do contrato (pode ser `null`).
`status`	`str`	Status do vínculo.
`id_usuario_created`	`int`	Usuário que criou o registro (multi-tenant).
`data_hora_criacao`	`datetime`	Timestamp de criação (server-side).

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.
O campo status aceita apenas os valores literais ativo, inativo, suspenso e cancelado; o default (na criação) é ativo.
As rotas estáticas GET /by-user e GET /by-customer/{customer_id} são declaradas antes da rota dinâmica GET /{plano_id}, garantindo que o FastAPI não interprete by-user ou by-customer como um plano_id.
Relaciona-se com Customers, que fornece o id_cliente referenciado no vínculo.