Operadora Saúde

Endpoints da WebApiAlcance para o cadastro de operadoras de plano de saúde (ex.: Unimed, Bradesco Saúde). Cobrem criação, listagem das operadoras do usuário autenticado (com filtros opcionais e paginação), detalhamento por ID, atualização parcial e exclusão. O cadastro é multi-tenant: cada operadora pertence ao usuário que a criou (id_usuario_created).

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/operadora-saude

Escopos necessários

operadora_saude:read - listagem e detalhamento
operadora_saude:write - criação, atualização e exclusão

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

Endpoints

`POST /operadora-saude/`

Cria uma nova operadora de saúde vinculada ao usuário autenticado. O campo id_usuario_created não vem no payload - é derivado do usuário logado. Único campo obrigatório é razao_social; os demais são opcionais.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (OperadoraSaudeCreate).

Request

{
  "razao_social": "Unimed Salvador",
  "cnpj": "12.345.678/0001-90",
  "registro_ans": "123456",
  "tipo_contratacao": "Coletivo empresarial",
  "tipo_cobertura": "Ambulatorial + Hospitalar",
  "abrangencia": "Nacional",
  "numero_contrato": "CT-2026-0001",
  "status": "ativo",
  "observacao": "Operadora preferencial da carteira."
}

Response 201 Created

{
  "success": true,
  "message": "Operadora de saúde criada com sucesso!",
  "data": {
    "id": 1,
    "razao_social": "Unimed Salvador",
    "cnpj": "12.345.678/0001-90",
    "registro_ans": "123456",
    "tipo_contratacao": "Coletivo empresarial",
    "tipo_cobertura": "Ambulatorial + Hospitalar",
    "abrangencia": "Nacional",
    "numero_contrato": "CT-2026-0001",
    "status": "ativo",
    "observacao": "Operadora preferencial da carteira.",
    "id_usuario_created": 42,
    "data_hora_criacao": "2026-07-03T10:15:00"
  }
}

Validações de campos (razao_social obrigatória, status inválido) retornam 422 Unprocessable Entity. Escopo: operadora_saude:write

`GET /operadora-saude/by-user`

