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

# Configuração e ambientes

> O que precisa ser configurado antes do primeiro envio, o que difere entre ambientes e erros de campanha e mensagem.

Parte dos erros de integração não está no payload: está no que precisa existir **antes** dele.
Identificadores, ids internos, chaves de API e configurações do care provider são definidos por
ambiente, e um envio impecável falha se algum deles não estiver no lugar. Esta página é a lista
do que conferir.

## O que tem de existir antes do primeiro envio

| Item                                                            | Quem define         | Por ambiente?                          |
| --------------------------------------------------------------- | ------------------- | -------------------------------------- |
| `system` de identificador de **paciente** e de **profissional** | Nilo, no onboarding | Sim                                    |
| Chave de API                                                    | Nilo                | Sim                                    |
| Ids de plano de saúde, grupo, status, campanha                  | Plataforma          | Sim — valores diferentes               |
| Diretrizes vigentes                                             | Plataforma          | Sim — podem não existir em homologação |
| Configurações do care provider                                  | Nilo, a pedido      | Sim                                    |

> **Note**
>
> Nada disso é declarado pelo payload. Um `system` de paciente ou profissional que você começou a
> usar, um plano que você quer testar em homologação, uma configuração de comportamento — todos
> passam por um chamado antes do primeiro envio. Vale conferir a lista inteira no começo da
> integração: descobrir um item faltando no meio de uma carga custa muito mais.

> **Note**
>
> **Só `Patient` e `Practitioner` dependem de `system` configurado.** Os demais recursos casam o
> registro existente por qualquer `system` que você enviar — você escolhe o namespace e usa, sem
> pedir nada. Não abra chamado para "configurar o name system" de cobertura, atendimento,
> diretriz aplicada ou qualquer outro recurso: não existe essa configuração para eles.

## `No identifier systems configured`

**Causa.** A mensagem vem junto com o erro de casamento de identificador de **profissional**, e
diz que nenhum `system` está configurado para aquela unidade de cuidado — nem o que você enviou,
nem nenhum outro. É diferente de "o `system` que você mandou não serve": aqui a lista está vazia.

**O que fazer.** Abra um chamado informando o **`system`** que você vai usar, a **unidade de
cuidado** e o **ambiente**. Configurações feitas em homologação não valem em produção, e
vice-versa — peça os dois de uma vez se você vai usar os dois.

## `Unable to use any of the provided identifiers` só num ambiente

**Causa.** O `system` de paciente ou de profissional foi configurado em um ambiente e não no
outro, ou foi configurado com um valor levemente diferente do que a origem envia — um segmento a
mais no caminho é o caso típico.

**O que fazer.** Compare o `system` do payload com o que foi configurado, caractere a caractere.
Alinhe o **valor exato** antes de pedir a configuração, e valide com uma escrita real depois
dela. Veja
[Identificadores e duplicidade](/guia/solucao-de-problemas/identificadores).

## `401 Unauthorized`

**Causa.** Chave de API errada para o ambiente, ausente, ou rotacionada.

**O que fazer.** Confirme que a chave é a do ambiente que você está chamando — chaves não são
compartilhadas entre ambientes. Se ela funcionava e parou, ela pode ter sido rotacionada: peça a
chave vigente ao time de suporte, por canal seguro. Se o `401` é intermitente, mande os horários
das falhas no chamado.

## `Select a valid choice`, ou campanha não encontrada

**Causa.** O id de campanha referenciado não existe naquele ambiente, ou existe mas pertence a
outro care provider.

**O que fazer.** Confirme com o suporte o id da campanha no ambiente em que você está enviando,
informando o **nome** dela. Campanhas de um care provider não são visíveis para outro, e em
homologação elas podem simplesmente não existir — nesse caso o teste precisa de um cadastro
prévio.

## `string contains invalid characters`

**Causa.** O conteúdo da mensagem contém um caractere de controle — um caractere invisível que
costuma entrar por copiar e colar de um editor ou de uma planilha.

**O que fazer.** Limpe caracteres de controle do texto antes de enviar. Eles não são visíveis no
payload, então vale higienizar o campo de forma programática em vez de inspecionar à vista.

## A mensagem de boas-vindas foi enviada e não devia — ou o contrário

**Causa.** O envio da mensagem de boas-vindas no cadastro do paciente é uma **configuração** do
care provider, e a extensão `patient-sendWelcomingMessage` decide caso a caso. Se a configuração
está ativa e você não envia a extensão, a mensagem sai.

**O que fazer.** Envie `patient-sendWelcomingMessage` explicitamente em todo cadastro, com o
valor que você quer. Se o comportamento padrão do seu care provider está errado, ele pode ser
alterado — abra um chamado. Veja [Extensões](/guia/conceitos/extensoes) e
[Paciente](/guia/recursos/patient).

## A mensagem programada não foi disparada

**Causa.** Duas causas independentes, e as duas são esperadas:

* **O paciente está inativo** — campanhas configuradas para excluir pacientes inativos não
  disparam para eles.
* **O disparo não é imediato** — ele roda num ciclo de hora em hora. Validar o resultado
  segundos depois do envio não prova nada.

**O que fazer.** Confirme o status do paciente antes de incluí-lo na campanha, e aguarde o ciclo
antes de tratar como falha. Veja
[Mensagem programada](/guia/recursos/communicationrequest).

## O erro menciona configuração duplicada ou ausente da plataforma

**Causa.** Uma configuração do care provider está duplicada ou faltando do lado da Nilo. Nada no
payload provoca ou resolve isso.

**O que fazer.** Abra um chamado com a resposta completa e o horário. Se a integração estava
funcionando e parou sem mudança do seu lado, mencione isso: uma mudança de configuração é a
primeira hipótese a checar.

## Dados que eu já enviei divergem do que eu leio de volta

**Causa.** Contagens diferentes entre a plataforma e uma leitura sua costumam vir de recortes
diferentes — período, status incluídos, recursos que existem em uma origem e não na outra — antes
de vir de perda de dado.

**O que fazer.** Antes de abrir o chamado, fixe o recorte: mesmo intervalo, mesmos status, mesmo
ambiente, e alguns identificadores concretos que você espera encontrar e não encontra. Uma
divergência com identificadores em mãos se investiga; uma divergência só de totais, não.