Pular para o conteúdo principal

Cadastrar/atualizar

EndpointPOST /fhir/resources/Patient
Autenticação🔓 Chave de API
StatusImplementado

Modelagem da API - Request​

OpçãoTipoRequeridoDescriçãoExemplo
x-api-keystringSimChave de autenticação do cliente, fornecida durante a configuração do ambiente.
Content-TypestringSimapplication/json

Comportamento geral​

Esta seção reúne as regras que se aplicam a qualquer criação ou atualização de paciente. As regras específicas de cada cenário (extensões obrigatórias, grupos, status) estão junto do respectivo exemplo em Exemplos de uso. Para o modelo de dados (campos, extensões e valores aceitos), consulte a página Pacientes.

Identificadores e upsert​

cuidado

O envio de um registro de paciente com um mesmo identificador principal de um registro já existente na base provoca uma alteração ao invés de um novo cadastro.

CPF

Ao enviar o CPF (identificador com system https://servicos.receita.fazenda.gov.br/servicos/cpf/):

  • O valor deve conter exatamente 11 dígitos, sem pontos, traços ou outros caracteres. Caso contrário, o sistema retorna um erro structure com a mensagem Invalid CPF: must contain exactly 11 digits with no dots, commas or other characters.
  • Para atualizar o CPF de um paciente já existente, o identificador deve ser enviado com use: "official". Um CPF com outro use é ignorado quando o paciente já possui um CPF cadastrado.

Campos de data​

O FHIR trabalha com atributos de data de uma maneira mais flexível que o NiloCare, permitindo datas parciais, nesse caso complementamos a data ao inseri-la no sistema. Exemplo: se recebermos uma data 2022-12 via API, assumiremos para o sistema 2022-12-01

Telefone e WhatsApp​

O telefone do paciente é obtido dos contatos em telecom com system='phone'. O número é validado quanto à elegibilidade no WhatsApp antes de ser gravado.

  • Se o número não for válido, a requisição falha com um erro invalid e a mensagem Invalid phone number: <número>.
  • A exceção são contatos com use igual a old ou temp: nesses casos, um número inválido é ignorado silenciosamente (não bloqueia o cadastro).
  • Quando há mais de um contato phone, o sistema prioriza aquele cujo use corresponde à tag de telefone verificado configurada para o cliente. Contatos com use='old' são descartados quando já existe outro número.
cuidado

Como a validação de WhatsApp pode rejeitar o cadastro inteiro, garanta que o número principal (use='mobile') seja um número de celular válido e com WhatsApp ativo.

Sexo​

O campo gender aceita apenas os valores male e female, que são preservados como enviados. Qualquer outro valor (incluindo other e unknown) é armazenado como other. Para representar a identidade de gênero de forma detalhada, utilize a extensão de Identidade de gênero.

Valores padrão​

Os seguintes atributos possuem uma configuração padrão customizada, e esses valores configurados serão assumidos caso não sejam enviados explicitamente na requisição.

  • Perfil Padrão de Cadastro de Paciente;
  • Envio de mensagem de boas-vindas;
  • Liberação para Primeiro Agendamento;
  • Grupo de Pacientes (Cohort);
  • ⁠Unidade de cuidado;
  • Status do Paciente;

As extensões de flag (patient-isLead, patient-sendWelcomingMessage, patient-createOnboardingScheduling) são obrigatórias, mas assumem o valor padrão configurado para o cliente quando não enviadas. Se não houver valor enviado nem padrão configurado, o cadastro falha — os erros de cada uma estão no exemplo correspondente em Exemplos de uso.

Unidade de cuidado​

O Patient referencia a unidade de cuidado pelo campo managingOrganization. O envio não é obrigatório: quando não informado, o sistema atribui a unidade de cuidado padrão configurada para o cliente. Consulte a estrutura do campo em Pacientes.

Atenção

Caso nenhuma unidade de cuidado padrão esteja configurada, a criação do paciente falhará.

Exemplo de erro:​
{
  "issue": [
    {
      "code": "not-found",
      "details": {
        "text": "A default care unit isn't configured for the care provider."
      },
      "expression": [
        "Patient.?"
      ],
      "severity": "error"
    }
  ],
  "resourceType": "OperationOutcome"
}

Exemplos de uso​

Criação de Pacientes​

Cadastro básico​

Cadastro básico de paciente, somente com nome, telefone. Como o atributo active não foi especificado, o sistema assumirá que esse paciente está ativo ("active": true) como valor padrão.

Cadastro básico de paciente

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Patient \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "resourceType": "Patient",
  "identifier": [
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709"
    }
  ],
  "name": [
    {
      "use": "official",
      "family": "Silveira",
      "given": [
        "João"
      ]
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "5521998765432",
      "use": "mobile"
    }
  ]
}'

