Plano de saúde

Planos novos não são criados por esta API. O catálogo é montado na implantação do seu ambiente, junto com o time da Nilo. O POST desta página encontra um plano pelo identifier e altera o nome dele; um identifier que não corresponda a nenhum plano existente não cria nada — a chamada é recusada. Para incluir um plano no catálogo, fale com o Suporte.

status não é gravável. Ativar ou desativar um plano é decisão da plataforma, e enviar status no payload não muda nada — o valor que volta continua sendo o que a plataforma calcula. Não há como aposentar um plano por esta API.

O status é informativo, e não restringe nada: um plano retired continua aparecendo na busca e continua sendo aceito em Coverage.class[0].value. Se a sua integração precisa oferecer só planos vigentes, filtre por status=active do seu lado — a plataforma não recusa o outro.

A referência lista só os campos suportados, e é assim que ela deve ser lida: o que mandar na escrita. A API em si não recusa quem manda os outros — eles ficam guardados no recurso e voltam nas leituras seguintes, sem nunca terem significado nada para a plataforma. Se o seu validador for estrito contra a referência, uma resposta assim vai parecer inválida; o remédio é não enviá-los.

Quem não quer carregar o id Nilo do plano pode usar a extensão insurance-plan da cobertura, que aceita qualquer identificador de um plano já cadastrado — inclusive o do seu próprio sistema, se ele tiver sido gravado no plano. Veja Cobertura e Extensões.

Os planos cadastrados na implantação trazem apenas o identificador Nilo. Um plano só passa a ter a sua chave se você a tiver gravado nele por integração — e como esta API não cria planos, isso só vale para os que já existiam quando você mandou o POST.

Os demais parâmetros canônicos do InsurancePlan existem e não encontram nada aqui, porque a Nilo não preenche o campo correspondente: type, owned-by, administered-by, endpoint e os de endereço. A exceção é o campo que você mesmo tenha enviado: ele fica no recurso e passa a ser encontrável — mais um motivo para omitir o que a plataforma não usa.

Um plano antigo, que ninguém tenha tocado desde que a sua integração começou, pode não aparecer na lista — e, não aparecendo, também não pode ser renomeado, porque o POST não consegue encontrá-lo. Se você espera um plano e ele não vem, peça ao Suporte: a busca não é um inventário garantido do catálogo.

Renomear muda o nome em todas as coberturas que apontam para o plano. O plano é um só, compartilhado por todos os pacientes que o usam — não há um nome por paciente. Um erro de digitação aqui aparece na ficha de todo mundo.

O identifier que localiza o plano pode ser o identificador Nilo dele ou uma chave sua que já esteja gravada no plano. Mandando uma chave nova junto com o identificador Nilo, as duas passam a valer para aquele plano — é assim que você anexa a sua própria chave a um plano do catálogo.

Diferente da busca, esta leitura não devolve um Bundle — mas também não devolve o recurso nu. A resposta é um envelope com fullUrl, search e resource, e o plano está em resource. Ler name na raiz da resposta não encontra nada.

Renomear um plano não muda nenhuma cobertura: as coberturas continuam apontando para o mesmo plano, e o Nilo Care passa a exibir o nome novo em todas elas. Nenhum paciente é afetado além do rótulo.

Na API, porém, o nome novo não alcança as coberturas já gravadas. A leitura de uma cobertura traz em class[0].name o nome que o plano tinha quando aquela cobertura foi gravada pela última vez, e renomear o plano não reescreve as coberturas. O class[0].name só acompanha o nome novo depois que a cobertura for gravada de novo, por qualquer motivo.

Para o nome atual de um plano, leia o InsurancePlan — nunca o class[0].name de uma cobertura. O class[0].value, esse sim, continua correto e é o que liga os dois.

Este endpoint nunca responde 204: não há remoção de plano por integração.

A última linha não é uma validação desta API — é a recusa da própria plataforma, repassada como está. Ela sai com code: exception, sem expression, e com uma mensagem de erro de linguagem, que inclui o endereço interno chamado. Nada disso é contrato: não tente interpretar o texto, não o exiba para o usuário final e não o registre em log de longa duração. Trate code: exception como “payload recusado, motivo não classificado” e confira antes, com um GET, se o plano que você quer alterar existe.