Pacientes

Introdução

---

Informações demográficas e administrativas sobre um indivíduo que está recebendo cuidados ou outros serviços relacionados à saúde.

Principais informações:

• Nome do paciente;
• WhatsApp do paciente;
• Identificadores do paciente;

Contexto NiloCare

---

Esse endpoint permite aos clientes Nilo Saúde manipular o cadastro de pacientes na plataforma NiloCare, é uma alternativa a interface de usuário para integração e automatização.

Mapeamento de Campos

#	Campo	Expressão de caminho no payload
1	Nome paciente	name.where(use='official').last().text
2	Apelido ou Nome Social	name.where(use='usual').last().text
3	CPF	identifier.where(system='https://servicos.receita.fazenda.gov.br/servicos/cpf/').last().value Onde o system configurado para o cliente para identificar o cpf, por exemplo, seja 'https://servicos.receita.fazenda.gov.br/servicos/cpf/'
4	Data de Nascimento	birthDate
5	Sexo	gender
6	Identidade de gênero	extension.where(url='http://hl7.org/fhir/StructureDefinition/patient-genderIdentity').last().valueCodeableConcept.coding.first().code
7	Espiritualidade	extension.where(url='https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-religion').last().valueCodeableConcept.coding.first().code
8	Celular com Whatsapp	telecom.where(system='phone' and use='mobile').last().value
9	Email	telecom.where(system='email').last().value
10	CEP	address.last().postalCode
11	Bairro	address.last().district
12	Cidade	address.last().city
13	Estado	address.last().state
14	Logradouro	address.last().line[0]
15	Número	address.last().line[1]
16	Complemento	address.last().line[2]
17	Doador de órgãos	extension.where(url='http://hl7.org/fhir/StructureDefinition/patient-cadavericDonor').last().valueBoolean
18	Grupos de pacientes	contained.where(resourceType='Group')
19	Já aceitou os termos de uso para ser paciente?	extension.where(url='https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-isLead').last().valueBoolean
20	Enviar mensagem de boas vindas?	extension.where(url='https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-sendWelcomingMessage').last().valueBoolean
21	Liberar agendamento de onboarding?	extension.where(url='https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-createOnboardingScheduling').last().valueBoolean

* Demais atributos nos payloads são armazenados, mas não afetados pelo sistema.

info

Esta página descreve o modelo de dados do recurso Patient: os campos, extensões e valores aceitos. As regras de escrita (valores padrão, extensões obrigatórias, validações, upsert, associação a grupos, unidade de cuidado e status) e o catálogo de erros estão documentados em Cadastrar/atualizar.

Modelo de dados

---

Identificadores

Nossa API suporta o uso de múltiplos identificadores para cada paciente. Porém, apenas dois identificadores refletem na interface de usuário sistema, o CPF e identificador externo pré-definido. Os demais identificadores podem ser utilizados para fins analíticos e para recuperação futura de informações sobre o paciente.

A definição de quais identificadores da lista fornecida serão utilizados como CPF ou identificador externo depende de configurações do sistema atreladas a conta de cada cliente, ela ocorre através do atributo identifier.system. Exemplo: Configuração no sistema para identificar o CPF através do system: https://servicos.receita.fazenda.gov.br/servicos/cpf/

...
"identifier": [
  {
    "use": "usual",
    "system": "https://www.4devs.com.br/gerador_de_pessoas/",
    "value": "507823709"
  },
  { // Esse identificador será considerado CPF
    "use": "official",
    "system": "https://servicos.receita.fazenda.gov.br/servicos/cpf/",
    "value": "57978394824"
  }
],
...

cuidado

Os systems utilizados como identificadores primários podem ser definidos com o time de suporte. Ao menos um identificador primário deve ser fornecido para cada paciente.

dica

Consulte aqui mais exemplos de uso dos identificadores para um entendimento mais completo sobre o tema.

As regras de validação de CPF e o comportamento de atualização por identificador (upsert) estão em Cadastrar/atualizar.

Extensões de comportamento do cadastro

Estas extensões controlam comportamentos do cadastro no NiloCare. Abaixo estão a descrição e os valores aceitos de cada uma; as regras de obrigatoriedade, valores padrão e erros estão em Cadastrar/atualizar.

Perfil de cadastro — patient-isLead

Define o perfil inicial do registro do paciente. Um lead é um pré-cadastro que só se torna um paciente ativo após a aceitação dos termos de uso. Caso a aceitação dos termos não seja exigida, o cadastro será automaticamente considerado um paciente ativo.

• URL: https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-isLead
• true: o paciente é um lead e precisa aceitar os termos de uso para ser paciente.
• false: o paciente já pode ser considerado ativo no sistema.

Envio de mensagem de boas-vindas — patient-sendWelcomingMessage

Controla o envio automático de uma mensagem de boas-vindas quando o paciente é cadastrado no sistema.

• URL: https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-sendWelcomingMessage
• true: mensagem de boas-vindas será enviada automaticamente.
• false: nenhuma mensagem será enviada.

Liberação para primeiro agendamento — patient-createOnboardingScheduling

Define se o paciente terá seu primeiro agendamento liberado imediatamente após o cadastro.

• URL: https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-createOnboardingScheduling
• true: o primeiro agendamento é liberado automaticamente após o cadastro.
• false: o paciente não pode agendar o primeiro atendimento.

Grupo de Pacientes (Cohorts)