Cadastrar um paciente sem realizar o envio de boas vindas, e com a liberação do agendamento da primeira consulta (onboarding).

Sem envio de mensagem de boas vindas, mas com liberação da primeira consulta.

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Patient \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "resourceType": "Patient",
  "identifier": [
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709"
    }
  ],
  "name": [
    {
      "use": "official",
      "family": "Silveira",
      "given": [
        "João"
      ]
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "5521998765432",
      "use": "mobile"
    }
  ],
  "extension": [
    {
      "url": "https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-sendWelcomingMessage",
      "valueBoolean": false
    },
    {
      "url": "https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-createOnboardingScheduling",
      "valueBoolean": true
    }
  ]
}'

As extensões sendWelcomingMessage e createOnboardingScheduling são obrigatórias, mas assumem o valor padrão configurado quando não enviadas. Se não houver valor enviado nem padrão cadastrado, o sistema retorna: 

{
  "issue": [
    {
      "code": "required",
      "details": {
        "text": "Extension with url https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-sendWelcomingMessage is required."
      },
      "severity": "error",
      "expression": [
        "Patient.extension"
      ]
    }
  ],
  "resourceType": "OperationOutcome"
}
{
  "issue": [
    {
      "code": "structure",
      "details": {
        "text": "Extension with url https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-createOnboardingScheduling is required."
      },
      "severity": "error",
      "expression": [
        "Patient.extension"
      ]
    }
  ],
  "resourceType": "OperationOutcome"
}
Cadastro básico de paciente, somente com nome, telefone e o CPF como identificador.

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Patient \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "resourceType": "Patient",
  "identifier": [
    {
      "system": "https://servicos.receita.fazenda.gov.br/servicos/cpf/",
      "value": "25184714057"
    }
  ],
  "name": [
    {
      "use": "official",
      "family": "Silveira",
      "given": [
        "João"
      ]
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "5521998765432",
      "use": "mobile"
    }
  ]
}'

O CPF deve conter exatamente 11 dígitos, sem pontuação. Veja as regras completas em Identificadores e upsert.

Cadastro de paciente adicionando-o a grupos (Cohorts)​

Para adicionar pacientes a grupos (cohorts), utilize o campo contained na requisição, conforme exemplo abaixo:

info

Para clientes que não possuem um grupo de pacientes padrão configurado, o campo contained torna-se obrigatório. Caso deseje ter um grupo padrão configurado, entre em contato com o suporte da Nilo.

Adicionando paciente a grupos.

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Patient \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "resourceType": "Patient",
  "identifier": [
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709"
    }
  ],
  "name": [
    {
      "use": "official",
      "family": "Silveira",
      "given": [
        "João"
      ]
    }
  ],
  "contained": [
    {
      "resourceType": "Group",
      "actual": true,
      "type": "person",
      "identifier": [
        {
          "system": "https://www.acmesaude.com.br/integracao/group/",
          "value": "group-123"
        }
      ]
    },
    {
      "resourceType": "Group",
      "actual": true,
      "type": "person",
      "identifier": [
        {
          "system": "https://www.acmesaude.com.br/integracao/group/",
          "value": "group-456"
        }
      ]
    }
  ]
}'
info

