Cadastrar/atualizar

Endpoint	POST /fhir/resources/Encounter
Autenticação	🔓 Chave de API
Status	Implementado

Modelagem da API - Request

Headers
Body

Opção	Tipo	Requerido	Descrição				Exemplo
x-api-key	string	Sim	Chave de autenticação do cliente, fornecida durante a configuração do ambiente.
Content-Type	string	Sim					application/json

required	object Classificação do encontro.
required	Array of objects (Identifier) Identificador(es) pelo qual este recurso é distinguido.
	object Duração do atendimento.
required	Array of objects (Encounter_Participant) A lista de pessoas responsáveis pela prestação do serviço.
required	object A hora de início e fim do encontro.
resourceType required	string Default: "Encounter" Indica o tipo do recurso transacionado.
status required	string Enum: "planned" "arrived" "triaged" "in-progress" "onleave" "finished" "cancelled" "entered-in-error" "unknown" Situação atual desse encontro.
required	object O paciente presente no encontro.

{"class": {"code": "VR",
"display": "virtual",
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode"
},
"identifier": [{"system": "{host}/fhir/resources/NamingSystem/hippocrates-api--model-name",
"use": "usual",
"value": "12345"
}
],
"length": {"id": "string",
"value": 0
},
"participant": [{"individual": {"identifier": {"system": "{host}/fhir/resources/NamingSystem/...unit",
"use": "usual",
"value": "12345"
},
"type": "Practitioner"
},
"type": [{"coding": [{"code": "ATND",
"display": "attender",
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType"
}
],
"text": "attender"
}
]
}
],
"period": {"end": "2022-05-23T19:00:00+00:00",
"start": "2022-05-23T19:00:00+00:00"
},
"resourceType": "Encounter",
"status": "finished",
"subject": {"identifier": {"system": "{host}/fhir/resources/NamingSystem/...unit",
"use": "usual",
"value": "12345"
},
"type": "Patient"
}
}

Regras de negócio:

A requisição cria um Atendimento podendo também envolver a criação de um Agendamento quando um profissional é informado. Também é possível enviar a referência para um agendamento que já existe e criar uma associação entre o atendimento e o agendamento. A seguir temos alguns exemplos com esses cenários citados.

Atendimento com profissional:

Exemplo de Payload com participant

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Encounter \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: ???' \
  --data '{
  "resourceType": "Encounter",
  "identifier": [
    {
      "use": "usual",
      "system": "https://sistemadocliente.com/atendimentos",
      "value": "55162"
    }
  ],
  "status": "finished",
  "class": {
    "system": "http://www.saude.gov.br/fhir/r4/CodeSystem/BRCBO",
    "code": "VR",
    "display": "virtual"
  },
  "subject": {
    "type": "Patient",
    "identifier": {
      "use": "usual",
      "system": "https://sistemadocliente.com/pacientes",
      "value": "216248"
    }
  },
  "participant": [
    {
      "individual": {
        "type": "Practitioner",
        "identifier": {
          "use": "usual",
          "system": "https://sistemadocliente.com/profissionais",
          "value": "350185"
        }
      },
      "type": [
        {
          "coding": [
            {
              "system": " http://www.saude.gov.br/fhir/r4/CodeSystem/BRCBO",
              "code": "ATND",
              "display": "attender"
            }
          ],
          "text": "attender"
        }
      ]
    }
  ],
  "period": {
    "start": "2025-04-16T19:30:00+00:00",
    "end": "2025-04-16T20:00:00+00:00"
  }
}'
  

Essa agenda poderá ser também associada automaticamente à tarefa de consulta de uma Diretriz (caso exista).

Atendimento sem profissional enviado:

Exemplo de Payload sem participant

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Encounter \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: ???' \
  --data '{
  "resourceType": "Encounter",
  "identifier": [
    {
      "use": "usual",
      "system": "https://sistemadocliente.com/atendimentos",
      "value": "55162"
    }
  ],
  "status": "finished",
  "class": {
    "system": "http://www.saude.gov.br/fhir/r4/CodeSystem/BRCBO",
    "code": "VR",
    "display": "virtual"
  },
  "subject": {
    "type": "Patient",
    "identifier": {
      "use": "usual",
      "system": "https://sistemadocliente.com/pacientes",
      "value": "216248"
    }
  },
  "period": {
    "start": "2025-04-16T19:30:00+00:00",
    "end": "2025-04-16T20:00:00+00:00"
  }
}'
  

