Profissional
O Practitioner é a pessoa que presta o
cuidado, direta ou indiretamente — médico, enfermeiro, nutricionista, recepcionista. É quem
assina um atendimento, aparece como responsável na linha do tempo do paciente e compõe a
equipe de cuidado.
Este recurso é a alternativa a pedir cadastro de profissional ao Suporte: pela API você cadastra a pessoa, registra o conselho e as especialidades, vincula as unidades de cuidado em que ela atua e — se quiser — concede o acesso ao NiloCare, tudo na mesma escrita.
Escrever um Practitioner pode criar um usuário com acesso ao NiloCare e aos pacientes das
unidades de cuidado vinculadas. É o efeito colateral mais forte desta API. Antes da primeira
carga, leia Acesso ao NiloCare e
Efeitos colaterais.
Campos
A coluna No NiloCare traz o rótulo com que o dado aparece para a equipe. São rótulos, não caminhos de navegação: a tela pode ser reorganizada, o rótulo é o que permite conferir se o dado chegou onde você esperava.
1 Não é obrigatória, mas alguma unidade de cuidado sempre é aplicada: sem a extensão vale a unidade padrão da sua implantação, e se não houver unidade padrão configurada a escrita é recusada.
As URLs completas das extensões estão em Extensões — nesta página elas aparecem só pelo nome final.
Campos do Practitioner que a Nilo não usa
O Practitioner canônico tem campos que esta integração não lê nem grava: photo,
birthDate, communication e o qualification[].issuer. Ficam fora da referência de
propósito. Enviá-los não é erro — o valor é gravado no recurso FHIR e volta nas leituras
seguintes —, mas nada no NiloCare passa a exibi-los.
A extensão practitioner-user-password também não tem efeito: a senha não é definida por
esta API. O profissional recebe o convite de acesso pelo e-mail de login.
Cadastrar ou atualizar
Não há endpoint separado para criar e atualizar. O mesmo POST faz os dois, e quem decide é
o identifier: se já existir um profissional com aquele par system + value, ele é
atualizado; se não existir, é criado.
A resposta devolve o recurso como ficou gravado:
Guarde o id: é por ele que se faz a leitura direta. A resposta traz também o identificador
Nilo do profissional (…/NamingSystem/almanac-api--professional) ao lado do seu — os dois
servem para buscar, e o seu continua sendo o único que você precisa guardar.
A atualização de profissional substitui, não complementa. Assim como no Coverage e
diferente do Patient, um campo omitido não preserva o valor atual: omitir telecom
apaga o telefone, omitir gender volta o cadastro para não informado, omitir o
identificador de CPF ou de conselho desfaz o vínculo com aquele documento. Para mudar só o
telefone, reenvie o payload inteiro com o telefone novo.
A única exceção é o e-mail: omitido, o e-mail que já estava gravado é preservado.
Identificadores
Ao menos um identifier é obrigatório, e o system enviado precisa estar entre os
namespaces habilitados para a sua unidade de cuidado — é por ele que a Nilo decide entre
criar e atualizar. Enviar só identificadores de system desconhecido é recusado, em vez de
criar um profissional duplicado — é a recusa mais comum na primeira integração, e o payload
dela está em Erros.
A mensagem lista os system que estão habilitados. Habilitar um novo não é feito pela API:
abra um ticket no Suporte informando a URI do seu namespace.
Além da chave do seu sistema, três system têm significado próprio:
Estes três só servem para encontrar um profissional já cadastrado se também estiverem habilitados como namespaces de identificador da sua unidade. Não estando, eles continuam sendo gravados — CPF, conselho e e-mail entram no cadastro —, mas o casamento tem de vir de outro identificador.
Registro em conselho
O registro vai num identifier no system
{host}/fhir/resources/NamingSystem/NiloClassCouncil/, e o value reúne num só campo os
três que o NiloCare mostra separados — Conselho, UF e Número:
Por exemplo, CRM-SP-118234.
O formato tem de ter exatamente dois hifens. Um número de registro que contenha hifen
(CRM-SP-1182-34) é recusado, e o mesmo vale para um valor sem a UF (CRM-118234). Se o seu
sistema guarda o registro num campo único com hifens, normalize antes de enviar.
A recusa vem com code: invalid apontando Practitioner.identifier. Os conselhos
reconhecidos estão em Conselhos aceitos.
Acesso ao NiloCare
Quem controla o login é a extensão composta practitioner-user. Sem ela, nada acontece
com o acesso — o profissional é apenas um cadastro, e o login que ele já tivesse continua
como está.
Enviando a extensão, o que decide é practitioner-user-active:
practitioner-user-email é obrigatória quando o acesso está sendo concedido: é o e-mail
com que o profissional entra na plataforma.
Sem ela, a recusa é code: required apontando Practitioner.extension.
Na remoção o e-mail também é necessário — é por ele que o usuário é localizado:
active: false remove o acesso, não o cadastro. O profissional continua existindo, continua
aparecendo em atendimentos passados e volta a ter acesso se você reenviar a extensão com
true. Para o e-mail que não corresponde a nenhum usuário, false não é erro: nada é feito.
O e-mail pode vir na extensão, no identifier do system urn:ietf:rfc:6530, ou nos dois.
Nos dois, os valores precisam ser iguais. Basta haver um e-mail em qualquer um dos dois
lugares para o profissional passar a ser tratado como usuário da plataforma — mas conceder o
acesso exige o e-mail especificamente na extensão.
Unidades de cuidado
Cada extensão practitioner-organization vincula o profissional a uma unidade de cuidado, e
com ela ao acesso aos pacientes daquela unidade. Uma extensão por unidade:
O valueIdentifier aceita qualquer identificador de uma unidade de cuidado já cadastrada,
inclusive o do seu próprio sistema. Para descobrir as unidades disponíveis, liste-as — veja
Unidade de cuidado:
A semântica é de adição: a extensão nunca remove um vínculo. Um profissional vinculado a três unidades e reenviado com uma só continua nas três. Remover unidade de cuidado tem implicações de acesso a dados e é feito pelo Suporte, não pela API.
Sem nenhuma extensão practitioner-organization, o profissional é vinculado à unidade de
cuidado padrão da sua implantação. Não havendo unidade padrão configurada, a escrita é
recusada.
Quando o identificador enviado não resolve para nenhuma unidade cadastrada, o expression
traz Practitioner.extensions[0].valueIdentifier, com um s a
mais em extension. O índice é confiável — é a posição da extensão no seu payload —, mas o
caminho não é um FHIRPath válido. Não o use como chave de tratamento automático.
Especialidades
Cada especialidade é uma entrada de qualification, identificada pelo código CBO no
system http://www.saude.gov.br/fhir/r4/CodeSystem/BRCBO:
O CBO tem de existir no catálogo — se não existir, a recusa aponta o item e o coding
culpados em Practitioner.qualification[N].code.coding[N].code.
Para várias especialidades, use uma entrada de qualification por especialidade. Dois
códigos CBO no mesmo coding que apontam para especialidades diferentes são recusados.
Todo item precisa de um coding no system do CBO — um item só com text, ou só com o
código do catálogo Nilo que vem nas leituras, é recusado.
Para encerrar uma especialidade, reenvie-a com period.end no passado:
qualification é aditivo: as especialidades já gravadas e ausentes do payload continuam.
Só period.end remove. E period não volta na leitura — a resposta traz apenas as
especialidades vigentes, cada uma com o CBO, o código do catálogo Nilo e o nome em text.
Locais de atendimento
Endereços com use: work viram os locais de atendimento do profissional. O line é
posicional:
Diferente das especialidades e das unidades, address não é aditivo: os locais de
trabalho que estavam gravados e não vêm no payload são desvinculados do profissional. Envie
sempre a lista completa dos locais em que ele atende.
E o comportamento é instável quando o profissional já tem mais de um local gravado:
nessa situação a sincronização pode criar um local duplicado e desvincular um que devia
permanecer. Enquanto isso não estiver resolvido, prefira não enviar address em
atualizações de profissional com vários locais — trate os locais pelo Suporte.
Endereços com qualquer outro use são ignorados, sem erro. E a leitura devolve os locais com
use: work, type: both e um text já formatado. state e country voltam como estão
gravados; o text usa a sigla do estado e do país, que a Nilo guarda em campos separados
e esta escrita não deriva. Ou seja: um local criado por aqui com state: SP volta com
state: SP, e a sigla no text só aparece nos endereços que a plataforma normalizou.
Buscar
A resposta é sempre um Bundle do tipo searchset, mesmo quando há um único resultado:
Busca sem resultados não é erro: volta 200 com um Bundle cujo entry é uma lista vazia.
Trate a ausência de resultados pela lista vazia, não esperando um 404.
Parâmetros de busca suportados
Dois parâmetros canônicos do Practitioner existem e não encontram nada aqui. family e
given filtram partes do nome, e a Nilo grava o nome inteiro num único name[0].text — use
name. E email filtra telecom com system: email, mas o e-mail do profissional não fica
em telecom: fica em identifier, no system urn:ietf:rfc:6530. Para achar alguém pelo
e-mail, use identifier=urn:ietf:rfc:6530|ana.ribeiro@acmesaude.com.br.
Especialidade, unidade de cuidado e acesso ao NiloCare não são filtráveis: o FHIR R4 não
define search parameter para qualification nem para extensões no Practitioner.
A busca mais comum na prática é pelo identificador do seu próprio sistema:
Ler por ID
Diferente da busca, a leitura por ID devolve o recurso direto, sem envelope Bundle, e
responde 404 quando o id não existe.
Valores aceitos
Conselhos aceitos
O conselho do registro é a sigla do conselho de classe. O NiloCare reconhece:
A UF é a sigla de duas letras do estado que emitiu o registro.
Gênero
gender usa os quatro códigos do FHIR R4:
Qualquer outro valor, ou a ausência do campo, é gravado como não informado e volta como
unknown na leitura.
Especialidades
As especialidades não são um vocabulário fixo desta API: elas vêm do catálogo de
CBO (Classificação Brasileira de Ocupações) e do catálogo de especialidades do NiloCare,
que a implantação mantém. 225130 é Médico de Família e Comunidade, 225175 é Médico
Geneticista.
A leitura devolve, além do CBO que você enviou, o código do catálogo Nilo da especialidade e
o nome dela em text — é por esse nome que a especialidade aparece na plataforma.
Efeitos colaterais
A escrita de Practitioner faz mais do que gravar o cadastro.
Com a extensão practitioner-user e active: true, a escrita cria um usuário e concede
acesso ao NiloCare — e com ele o acesso aos pacientes de todas as unidades de cuidado
vinculadas ao profissional. Com active: false, ela remove o acesso. Nos dois casos o
efeito é imediato e não passa por aprovação.
Enviar address desvincula os locais de atendimento que não vierem no payload.
CPF e registro em conselho que ainda não existiam são criados no cadastro da Nilo, e um CPF ou registro já cadastrado é reaproveitado em vez de duplicado.
Este endpoint não remove profissionais: a escrita nunca responde 204. A remoção acontece do
lado Nilo e é propagada para o store FHIR pela sincronização, não por esta API. O mesmo vale
para o vínculo com unidade de cuidado, que a API só sabe adicionar.
Erros
Recusa é sempre 400 com um OperationOutcome: issue[].code classifica o problema,
issue[].expression aponta o campo culpado e issue[].details.text explica o motivo.
O erro que toda primeira integração encontra é o do identificador não habilitado:
Este erro só sai quando name está ausente. Um name presente mas sem nenhum item
use: official passa pela validação e grava o profissional sem nome — a escrita responde
200 e o cadastro fica vazio no lugar do nome. Confira o use antes de montar a carga.
Os dois últimos chegam da camada de execução sem serem reformulados, e por isso o code é o
genérico exception e o details.text é técnico. Trate-os pela mensagem aproximada, não pelo
texto exato — ele pode mudar.
A aba Referência traz o payload de todos estes erros: abra o endpoint de cadastro do
Profissional e troque o exemplo na resposta 400.
O que a integração não cobre
Nem a senha nem a redefinição de senha do profissional são definidas por esta API: o convite de acesso vai por e-mail. Perfil e permissões dentro do NiloCare também não — a API concede ou remove o acesso, e o que a pessoa pode fazer depois é configuração da plataforma.
A remoção de vínculo com unidade de cuidado e a remoção do cadastro do profissional passam pelo Suporte.
E a especialidade por unidade não existe aqui: qualification descreve as especialidades
da pessoa, não o que ela atende em cada unidade. O papel do profissional dentro de uma equipe
é assunto do CareTeam.