Para saber mais sobre grupos de pacientes, consulte a seção Grupos de Pacientes.

Possíveis erros (OperationOutcome)​

Ao associar um paciente a grupos, o sistema pode retornar os seguintes erros:

Grupo com identificadores enviados não existe

{
    "issue": [
        {
            "code": "structure",
            "details": {
                "text": "Group with identifiers (system|value) https://www.acmesaude.com.br/integracao/group/|group-123 does not exists"
            },
            "severity": "error",
            "expression": [
                "Patient.contained"
            ]
        }
    ],
    "resourceType": "OperationOutcome"
}

Esse tipo de erro ocorre quando o grupo de pacientes não existe ou não foi encontrado no sistema. É importante garantir que o identificador do grupo esteja correto e que o grupo tenha sido criado previamente. Para consultar os grupos de pacientes existentes, você pode utilizar o endpoint de leitura do recurso Group na documentação de leitura de Group.

Conflito de campos contained e extension

{
    "issue": [
        {
            "code": "structure",
            "details": {
                "text": "Group cannot be defined both in extension and contained."
            },
            "severity": "error",
            "expression": [
                "Patient.extension,contained"
            ]
        }
    ],
    "resourceType": "OperationOutcome"
}

Um grupo de pacientes não pode ser definido tanto na extension quanto no contained. Escolha o campo contained para definir os grupos do paciente.

Criação de paciente sem associação a grupos

Para clientes que não possuem um grupo de pacientes padrão configurado, o campo contained torna-se obrigatório e caso não seja enviado, o sistema retornará o seguinte erro:

{
  "issue": [
    {
      "code": "structure",
      "details": {
        "text": "Extension with url 'https://landing-zone-api.nilo.services/fhir/resources/Group' is required when no contained Group resourceType is present, or contained with resourceType=Group is required when no extension is present."
      },
      "severity": "error",
      "expression": [
        "Patient.contained"
      ]
    }
  ],
  "resourceType": "OperationOutcome"
}

Perfil de cadastro (lead)​

Cadastro de um paciente como lead — um pré-cadastro que só se torna paciente ativo após a aceitação dos termos de uso.

Cadastro de paciente como lead (pré-cadastro)

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Patient \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "resourceType": "Patient",
  "identifier": [
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709"
    }
  ],
  "name": [
    {
      "use": "official",
      "family": "Silveira",
      "given": [
        "João"
      ]
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "5521998765432",
      "use": "mobile"
    }
  ],
  "extension": [
    {
      "url": "https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-isLead",
      "valueBoolean": true
    }
  ]
}'

A extensão patient-isLead é obrigatória, mas assume o valor padrão configurado quando não enviada. Se não houver valor enviado nem padrão cadastrado, o sistema retorna: 

{
  "issue": [
    {
      "code": "required",
      "details": {
        "text": "Extension with url https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-isLead is required."
      },
      "severity": "error",
      "expression": [
        "Patient.extension"
      ]
    }
  ],
  "resourceType": "OperationOutcome"
}
Atributos complementares​

Cadastro informando os atributos complementares (doador de órgãos, identidade de gênero e espiritualidade). Consulte a seção Valores complementares para os valores aceitos e o comportamento de cada extensão.

Cadastro com atributos complementares

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Patient \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "resourceType": "Patient",
  "identifier": [
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709"
    }
  ],
  "name": [
    {
      "use": "official",
      "family": "Silveira",
      "given": [
        "João"
      ]
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "5521998765432",
      "use": "mobile"
    }
  ],
  "extension": [
    {
      "url": "http://hl7.org/fhir/StructureDefinition/patient-cadavericDonor",
      "valueBoolean": true
    },
    {
      "url": "http://hl7.org/fhir/StructureDefinition/patient-genderIdentity",
      "valueCodeableConcept": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/gender-identity",
            "code": "transgender-female",
            "display": "Transgender Female"
          }
        ],
        "text": "Mulher Trans"
      }
    },
    {
      "url": "https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-religion",
      "valueCodeableConcept": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/v2-0916",
            "code": "CATHOLIC",
            "display": "Católico"
          }
        ],
        "text": "Católico"
      }
    }
  ]
}'