Como resultado, um Atendimento será criado normalmente, mas não será criada uma Agenda.

Atendimento sem campo period.end e profissional

Exemplo de Payload de Encounter sem period.end, sem length e com participant

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Encounter \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: ???' \
  --data '{
  "resourceType": "Encounter",
  "identifier": [
    {
      "use": "usual",
      "system": "https://sistemadocliente.com/atendimentos",
      "value": "55162"
    }
  ],
  "status": "finished",
  "class": {
    "system": "http://www.saude.gov.br/fhir/r4/CodeSystem/BRCBO",
    "code": "VR",
    "display": "virtual"
  },
  "subject": {
    "type": "Patient",
    "identifier": {
      "use": "usual",
      "system": "https://sistemadocliente.com/pacientes",
      "value": "216248"
    }
  },
  "participant": [
    {
      "individual": {
        "type": "Practitioner",
        "identifier": {
          "use": "usual",
          "system": "https://sistemadocliente.com/profissionais",
          "value": "350185"
        }
      },
      "type": [
        {
          "coding": [
            {
              "system": " http://www.saude.gov.br/fhir/r4/CodeSystem/BRCBO",
              "code": "ATND",
              "display": "attender"
            }
          ],
          "text": "attender"
        }
      ]
    }
  ],
  "period": {
    "start": "2025-04-16T19:30:00+00:00"
  }
}'
  

Nesse cenário, serão criados um atendimento e um agendamento, mas com duração mínima (1 minuto).

Atendimento com campo length e profissional

Exemplo de Payload de Encounter sem period.end, com length e com participant

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Encounter \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: ???' \
  --data '{
  "resourceType": "Encounter",
  "identifier": [
    {
      "use": "usual",
      "system": "https://sistemadocliente.com/atendimentos",
      "value": "55162"
    }
  ],
  "status": "finished",
  "class": {
    "system": "http://www.saude.gov.br/fhir/r4/CodeSystem/BRCBO",
    "code": "VR",
    "display": "virtual"
  },
  "subject": {
    "type": "Patient",
    "identifier": {
      "use": "usual",
      "system": "https://sistemadocliente.com/pacientes",
      "value": "216248"
    }
  },
  "participant": [
    {
      "individual": {
        "type": "Practitioner",
        "identifier": {
          "use": "usual",
          "system": "https://sistemadocliente.com/profissionais",
          "value": "350185"
        }
      },
      "type": [
        {
          "coding": [
            {
              "system": " http://www.saude.gov.br/fhir/r4/CodeSystem/BRCBO",
              "code": "ATND",
              "display": "attender"
            }
          ],
          "text": "attender"
        }
      ]
    }
  ],
  "period": {
    "start": "2025-04-16T19:30:00+00:00"
  },
  "length": {
    "value": 20
  }
}'
  

O campo period.end tem prioridade sobre o campo length. No exemplo acima, onde o cenário citado é atendido, serão criados um Atendimento e uma Agenda, sendo que a agenda terá fim às 2025-04-16T19:50:00+00:00 (duração de 20 minutos).

Associando Agendamento existente com atendimento

