Como diagnosticar
Esta seção reúne os problemas que mais aparecem em integrações reais: o sintoma como ele chega, a causa e o que fazer. Ela não substitui a página de cada recurso — quando o problema é um campo específico, o lugar certo é a tabela de campos do recurso. Serve para o caso oposto: você tem uma mensagem de erro, ou um recurso que foi aceito e não apareceu, e precisa saber por onde começar.
Cinco checagens antes de tudo
A maioria dos casos que chegam ao suporte cai em um destes cinco padrões. Vale passar por eles antes de procurar o caso específico.
1. Leia o OperationOutcome. Toda escrita recusada volta com um diagnóstico que nomeia o
campo. Numa carga em lote, a entrada que falhou volta
identificada pelo fullUrl — e quando o que falhou foi uma dependência, a mensagem diz o
fullUrl do recurso que precisa ser corrigido, não o do recurso que você estava tentando
gravar.
2. Confirme o ambiente. Os system de identificador de paciente e de profissional são
configurados por ambiente, e os
ids internos da plataforma — planos de saúde, grupos de pacientes, status, campanhas, unidades
de cuidado — não são os mesmos em homologação e em produção. Um payload que funciona em um
ambiente pode falhar no outro sem que nada esteja errado nele. Confirme também que o paciente
que você está referenciando existe no ambiente em que você está enviando.
3. Confirme que o que você referencia já existe. Referência por identificador não cria nada. Se o paciente, o profissional, o atendimento, o plano de saúde ou o grupo apontado não estiver cadastrado naquele ambiente, a escrita é recusada — e o erro fala do recurso referenciado, não do que você enviou.
4. Verifique se houve envio duplicado. Duas requisições iguais para o mesmo recurso em sequência rápida é uma das causas mais frequentes de erro: a primeira grava, e a segunda falha porque o registro já está no estado final. Antes de tratar como bug, confira se a primeira das duas foi aceita — em geral foi, e não há nada a corrigir além do reenvio.
5. Considere o tempo de propagação. Um 200 diz que a escrita foi aceita, não que ela já
está visível. Parte do que você envia passa por processamento assíncrono, algumas atribuições
rodam em lote uma vez por dia, e algumas telas leem de um cache de poucos minutos. Antes de
reenviar, confirme por um GET se o recurso está lá.
Reenviar não é perigoso — a escrita é um upsert por identificador, então o mesmo payload enviado duas vezes atualiza o mesmo registro em vez de criar dois. O que causa problema é reenviar em paralelo: dois envios simultâneos do mesmo recurso disputam o mesmo registro e um dos dois falha.
Índice de mensagens de erro
Quando abrir um chamado
Alguns problemas não se resolvem do lado do integrador, e vale saber quais desde o começo:
- Configuração de
systemde identificador de paciente e de profissional — só esses dois recursos casam por uma lista configurada, e ela é definida pela Nilo, por ambiente. Para os demais recursos você escolhe osysteme usa, sem configuração nenhuma. - Registros duplicados na base da Nilo — quando dois registros do mesmo paciente ou do mesmo profissional já existem, nenhum payload seu resolve; a unificação é feita pela Nilo.
- Ids internos que você precisa referenciar — o id de um plano de saúde, de um grupo, de um status ou de uma campanha vem da plataforma. Alguns são consultáveis pela API, outros não.
- Cadastros que faltam no ambiente de teste — se o plano, a diretriz ou a campanha que você quer testar não existe em homologação, ela precisa ser cadastrada antes do teste.
Ao abrir o chamado, mande o payload enviado, a resposta recebida com o OperationOutcome
inteiro, o ambiente e o horário aproximado do envio. Sem o payload, quase toda
investigação começa perguntando por ele.