Atualização de Pacientes​

Removendo nome social​

Para remover o nome social de um paciente, basta enviar o atributo period definindo o sub-atributo end com qualquer data (formato: YYYY-MM-DD). A simples presença de period.end faz o sistema entender que essa informação deve ser removida do cadastro do paciente.

Removendo nome social ou apelido

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Patient \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "resourceType": "Patient",
  "identifier": [
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709"
    }
  ],
  "name": [
    {
      "use": "official",
      "family": "Silveira",
      "given": [
        "João"
      ]
    },
    {
      "use": "usual",
      "text": "João Silva",
      "period": {
        "end": "2021-01-01"
      }
    }
  ]
}'
Inativando um paciente​

Para inativar um paciente, basta enviar o atributo active com o valor false. Quando active não é enviado, o paciente é considerado ativo ("active": true) e recebe o status ativo padrão configurado. Consulte o mapeamento de status em Pacientes.

Inativando um paciente

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Patient \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "resourceType": "Patient",
  "identifier": [
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709"
    }
  ],
  "active": false
}'
cuidado

Caso os atributos padrões não sejam enviados, o sistema assume o valor padrão definido na implantação do sistema Nilo.

Adicionando paciente a Grupos (Cohorts)​

Para atualizar os grupos de um paciente, é semelhante a criação, basta enviar o campo contained com a lista de grupos que o paciente deve pertencer.

Considerando que o paciente pertence aos grupos group-123 e group-456, conforme exemplo do cadastro, e desejo adicioná-lo ao group-789, é necessário enviar no contained os grupos que o paciente já pertence, além do novo grupo, conforme payload abaixo:

Atualizando grupos do paciente

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Patient \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "resourceType": "Patient",
  "identifier": [
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709"
    }
  ],
  "contained": [
    {
      "resourceType": "Group",
      "actual": true,
      "type": "person",
      "identifier": [
        {
          "system": "https://www.acmesaude.com.br/integracao/group/",
          "value": "group-123"
        }
      ]
    },
    {
      "resourceType": "Group",
      "actual": true,
      "type": "person",
      "identifier": [
        {
          "system": "https://www.acmesaude.com.br/integracao/group/",
          "value": "group-456"
        }
      ]
    },
    {
      "resourceType": "Group",
      "actual": true,
      "type": "person",
      "identifier": [
        {
          "system": "https://www.acmesaude.com.br/integracao/group/",
          "value": "group-789"
        }
      ]
    }
  ]
}'
Removendo paciente de grupos​

Para remover um paciente de um grupo, basta enviar o campo contained com a lista de grupos que o paciente deve pertencer, ou seja, os grupos que o paciente ainda pertence.

Por exemplo, se o paciente pertencia aos grupos group-123, group-456 e group-789, conforme o payload de atualização mostrado anteriormente, e você deseja remover o paciente do grupo group-456, basta enviar o payload sem esse grupo, conforme exemplo abaixo:

Removendo paciente de grupo

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Patient \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "resourceType": "Patient",
  "identifier": [
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709"
    }
  ],
  "contained": [
    {
      "resourceType": "Group",
      "actual": true,
      "type": "person",
      "identifier": [
        {
          "system": "https://www.acmesaude.com.br/integracao/group/",
          "value": "group-123"
        }
      ]
    },
    {
      "resourceType": "Group",
      "actual": true,
      "type": "person",
      "identifier": [
        {
          "system": "https://www.acmesaude.com.br/integracao/group/",
          "value": "group-789"
        }
      ]
    }
  ]
}'
Atenção

