Local de atendimento

Enviando address, o line e o postalCode vão junto. São os dois campos sem os quais a chamada é recusada; bairro, cidade, estado e país são opcionais. Se você não tem o CEP ou o logradouro, é melhor omitir o address inteiro numa criação — mas veja o aviso sobre atualização logo abaixo.

Um address sem line não é recusado com uma mensagem de campo: cai num erro genérico (code: exception), que é a forma mais difícil de diagnosticar. Mande sempre o line.

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. Um telecom enviado assim parece o telefone do estabelecimento, e não é: o contato do estabelecimento existe no Nilo Care — Celular, E-mail, Telefone comercial, Site —, mas não é exposto nem gravável por esta API.

Isso vale para os campos de topo. Dentro de address, não: o endereço é remontado inteiro a cada leitura, e o que a Nilo não usa é descartado. Um address.period, um line[3] ou um address.use que você envie somem sem aviso.

Não pule posições encurtando a lista. Enviar ["Rua Tamandaré", "Casa 2"] grava Casa 2 como número, não como complemento.

E não há como deixar uma posição em branco: string vazia é recusada pela validação do FHIR, com code: structure apontando a posição. Endereço sem número usa a convenção S/N no lugar — ["Rua Tamandaré", "S/N", "Casa 2"].

A leitura encurta a lista. Posições sem valor são omitidas na resposta: um local sem complemento volta com line de dois itens, e um local sem número volta com dois itens em que o segundo é o complemento.

Reenviar uma resposta como ela veio pode, por isso, mover o complemento para o número. Ao reenviar um endereço lido, reconstrua as três posições a partir do que cada uma significa, não da ordem em que vieram.

O endereço enviado é conferido e completado contra uma base de endereços antes de ser gravado. O que você mandou preenchido volta como você mandou — state: SP volta SP. O que muda é o resto:

• os campos que você deixou de fora podem voltar preenchidos, completados a partir dos que você enviou — bairro, cidade, estado ou país, por exemplo;
• a capitalização é normalizada: rua tamandaré volta Rua Tamandaré.

Por isso a resposta de uma escrita raramente é idêntica ao que você mandou. Isso é esperado, e não indica erro.

Numa atualização que traga postalCode, os demais campos do endereço são recalculados a partir dele. Reenviar o endereço inteiro é o caminho seguro; reenviar só o CEP pode trocar o resto.

Omitir address numa atualização apaga o endereço já cadastrado. Ao contrário dos demais campos, o endereço não é preservado por omissão: um POST só com identifier e name sobre um local que tinha endereço deixa o estabelecimento sem endereço nenhum no Nilo Care.

Se você só quer corrigir o nome, reenvie o endereço junto — inteiro, com o line e o postalCode.

E essa remoção é invisível por aqui. O recurso FHIR guarda o último endereço gravado, então a resposta do POST e todas as leituras seguintes continuam mostrando o endereço que sumiu do cadastro. Não use o GET para confirmar que o endereço foi removido: ele não vai refletir isso.

O código CNES, esse sim, é preservado: uma atualização sem o identificador https://cnes.datasus.gov.br/ mantém o CNES que o estabelecimento já tinha. Para trocá-lo, mande o identificador novo.

O código CNES é único no ambiente. Enviar um CNES que já pertence a outro estabelecimento responde 409, e nada é gravado. É o único 409 deste recurso.

E há um segundo desfecho, pior que o 409. O CNES também serve para reconhecer o local: se a sua chave ainda não existe mas o CNES bate com um estabelecimento já cadastrado, a escrita não cria nada nem recusa — ela atualiza aquele estabelecimento, trocando o nome dele e agregando a sua chave. A chamada responde 200, e você só descobre olhando o id que voltou.

Trate o CNES como chave: não o reaproveite entre locais, e confira com um GET antes de cadastrar um estabelecimento cujo CNES você não tem certeza de que é novo.

Os demais parâmetros canônicos do Location existem e não encontram nada aqui, porque a Nilo não preenche o campo correspondente: status, operational-status, type, near, organization, partof e endpoint. 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 estabelecimento antigo, que ninguém tenha tocado desde que a sua integração começou, pode não aparecer na lista. Se você espera um local e ele não vem, peça ao Suporte: a busca não é um inventário garantido do cadastro.

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 local está em resource. Ler name ou address na raiz da resposta não encontra nada.

Não há vínculo vivo entre o evento e o local. O que o evento guarda é o nome do local no momento da gravação, copiado como texto. Renomear ou mudar o endereço de um Location depois não altera o que ficou registrado no evento.

Os dois caminhos de cadastro não se encontram. O endereço work de um profissional sempre cria um local novo — não há como apontar para um Location já cadastrado a partir do profissional. Repetir o mesmo endereço em vários profissionais gera vários locais diferentes, todos com o mesmo endereço. Se o seu ambiente cadastra locais por aqui, evite mandar address com use: work no profissional.

address.use é sempre work e address.type é sempre both. São constantes da leitura, não uma classificação do endereço — não há como registrar um endereço residencial ou postal aqui.

address.text é o endereço montado numa linha só pela plataforma, para exibição. Enviá-lo não tem efeito, e o formato dele não é contrato: monte a sua própria exibição a partir dos campos.

Atualizar sem address apaga o endereço. É o efeito de maior consequência deste recurso, e vale repetir aqui: o endereço não é preservado por omissão.

Alterar um local não altera nenhum evento já registrado: os eventos guardam o nome do local como texto, e continuam com o nome antigo.

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

As linhas exception não são validações desta API — são falhas repassadas como estão. Elas saem sem expression e com uma mensagem de erro de linguagem, que inclui o endereço interno chamado. O mesmo vale para o diagnostics do 409.

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 o line, o postalCode e o name.