Exemplo de Payload com associação entre agendamento e atendimento

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Encounter \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: ???' \
  --data '{
  "resourceType": "Encounter",
  "identifier": [
    {
      "use": "usual",
      "system": "https://sistemadocliente.com/atendimentos",
      "value": "55162"
    }
  ],
  "status": "finished",
  "class": {
    "system": "http://www.saude.gov.br/fhir/r4/CodeSystem/BRCBO",
    "code": "VR",
    "display": "virtual"
  },
  "subject": {
    "type": "Patient",
    "identifier": {
      "use": "usual",
      "system": "https://sistemadocliente.com/pacientes",
      "value": "216248"
    }
  },
  "participant": [
    {
      "individual": {
        "type": "Practitioner",
        "identifier": {
          "use": "usual",
          "system": "https://sistemadocliente.com/profissionais",
          "value": "350185"
        }
      },
      "type": [
        {
          "coding": [
            {
              "system": " http://www.saude.gov.br/fhir/r4/CodeSystem/BRCBO",
              "code": "ATND",
              "display": "attender"
            }
          ],
          "text": "attender"
        }
      ]
    }
  ],
  "period": {
    "start": "2025-04-16T19:30:00+00:00",
    "end": "2025-04-16T20:00:00+00:00"
  },
  "appointment": [
    {
      "type": "Appointment",
      "identifier": {
        "system": "https://sistemadocliente.com/agendamentos",
        "value": "83732"
      }
    }
  ]
}'
  

Possíveis erros

Os erros são retornados no formato de OperationOutcome.

Exemplo:

{
    "issue": [
        {
            "code": "structure",
            "details": {
                "text": "Field period.start is required."
            },
            "severity": "error",
            "expression": [
                "Encounter.period.start"
            ]
        }
    ],
    "resourceType": "OperationOutcome"
}

Os principais campos são:

details: Descrição do erro.
expression: Caminho do recurso onde o erro ocorreu.

Erros conhecidos

O paciente com identificador enviado não foi encontrado ou não está ativo

Patient with identifier https://sistemadocliente.com/pacientes|216248 does not exist or is not active

O paciente removido

Patient not found.

O código enviado em 'class.code' não é suportado

Code '<code>' is not allowed. Allowed codes: 'VR', 'AMB'

Múltiplas referencias para 'appointment' não são suportadas.

Multiple appointments are not supported.

Modelagem da API - Response

✔ 200
✘ 400
✘ 500

Operação bem sucedida.

required	object Classificação do encontro.
required	Array of objects (Identifier) Identificador(es) pelo qual este recurso é distinguido.
	object Duração do atendimento.
required	Array of objects (Encounter_Participant) A lista de pessoas responsáveis pela prestação do serviço.
required	object A hora de início e fim do encontro.
resourceType required	string Default: "Encounter" Indica o tipo do recurso transacionado.
status required	string Enum: "planned" "arrived" "triaged" "in-progress" "onleave" "finished" "cancelled" "entered-in-error" "unknown" Situação atual desse encontro.
required	object O paciente presente no encontro.

{"class": {"code": "VR",
"display": "virtual",
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode"
},
"identifier": [{"system": "{host}/fhir/resources/NamingSystem/hippocrates-api--model-name",
"use": "usual",
"value": "12345"
}
],
"length": {"id": "string",
"value": 0
},
"participant": [{"individual": {"identifier": {"system": "{host}/fhir/resources/NamingSystem/...unit",
"use": "usual",
"value": "12345"
},
"type": "Practitioner"
},
"type": [{"coding": [{"code": "ATND",
"display": "attender",
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType"
}
],
"text": "attender"
}
]
}
],
"period": {"end": "2022-05-23T19:00:00+00:00",
"start": "2022-05-23T19:00:00+00:00"
},
"resourceType": "Encounter",
"status": "finished",
"subject": {"identifier": {"system": "{host}/fhir/resources/NamingSystem/...unit",
"use": "usual",
"value": "12345"
},
"type": "Patient"
}
}

Parâmetro enviado inválido.

required	Array of objects Uma coleção de mensagens de erro, aviso ou informação que resultado de uma ação do sistema.
resourceType required	string Default: "OperationOutcome" Indica o tipo do recurso transacionado.

{"issue": [{"code": "exception",
"details": {"text": "Parâmetro enviado inválido"
},
"severity": "error"
}
],
"resourceType": "OperationOutcome"
}

Modelagem da API - Request​

Regras de negócio:​

Atendimento com profissional:​

Atendimento sem profissional enviado:​

Atendimento sem campo period.end e profissional​

Atendimento com campo length e profissional​

Associando Agendamento existente com atendimento​

Possíveis erros​

Erros conhecidos​

Modelagem da API - Response​