Lista todas as operadoras do usuário autenticado, com filtros opcionais e paginação. Lista vazia é um estado válido - sempre retorna 200 OK, com data: [] e a mensagem "Nenhuma operadora de saúde encontrada.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`status`	`str`	query	não	Filtro por status do cadastro (ex.: `ativo`).
`razao_social`	`str`	query	não	Filtro por razão social (busca parcial, ex.: `Unimed`).
`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": "Operadoras de saúde recuperadas com sucesso!",
  "data": [
    {
      "id": 1,
      "razao_social": "Unimed Salvador",
      "cnpj": "12.345.678/0001-90",
      "registro_ans": "123456",
      "tipo_contratacao": "Coletivo empresarial",
      "tipo_cobertura": "Ambulatorial + Hospitalar",
      "abrangencia": "Nacional",
      "numero_contrato": "CT-2026-0001",
      "status": "ativo",
      "observacao": "Operadora preferencial da carteira.",
      "id_usuario_created": 42,
      "data_hora_criacao": "2026-07-03T10:15:00"
    }
  ]
}

Escopo: operadora_saude:read

`GET /operadora-saude/{operadora_id}`

Detalha uma operadora do usuário autenticado pelo ID inteiro. Quando não encontrada (ou pertencente a outro usuário), retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`operadora_id`	`int`	path	sim	ID interno da operadora

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Operadora de saúde encontrada!",
  "data": {
    "id": 1,
    "razao_social": "Unimed Salvador",
    "cnpj": "12.345.678/0001-90",
    "registro_ans": "123456",
    "tipo_contratacao": "Coletivo empresarial",
    "tipo_cobertura": "Ambulatorial + Hospitalar",
    "abrangencia": "Nacional",
    "numero_contrato": "CT-2026-0001",
    "status": "ativo",
    "observacao": "Operadora preferencial da carteira.",
    "id_usuario_created": 42,
    "data_hora_criacao": "2026-07-03T10:15:00"
  }
}

Escopo: operadora_saude:read

`PUT /operadora-saude/{operadora_id}`

Atualiza uma operadora existente do usuário autenticado. O body é um OperadoraSaudeUpdate com campos parciais - somente o que vier preenchido é alterado. Os campos id, id_usuario_created 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
`operadora_id`	`int`	path	sim	ID da operadora

Request (OperadoraSaudeUpdate - todos os campos opcionais)

{
  "status": "suspenso",
  "observacao": "Contrato em renegociação."
}

Response 200 OK

{
  "success": true,
  "message": "Operadora de saúde atualizada!",
  "data": {
    "id": 1,
    "razao_social": "Unimed Salvador",
    "cnpj": "12.345.678/0001-90",
    "registro_ans": "123456",
    "tipo_contratacao": "Coletivo empresarial",
    "tipo_cobertura": "Ambulatorial + Hospitalar",
    "abrangencia": "Nacional",
    "numero_contrato": "CT-2026-0001",
    "status": "suspenso",
    "observacao": "Contrato em renegociação.",
    "id_usuario_created": 42,
    "data_hora_criacao": "2026-07-03T10:15:00"
  }
}

Escopo: operadora_saude:write

`DELETE /operadora-saude/{operadora_id}`

Remove uma operadora de saúde do usuário autenticado pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`operadora_id`	`int`	path	sim	ID da operadora

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Operadora de saúde removida!",
  "data": null
}

Escopo: operadora_saude:write

Schemas

`OperadoraSaudeCreate`

Herda todos os campos de OperadoraSaudeBase. Apenas razao_social é obrigatório.

Campo	Tipo	Obrigatório	Observações
`razao_social`	`str`	sim	Razão social / nome da operadora. 1-200 caracteres.
`cnpj`	`str`	não	CNPJ da operadora. Máx. 20 caracteres (apenas comprimento é validado).
`registro_ans`	`str`	não	Registro da operadora na ANS. Máx. 50 caracteres.
`tipo_contratacao`	`str`	não	Tipo de contratação (ex.: `Coletivo empresarial`). Máx. 100.
`tipo_cobertura`	`str`	não	Tipo de cobertura (ex.: `Ambulatorial + Hospitalar`). Máx. 100.
`abrangencia`	`str`	não	Abrangência geográfica (ex.: `Nacional`). Máx. 100.
`numero_contrato`	`str`	não	Número do contrato com a operadora. Máx. 100.
`status`	`str`	não	Status do cadastro. Default `ativo`. Ver valores aceitos abaixo.
`observacao`	`str`	não	Observação livre do cadastro.

Valores aceitos em status: ativo, inativo, suspenso, cancelado.

`OperadoraSaudeUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. Os campos imutáveis (id, id_usuario_created, data_hora_criacao) não aparecem aqui - bloqueio contra mass-assignment.

Campo	Tipo	Observações
`razao_social`	`str`	1-200 caracteres.
`cnpj`	`str`	Máx. 20 caracteres.
`registro_ans`	`str`	Máx. 50 caracteres.
`tipo_contratacao`	`str`	Máx. 100 caracteres.
`tipo_cobertura`	`str`	Máx. 100 caracteres.
`abrangencia`	`str`	Máx. 100 caracteres.
`numero_contrato`	`str`	Máx. 100 caracteres.
`status`	`str`	`ativo`, `inativo`, `suspenso` ou `cancelado`.
`observacao`	`str`	Observação livre.

`OperadoraSaudeRead`

Herda OperadoraSaudeBase e adiciona os campos gerenciados (id, owner, timestamp).

Campo	Tipo	Notas
`id`	`int`	Identificador da operadora de saúde.
`razao_social`	`str`	Razão social / nome da operadora.
`cnpj`	`str`	CNPJ (pode ser `null`).
`registro_ans`	`str`	Registro na ANS (pode ser `null`).
`tipo_contratacao`	`str`	Tipo de contratação (pode ser `null`).
`tipo_cobertura`	`str`	Tipo de cobertura (pode ser `null`).
`abrangencia`	`str`	Abrangência geográfica (pode ser `null`).
`numero_contrato`	`str`	Número do contrato (pode ser `null`).
`status`	`str`	Status do cadastro (`ativo` por padrão).
`observacao`	`str`	Observação livre (pode ser `null`).
`id_usuario_created`	`int`	ID do usuário que criou (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.
A rota estática GET /operadora-saude/by-user é declarada antes da rota dinâmica GET /operadora-saude/{operadora_id}, então o FastAPI resolve by-user como rota estática (e não interpreta by-user como um operadora_id).
O cadastro é multi-tenant: GET /by-user lista apenas as operadoras do usuário autenticado, e detalhar/atualizar/excluir uma operadora de outro usuário retorna 404 Not Found.
O cnpj valida apenas o comprimento (máx. 20 caracteres), sem verificação dos dígitos - mesmo padrão do resto da API.