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 |
| ||||
4 | Data de Nascimento | birthDate | ||||
5 | Sexo | gender | ||||
6 | Identidade de gênero |
| ||||
7 | Espiritualidade |
| ||||
8 | Celular com Whatsapp | telecom.where(system='phone' and use='mobile').last().value | ||||
9 | 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 |
| ||||
18 | Grupo de pacientes |
| ||||
19 | Já aceitou os termos de uso para ser paciente? |
| ||||
20 | Enviar mensagem de boas vindas? |
| ||||
21 | Liberar agendamento de onboarding? |
|
* 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"
}
],
...
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.
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.
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 (Cohort)
O Grupo de Pacientes é um recurso que permite agrupar pacientes com características semelhantes, facilitando o gerenciamento e a análise de dados.
No padrão FHIR, o recurso utilizado para representar grupos de pacientes é o Group
. Por meio dele, é possível consultar quais cohorts (grupos) existem, bem como identificar o system
e o value
corretos que devem ser utilizados no payload da extensão, caso queira associar um paciente a um determinado grupo.
Consulte
aqui a documentação do recurso Group
para um entendimento mais completo sobre o tema.
Exemplo de payload:
{
"resourceType": "Patient",
"id": "example-patient-cohort",
"extension": [
{
"url": "https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/patient-cohort",
"valueIdentifier": {
"system": "https://nilo.services/cohort-system",
"value": "cohort-123"
}
}
]
}
Uso esperado:
value
: o valor do atributocohort
é o nome do grupo de pacientes ao qual o paciente pertence.system
: o valor do atributosystem
é o sistema que identifica o grupo de pacientes.
Exemplo de erro:
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "exception",
"details": {
"text": "ValidationError: 'default_cohort_id' cannot be null"
}
}
]
}
Esse tipo de erro ocorre quando não é enviado a informação de qual cohort o paciente faz parte ou não tem um valor padrão cadastrado.
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": {
"identifier": {
"system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/sorting-hat-api--care-unit",
"value": "001"
}
}
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"
}
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
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
: Homemfemale
: Mulhertransgender-male
: Homem Transtransgender-female
: Mulher Transother
: Outronon-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.
A inserção de valores nos atributos complementares não gera erro, porém os atributos não são efetivamente aplicados.