O Grupo de Pacientes é um recurso que permite agrupar pacientes com características semelhantes, facilitando o gerenciamento e a análise de dados. No FHIR, o recurso utilizado para representar grupos de pacientes é o Group. Por meio dele, é possível consultar quais cohorts (grupos) existem, bem como obter os identifier (system e value) corretos que devem ser utilizados no payload de Patient, no campo contained, caso queira associar um paciente a um ou mais grupos.

Consulte aqui a documentação do recurso Group para um entendimento mais completo sobre o tema.

Estrutura do contained:

{
  "resourceType": "Patient",
  "contained": [
    {
      "resourceType": "Group",
      "actual": true,
      "type": "person",
      "identifier": [
        {
          "system": "https://www.acmesaude.com.br/integracao/group/",
          "value": "group-123"
        }
      ]
    }
  ]
}

Uso esperado:

• contained: o paciente pode pertencer a um ou mais grupos de pacientes.
  • resourceType: Sempre será Group, pois é o recurso FHIR utilizado para representar grupos de pacientes.
  • actual: o valor do atributo actual é sempre true, indicando que o grupo é real e não apenas um modelo.
  • type: o valor do atributo type é sempre person, indicando que o grupo é composto por pessoas (pacientes).
  • identifier: o valor do atributo identifier é um identificador único do grupo de pacientes.
    • system: o valor do atributo system é o sistema que identifica o grupo de pacientes, por exemplo, https://www.acmesaude.com.br/integracao/group/.
    • value: o valor do atributo value é o identificador do grupo de pacientes, por exemplo, group-123.

As regras de associação (adicionar, substituir e remover grupos), os exemplos executáveis e os erros relacionados estão em Cadastrar/atualizar.

Unidade de cuidado

Uma unidade de cuidado representa a unidade de atendimento que será atribuída ao paciente.

Como ela se conecta com o Pacient?

O recurso Patient possui o campo managingOrganization, que referencia a Organization responsável pelo gerenciamento daquele paciente.

Exemplo:

"managingOrganization": {
  "type": "Organization",
  "identifier": {
    "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/sorting-hat-api--care-unit",
    "value": "001"
  }
}

O comportamento de obrigatoriedade / valor padrão e o erro relacionado estão em Cadastrar/atualizar.

Status do paciente

O status do paciente é controlado via o atributo active: true | false, utilizado para habilitar ou desabilitar o paciente no sistema, conforme as regras definidas durante a implantação do sistema Nilo.

Funcionamento

Ação	Status
Habilita	Pré ativo, Ativo
Desabilita	Encerrado, Inativo

O atributo active = true define o paciente como Ativo, o status ativo padrão¹ é exibido no Hub do paciente:

¹ Definido nas regras de integração

O atributo active = false define o paciente como Encerrado, o status inativo padrão² é exibido no Hub do paciente:

² Definido nas regras de integração

O comportamento de status padrão (quando o atributo não é enviado) está em Cadastrar/atualizar.

Valores complementares

Os atributos complementares descritos abaixo seguem a especificação FHIR. Elas podem ser utilizadas de forma opcional para representar informações adicionais que não estão presentes nos campos padrões do FHIR.

Essas extensões são compatíveis com a estrutura do recurso Patient e devem ser utilizadas conforme suas respectivas definições técnicas.

• Doador de orgãos - patient-cadavericDonor
• Identidade de gênero - patient-genderIdentity
• Espiritualidade - patient-religion

Doador de órgãos

O atributo cadavericDonor indica se o paciente é um doador de órgãos. Ele é utilizado para identificar pacientes que são doadores de órgãos, o que pode ser relevante em contextos de transplantes e cuidados de saúde relacionados.

• URL: http://hl7.org/fhir/StructureDefinition/patient-cadavericDonor
• true: o paciente é um doador de órgãos.
• false: o paciente não é um doador de órgãos.

nota

Diferente das extensões próprias da Nilo (isLead, sendWelcomingMessage, etc.), o doador de órgãos usa a URL canônica do FHIR (http://hl7.org/...), que é fixa e independente do ambiente.

Identidade de gênero

O atributo genderIdentity indica a identidade de gênero do paciente.

• URL: http://hl7.org/fhir/StructureDefinition/patient-genderIdentity

Os valores aceitos para o atributo genderIdentity são os seguintes:

• male: Homem
• female: Mulher
• transgender-male: Homem Trans
• transgender-female: Mulher Trans
• other: Outro
• non-disclose: Não informado

nota

Assim como o doador de órgãos, a identidade de gênero usa a URL canônica do FHIR (http://hl7.org/...), fixa e independente do ambiente.

Espiritualidade

O atributo religion indica a religião do paciente. Ele é utilizado para identificar a religião do paciente.

• URL (envio/POST): https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-religion

O campo para adicionar o valor para o atributo religion é livre, portanto caso seu sistema possua padrão específico, ele deverá ser respeitado.

cuidado

No envio (POST) a espiritualidade deve usar a URL Nilo (.../fhir/resources/StructureDefinition/patient-religion). Na leitura (GET), porém, essa extensão é retornada com a URL canônica do FHIR (http://hl7.org/fhir/StructureDefinition/patient-religion). Portanto, ao reenviar um paciente obtido via GET, ajuste a URL desta extensão para a URL Nilo, caso contrário o valor será ignorado.

important

Os atributos complementares (doador de órgãos, identidade de gênero e espiritualidade) são armazenados e aplicados ao cadastro do paciente. Diferente de atributos como sendWelcomingMessage, eles não disparam ações automáticas no sistema — apenas registram a informação no perfil do paciente.

Veja exemplos de requisição executáveis para todos esses atributos em Cadastrar/atualizar.