Identificadores e duplicidade
O identificador é a chave de tudo: é ele que decide se um POST cria ou atualiza, é por ele que
um recurso aponta para outro e é por ele que você busca. Quase todo erro de “não encontrou” ou
“encontrou demais” é um problema de identificador. Os fundamentos estão em
Identificadores e em Escritas;
esta página cobre o que dá errado na prática.
Unable to use any of the provided identifiers to match an existing resource
Este erro só acontece em Patient e Practitioner. São os dois únicos recursos que procuram
o registro existente por uma lista de system configurada na Nilo. Todos
os outros recursos casam por qualquer system que você enviar, e não dependem de
configuração nenhuma — se você vê esta mensagem em outro recurso, o payload está sem
identifier, e o caminho é preencher o campo, não abrir chamado.
Causa. Nenhum dos system enviados está na lista configurada para aquela unidade de cuidado,
naquele ambiente. Na prática, quase sempre é uma divergência sutil de string: um segmento a mais
ou a menos no caminho, uma barra final, http em vez de https.
O que fazer. Em Practitioner, a resposta traz os system aceitos junto com o erro — compare
o seu contra essa lista antes de qualquer outra hipótese. Em Patient a lista não vem na
resposta, então a comparação é contra o que foi combinado no onboarding. Nos dois casos a
comparação é literal: não há normalização de URI. Se o system estiver certo e o erro persistir,
ele provavelmente não está configurado nesse ambiente — veja
Configuração e ambientes.
Um system novo de paciente ou de profissional — de um sistema de origem que você acabou de
ligar, ou de um ambiente que você está estreando — precisa ser configurado pela Nilo antes do
primeiro envio. Não é algo que o payload declare; enquanto não estiver configurado, todo envio
de Patient ou Practitioner com ele é recusado. Valide com uma escrita real logo depois da
configuração, e não só com o payload em mãos.
A lista de system é configurada por unidade de cuidado, não pelo care provider inteiro. Um
system aceito para uma unidade pode não estar configurado em outra — o que aparece como “o
mesmo payload funciona para um paciente e falha para outro”. Para Patient, a unidade
considerada é a de managingOrganization, ou a do paciente já cadastrado quando o campo não vai
no payload.
MultipleResourcesReturned: Too many matches e returned more than one resource
Causa. Mais de um recurso já cadastrado casa com os identificadores enviados. Isso acontece por dois motivos:
- Duplicidade real na base — o mesmo profissional ou o mesmo paciente existe em dois registros, cada um carregando um dos identificadores que você mandou.
- Vários identificadores no mesmo payload apontando para registros diferentes — você envia dois ou três identificadores para deduplicar, e cada um encontra um registro distinto. A escrita não tem como escolher entre eles.
O que fazer. Envie o recurso identificado por uma chave que você sabe ser única, em vez de um conjunto de chaves. Se ainda assim o erro aparecer, é duplicidade na base: a unificação dos registros é feita pela Nilo, e nenhum ajuste de payload contorna o problema até que ela aconteça.
Reference … not found
Causa. O recurso apontado por uma referência não existe com aquele par system + value.
O erro nomeia o campo — Condition.recorder, Encounter.participant.individual,
CarePlan.subject — e é sempre sobre o recurso referenciado, não sobre o que você está
gravando.
O que fazer. Cadastre primeiro o recurso referenciado, ou envie os dois na mesma
carga em lote com referência interna. Confira também se o
system da referência é o mesmo com que aquele recurso foi cadastrado: o registro pode existir,
mas com outro identificador. Para profissionais, veja
Equipe de cuidado e profissionais.
Invalid CPF: must contain exactly 11 digits
Causa. O CPF foi enviado com máscara — pontos, hífen, espaço — ou com um número de dígitos diferente de 11.
O que fazer. Envie apenas os 11 dígitos. A validação é estrutural e acontece antes de qualquer busca, então um CPF com máscara é recusado, não gravado: ele não cria cadastro duplicado. Veja Paciente.
Paciente cadastrado duas vezes
Duplicidade de paciente vem do identificador, não dos dados: dois cadastros com nome e nascimento idênticos convivem sem conflito se os identificadores diferem, e é isso que gera o perfil repetido. Duas variações:
Dois identificadores externos para a mesma pessoa
Causa. O sistema de origem emitiu dois ids diferentes para o mesmo paciente, e os dois foram enviados ao longo do tempo. Se o CPF também vai no payload, a integração passa a tratar os dois ids como a mesma pessoa — o que embaralha o histórico em vez de resolver.
O que fazer. Garanta unicidade do id externo por paciente na origem, antes de enviar. Se um paciente já entrou com dois ids, a correção é a unificação dos registros pela Nilo — e o gerador do lado da origem precisa ser corrigido, ou o problema volta.
O mesmo CPF em pacientes diferentes
Causa. Um CPF de preenchimento ou repetido por engano na origem aparece em vários cadastros. Como o CPF é um identificador, os cadastros colidem entre si e a importação passa a falhar.
O que fazer. Não envie CPF de preenchimento. Prefira omitir o campo a enviar um valor que não é o CPF daquela pessoa: um CPF ausente é um dado que falta, um CPF errado é uma colisão que quebra outros cadastros.
O identificador já está em uso por outro registro
Causa. Você reaproveitou um identifier.value que já pertence a outro registro. O
identificador é único por recurso, e a plataforma não permite transferir um registro existente
para outro paciente ou para outro contexto — o erro varia por recurso, mas a raiz é a mesma.
O que fazer. Emita um value novo. Isso vale em particular para dois casos:
- Reinscrição em diretriz — um plano de cuidado cancelado é imutável, e o
valuedele não pode ser reusado. Veja Plano de cuidado e diretriz. - Etiquetas — uma etiqueta já vinculada a um paciente não muda de paciente. Veja Etiquetas.
O registro existe, mas não tem o meu identificador
Causa. O registro foi criado pela interface da plataforma, não pela integração. Nesse
caso ele não carrega o seu system, e a busca por identificador não o encontra. A escrita
então tenta criar um registro novo e colide com a chave de negócio daquele recurso.
O que fazer. Para cobertura de saúde existe um segundo critério de casamento que resolve o caso — veja Cobertura, grupos e status. Para os demais recursos, o caminho é buscar o registro por um campo que você conheça, conferir o identificador que ele já tem e enviar a atualização por ele.
A atualização não refletiu
Causa. Duas atualizações do mesmo registro emitidas em sequência muito rápida, com valores diferentes. Não há garantia de ordem de processamento entre requisições independentes, então o valor que fica não é necessariamente o da última que você mandou.
O que fazer. Serialize as atualizações do mesmo registro na origem — uma requisição por mudança, esperando a resposta antes da próxima. Se o valor final estiver errado, reenvie o correto: o upsert por identificador sobrescreve.