Consultar a elegibilidade

Verifica se um cartão de benefício está apto a ser usado, antes do atendimento. O recurso disponibiliza uma operação de consulta.

curl -G "https://api.clinicanasnuvens.com.br/plano-beneficio/elegibilidade" \
  -H "Authorization: Basic <CREDENCIAIS_EM_BASE64>" \
  -H "clinicaNasNuvens-cid: <TOKEN_DA_CLINICA>" \
  --data-urlencode "numeroCartao=9988776655"

Parâmetro	Obrigatório	Observação
numeroCartao	Sim	O número impresso no cartão
tipoElegibilidade	Não	Aplica-se a cartões de plano de benefício

A consulta é feita pelo número do cartão. Quando apenas o paciente é conhecido, o número do cartão é obtido em Convênios do paciente, no campo carteirinha.

Estrutura da resposta

{
  "elegivel": false,
  "nomePaciente": "João da Silva",
  "nomeConvenio": "Plano Saúde Mais",
  "validade": "2026-12-31",
  "motivosInelegibilidade": ["Carência não cumprida"]
}

A resposta contém elegivel, o nome do paciente, o nome do convênio, a validade e a lista motivosInelegibilidade. Quando o cartão está apto, essa lista é retornada vazia.

O campo motivosInelegibilidade contém textos prontos para exibição, de acordo com as regras do convênio no momento da consulta.

Resultados da consulta

Situação	Resposta
Cartão existente, mas não apto	200 com elegivel igual a false e os motivos preenchidos
Número de cartão de benefício com dígito verificador incorreto	400 com "O número da carteirinha é inválido."
Nenhum paciente com o número informado	400 com "Nenhum paciente foi encontrado com essa carteirinha."
Mais de um paciente com o número informado	400 com "Mais de um paciente foram encontrados com essa carteirinha."
Cartão de benefício de outra clínica, sem tipoElegibilidade=MATRIZ	400 com "Esse número de carteirinha não pertence à filial selecionada."
numeroCartao não informado	400 de validação da requisição

O primeiro caso é uma resposta de negócio, com os motivos de inelegibilidade; os demais indicam que o número informado não corresponde a um cartão válido para a consulta.

Etapa no fluxo de cadastro

É uma etapa opcional entre o vínculo do convênio e o agendamento:

  Vincular o convênio   →   Verificar a carteirinha   →   Agendar

Ver Cadastrar um paciente.

Veja na Referência

Os detalhes de cada operação, campo a campo, estão em Referência › Plano de benefício.