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='http://hl7.org/fhir/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='http://hl7.org/fhir/StructureDefinition/patient-isLead').last().valueBoolean`
20	Enviar mensagem de boas vindas?	`extension.where(url='http://hl7.org/fhir/StructureDefinition/patient-sendWelcomingMessage').last().valueBoolean`
21	Liberar agendamento de onboarding?	`extension.where(url='http://hl7.org/fhir/StructureDefinition/patient-createOnboardingScheduling').last().valueBoolean`

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

Especificações de comportamento FHIR - NiloCare

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.

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.

dica

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

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

Valores padrões

Os seguintes atributos possuem uma configuração padrão customizada, e esse 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;

Perfil padrão de cadastro de paciente

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.

Implementação FHIR:

https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-isLead

Exemplo de payload:

{
  "resourceType": "Patient",
  "extension": [
    {
      "url": "https://landing-zone-api.nilo.services/fhir/StructureDefinition/patient-isLead",
      "valueBoolean": true
    }
  ]
}

Uso esperado:

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.

Exemplo de erro:

{
  "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"
}

Esse tipo de erro ocorre quando não é enviado a informação do perfil inicial do paciente ou não tem um valor padrão cadastrado.

Envio de mensagem de boas-vindas

O envio de mensagem de boas-vindas é uma ação automática que ocorre quando o paciente é cadastrado no sistema. O envio da mensagem de boas-vindas é controlado pelo atributo sendWelcomingMessage: true | false.

Implementação FHIR:

https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-sendWelcomingMessage

Exemplo de payload:

{
  "resourceType": "Patient",
  "extension": [
    {
      "url": "https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-sendWelcomingMessage",
      "valueBoolean": true
    }
  ]
}

Uso esperado:

true: mensagem de boas-vindas será enviada automaticamente.
false: nenhuma mensagem será enviada.

Exemplo de erro:

{
  "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"
}

Esse tipo de erro ocorre quando não é enviado a informação do envio da mensagem de boas-vindas ou não tem um valor padrão cadastrado.

Liberação para Primeiro Agendamento

Define se, por padrão, o paciente terá seu primeiro agendamento liberado imediatamente após o cadastro. O envio do atributo createOnboardingScheduling: true | false.

Exemplo de payload:

{
  "resourceType": "Patient",
  "id": "example-patient-onboarding-scheduling",
  "extension": [
    {
      "url": "https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-createOnboardingScheduling",
      "valueBoolean": true
    }
  ]
}

Uso esperado:

true: quando o paciente foi cadastrado, e o primeiro agendamento é liberado automaticamente.
false: o paciente não pode agendar o primeiro atendimento.

Exemplo de erro:

{
  "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"
}

Esse tipo de erro ocorre quando não é enviado a informação de liberação de agendamento de onboarding ou não tem um valor padrão cadastrado.

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.

Exemplo de payload:

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

Consulte a documentação de escrita de paciente para mais exemplos de payload, como por exemplo remover ou adicionar paciente a múltiplos grupos.

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.

Possíveis erros (OperationOutcome)

Associação a grupos de pacientes (Cohorts)

Ao tentar 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.dev.nilo.servicesfhir/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"
}

Unidades 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"
  }
}

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"
}

important

O envio da unidade de cuidado no paciente não é obrigatório. Porém, se não for enviado, o sistema atribuirá automaticamente a unidade de cuidado padrão configurada para o cliente.

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

cuidado

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

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.

Implementação FHIR:

https://{domínio}/fhir/resources/StructureDefinition/patient-cadavericDonor

Substitua {domínio} conforme o ambiente:

Produção: landing-zone-api.nilo.services
Staging: landing-zone-api.stg.nilo.services

Exemplo de payload:

{
  "resourceType": "Patient",
  "extension": [
    {
      "url": "https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-cadavericDonor",
      "valueBoolean": true
    }
  ]
}

Uso esperado:

true: o paciente é um doador de órgãos.
false: o paciente não é um doador de órgãos.

Identidade de gênero

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

Implementação FHIR:

https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-genderIdentity

Exemplo de payload:

