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

# Equipe de cuidado e profissionais

> Profissional duplicado ou não encontrado, equipe criada e vazia na tela, e como identificar um profissional recebido.

Profissional e equipe de cuidado aparecem em quase todo fluxo — atendimento, condição, diretriz
aplicada — e é por isso que um profissional mal identificado quebra coisas que parecem não ter
relação com ele. Os fundamentos estão em [Profissional](/guia/recursos/practitioner) e em
[Equipe de cuidado](/guia/recursos/careteam).

## `Too many matches for Practitioner`

**Causa.** Mais de um profissional já cadastrado casa com os identificadores enviados. Isso
aparece com frequência quando o payload manda dois identificadores para deduplicar — e-mail e
conselho de classe, por exemplo — e cada um encontra um registro diferente. Também aparece
quando o mesmo profissional está duplicado na base.

**O que fazer.** Identifique o profissional por **uma** chave única. Se o erro persistir, é
duplicidade de cadastro: a unificação é feita pela Nilo, e nenhum payload contorna isso enquanto
os dois registros existirem.

## `Reference … not found` apontando para um profissional

**Causa.** O par `system` + `value` enviado não corresponde a nenhum profissional cadastrado. O
caso típico é o sistema de origem usar o próprio código interno do profissional, que a Nilo não
conhece.

**O que fazer.** Prefira o **e-mail** como identificador primário do profissional, com
`system: urn:ietf:rfc:6530`. Ele é estável, é único e não depende de configuração adicional.
Confirme antes que o profissional está cadastrado na plataforma: a referência não cria o
profissional, só aponta para ele.

> **Note**
>
> Se você precisa usar o código interno do seu sistema como identificador de profissional, ele
> funciona — mas o `system` correspondente precisa estar configurado para a unidade de cuidado
> antes do primeiro envio. `Practitioner` é, com `Patient`, um dos dois recursos em que o `system`
> passa por configuração. Veja
> [Configuração e ambientes](/guia/solucao-de-problemas/configuracao).

## O profissional não tem e-mail

**Causa.** Nem todo profissional que você precisa registrar tem e-mail: profissionais inativos e
cargas de histórico de atendimentos são o caso comum.

**O que fazer.** O e-mail **não é obrigatório** para cadastrar um profissional. Envie outro
identificador. O que muda é o acesso: um profissional sem e-mail é um registro de referência,
para aparecer em atendimentos e eventos, e não ganha acesso à plataforma.

## `qualification` recusada

**Causa.** A especialidade do profissional foi enviada como `identifier` em vez de
`code.coding`. É o erro mais comum nesse campo, e a mensagem que ele produz costuma falar de
tipo, não de especialidade.

**O que fazer.** Envie a especialidade em `qualification.code.coding`, com o `system` do catálogo
de ocupações e o código correspondente, mais o `code.text`. O formato exato está em
[Profissional](/guia/recursos/practitioner).

## A equipe é criada com `200`, mas aparece vazia na tela

Duas causas, e a segunda é sutil:

**O ambiente errado.** A requisição foi para homologação e o paciente referenciado é de produção,
ou o contrário. A equipe é criada, o paciente não é encontrado, e o resultado é uma equipe que
não se liga a ninguém. Confirme o ambiente antes de reenviar.

**O `system` do identificador da equipe divergindo do que você usa normalmente.** Aqui não há
configuração envolvida: `CareTeam` aceita qualquer `system`, então um `system` apontando para o
ambiente de desenvolvimento da origem — um host local, por exemplo — é aceito sem erro e cria uma
equipe **nova**, sob um identificador que nada mais referencia. Confira o `system` contra o que
você usa para aquela equipe nos outros envios.

## O mesmo participante repetido no payload

**Causa.** O array `participant` traz o mesmo profissional mais de uma vez. A equipe é criada,
mas o vínculo do profissional pode não se completar, porque o mesmo vínculo é tentado duas vezes.

**O que fazer.** Deduplique os participantes na origem antes de enviar. Um profissional aparece
uma vez por equipe, mesmo quando ele acumula funções.

## A equipe aparece como inativa sem eu ter encerrado nada

**Causa.** O status da equipe é derivado do **período** do vínculo, e período vazio não significa
"sem vigência":

| `period.start` | `period.end` | Como é interpretado                          |
| -------------- | ------------ | -------------------------------------------- |
| ausente        | ausente      | Vigente — iniciado desde sempre, sem término |
| definido       | ausente      | Vigente a partir de `start`                  |
| definido       | definido     | Vigente no intervalo, encerrado depois       |

**O que fazer.** Se você quer o vínculo vigente, o mais simples é omitir os dois campos. Se
envia `start`, não envie um `end` no passado sem querer encerrar o vínculo.

## Como descobrir qual profissional é o da equipe que eu recebi

**Causa.** O `CareTeam` traz o profissional apenas como **referência**, em
`participant.member.identifier`. Os dados dele — nome, especialidade, conselho — não vêm no mesmo
payload.

**O que fazer.** Faça uma segunda requisição buscando o profissional por aquele identificador:

```
GET /fhir/resources/Practitioner?identifier=<system>|<value>
```

O mesmo vale para o profissional que chega numa notificação de atendimento. Veja
[Identificadores](/guia/conceitos/identificadores) para o formato do filtro.