Sempre que o campo contained for enviado, o sistema irá substituir os grupos do paciente pela nova lista enviada.

Importante

Se o campo contained não for enviado ou estiver vazio, os grupos do paciente permanecerão inalterados.


Modelagem da API - Response​

Operação bem sucedida.
active
boolean^true|false$

Se o registro deste paciente está em uso ativo

Array of objects (Address)

O(s) endereço(s) para o indivíduo.

birthDate
string^([0-9]([0-9]([0-9][1-9]|[1-9]0)|[1-9]00)|[1-...

A data de nascimento do indivíduo.

Array of objects (Contained_Group)

Grupos de pacientes que o paciente pertence, são enviados como recursos contidos.

Array of objects (Patient_Communication)

Uma linguagem que pode ser usada para se comunicar com o paciente sobre sua saúde.

deceasedBoolean
boolean^true|false$

Indica se o indivíduo é falecido ou não.

deceasedDateTime
string^([0-9]([0-9]([0-9][1-9]|[1-9]0)|[1-9]00)|[1-...

A data e hora do falecimento do indivíduo.

Array of Extension-Patient-cadavericDonor (object) or Extension-Patient-genderIdentity (object) or Extension-Patient-religion (object) or Extension-Patient-isLead (object) or Extension-Patient-sendWelcomingMessage (object) or Extension-Patient-createOnboardingScheduling (object) or Extension-Patient-status (object)

Pode ser usado para representar informações adicionais que não fazem parte da definição básica do recurso. Qualquer implementador pode definir uma extensão, aqui apresentamos as extensões utilizadas no contexto Nilo, extensões externas a esse contexto são ignoradas.

gender
string
Enum: "male" "female" "other" "unknown"

O sexo que o paciente é considerado para fins de administração e manutenção de registros.

id
string (id) ^[A-Za-z0-9\-\.]{{1,64}}$

Qualquer combinação de letras, números, "-" e ".", com um limite de 64 caracteres. (Pode ser um número inteiro, um OID não prefixado, UUID ou qualquer outro padrão de identificador que atenda a essas restrições.) Os IDs não diferenciam maiúsculas de minúsculas.

required
Array of objects (Identifier) non-empty

Um conjunto de códigos de identificação para este paciente (IDs, CPF, RG, ...). Ao menos um identificador usado como CPF ou identificador externo é obrigatório e deve ser único, as regras de namespace para leitura e escrita são definidas durante a implantação.

object

Organização, departamento ou sub-departamento guardiã do prontuário do paciente.

object

Estado civil de um paciente

object (Meta)

Os metadados sobre um recurso. Este conteúdo do recurso é normalmente mantido pelo sistema gestor do registro.

Array of objects (HumanName)

O(s) nome(s) associado(s) ao paciente.

resourceType
required
string
Default: "Patient"

Indica o tipo do recurso transacionado.

Array of objects (ContactPoint)

Um detalhe de contato (por exemplo, um número de telefone ou um endereço de e-mail) por qual o indivíduo pode ser contatado. Atenção: números de telefone sem alta confiança é recomendado enviar com use old ou temp, desse modo não sobrescreverá outros que possam ser mais atualizados.

{
  • "active": true,
  • "address": [
    ],
  • "birthDate": "1974-12-25",
  • "contained": [
    ],
  • "communication": {
    },
  • "deceasedBoolean": true,
  • "deceasedDateTime": "2015-02-07T13:28:17",
  • "extension": [],
  • "gender": "male",
  • "id": "903dAAe9-c57f-4eb3-bd1c-65XXd41exx81",
  • "identifier": [
    ],
  • "managingOrganization": {
    },
  • "maritalStatus": {},
  • "meta": {
    },
  • "name": [
    ],
  • "resourceType": "Patient",
  • "telecom": [
    ]
}