{
  "url": "https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-genderIdentity",
  "valueCodeableConcept": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/gender-identity",
        "code": "transgender-female",
        "display": "Transgender Female"
      }
    ],
    "text": "Mulher Trans"
  }
}

Uso esperado:

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

Espiritualidade

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

Implementação FHIR:

https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-religion

Exemplo de payload:

{
    "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"
  }
}

Uso esperado:

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

important

A inserção de valores nos atributos complementares não gera erro, porém os atributos não são efetivamente aplicados.

Introdução​

Contexto NiloCare​

Mapeamento de Campos​

Especificações de comportamento FHIR - NiloCare​

Identificadores​

Campos de data​

Valores padrões​

Perfil padrão de cadastro de paciente​

Implementação FHIR:​

Exemplo de payload:​

Uso esperado:​

Exemplo de erro:​

Esse tipo de erro ocorre quando não é enviado a informação do perfil inicial do paciente ou não tem um valor padrão cadastrado.​

Envio de mensagem de boas-vindas​

Implementação FHIR:​

Exemplo de payload:​

Uso esperado:​

Exemplo de erro:​

Esse tipo de erro ocorre quando não é enviado a informação do envio da mensagem de boas-vindas ou não tem um valor padrão cadastrado.​

Liberação para Primeiro Agendamento​

Exemplo de payload:​

Uso esperado:​

Exemplo de erro:​

Esse tipo de erro ocorre quando não é enviado a informação de liberação de agendamento de onboarding ou não tem um valor padrão cadastrado.​

Grupo de Pacientes (Cohorts)​

Exemplo de payload:​

Uso esperado:​

Possíveis erros (OperationOutcome)​

Associação a grupos de pacientes (Cohorts)​

Grupo com identificadores enviados não existe​

Conflito de campos contained e extension​

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

Unidades de cuidado​

Como ela se conecta com o Pacient?​

Exemplo:​

Exemplo de erro:​

Status do paciente​

Funcionamento​

¹ Definido nas regras de integração​

² Definido nas regras de integração​

Valores Complementares​

Doador de órgãos​

Implementação FHIR:​

Exemplo de payload:​

Uso esperado:​

Identidade de gênero​

Implementação FHIR:​

Exemplo de payload:​

Uso esperado:​

Espiritualidade​

Implementação FHIR:​

Exemplo de payload:​

Uso esperado:​

Introdução

Contexto NiloCare

Mapeamento de Campos

Especificações de comportamento FHIR - NiloCare

Identificadores

Campos de data

Valores padrões

Perfil padrão de cadastro de paciente

Implementação FHIR:

Exemplo de payload:

Uso esperado:

Exemplo de erro:

Esse tipo de erro ocorre quando não é enviado a informação do perfil inicial do paciente ou não tem um valor padrão cadastrado.

Envio de mensagem de boas-vindas

Implementação FHIR:

Exemplo de payload:

Uso esperado:

Exemplo de erro:

Esse tipo de erro ocorre quando não é enviado a informação do envio da mensagem de boas-vindas ou não tem um valor padrão cadastrado.

Liberação para Primeiro Agendamento

Exemplo de payload:

Uso esperado:

Exemplo de erro:

Esse tipo de erro ocorre quando não é enviado a informação de liberação de agendamento de onboarding ou não tem um valor padrão cadastrado.

Grupo de Pacientes (Cohorts)

Exemplo de payload:

Uso esperado:

Possíveis erros (OperationOutcome)

Associação a grupos de pacientes (Cohorts)

Grupo com identificadores enviados não existe

Conflito de campos `contained` e `extension`

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

Unidades de cuidado

Como ela se conecta com o `Pacient`?

Exemplo:

Exemplo de erro:

Status do paciente

Funcionamento

¹ Definido nas regras de integração

² Definido nas regras de integração

Valores Complementares

Doador de órgãos

Implementação FHIR:

Exemplo de payload:

Uso esperado:

Identidade de gênero

Implementação FHIR:

Exemplo de payload:

Uso esperado:

Espiritualidade

Implementação FHIR:

Exemplo de payload:

Uso esperado: