> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api-docs.nilo.services/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api-docs.nilo.services/_mcp/server.

# Identificadores e duplicidade

> Erros de casamento de identificador, paciente ou profissional duplicado, e reuso indevido de identificador.

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](/guia/conceitos/identificadores) e em [Escritas](/guia/comecando/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`

> **Note**
>
> **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](/guia/solucao-de-problemas/configuracao).

> **Note**
>
> 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.

> **Note**
>
> 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](/guia/operacoes/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](/guia/solucao-de-problemas/equipe-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](/guia/recursos/patient).

## 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** — uma diretriz aplicada cancelada é imutável, e o `value` dela não
  pode ser reusado. Veja [Diretrizes](/guia/solucao-de-problemas/diretrizes).
* **Etiquetas** — uma etiqueta já vinculada a um paciente não muda de paciente. Veja
  [Etiquetas](/guia/solucao-de-problemas/atendimentos#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](/guia/solucao-de-problemas/cobertura-e-grupos). 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.