Pular para o conteúdo principal

Cadastrar/atualizar

EndpointPOST /fhir/resources/Appointment
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
Criação básica de um Appointment

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Appointment \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "resourceType": "Appointment",
  "identifier": [
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/agendamento/",
      "value": "AG-98765"
    }
  ],
  "status": "booked",
  "description": "Consulta de retorno",
  "start": "2024-09-28T20:32:56.528762+00:00",
  "end": "2024-09-28T21:02:56.528762+00:00",
  "created": "2024-09-27T20:30:56.528762+00:00",
  "comment": "Comentários sobre o agendamento",
  "appointmentType": {
    "coding": [
      {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/appointment-type",
        "code": "ONLINE",
        "display": "Atendimento Online"
      }
    ]
  },
  "participant": [
    {
      "actor": {
        "type": "Patient",
        "identifier": {
          "system": "https://www.acmesaude.com.br/integracao/paciente/",
          "value": "1234"
        },
        "reference": "Patient/d77bd7b0-144d-4789-9e81-062a375addb8"
      },
      "status": "accepted"
    },
    {
      "actor": {
        "type": "Practitioner",
        "identifier": {
          "system": "https://www.acmesaude.com.br/integracao/profissional/",
          "use": "usual",
          "value": "456"
        },
        "reference": "Practitioner/1e8f3c9e-6f4b-4c3b-9d2e-1c2b3a4d5e6f"
      },
      "status": "accepted"
    }
  ]
}'

Modelagem da API - Response​

Operação bem sucedida.
resourceType
required
any
Value: "Appointment"
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.

object (Meta)

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

implicitRules
string (uri) ^\S*$

Uma referência de identificador de recurso uniforme (RFC 3986) usado como "namespace".

language
string (code) ^[^\s]+(\s[^\s]+)*$

Indica que o valor é obtido de um conjunto de strings controladas definidas em uma listagem.

object (Narrative)
Array of objects (Appointment_Contained)
Array of objects (Extension)
Array of objects (Extension)
required
Array of objects (Identifier)

identificador único para o Appointment.

status
required
any
Enum: "proposed" "pending" "booked" "arrived" "fulfilled" "cancelled" "noshow" "entered-in-error" "checked-in" "waitlist"
object (CodeableConcept)

Um CodeableConcept representa um valor geralmente fornecido como uma referência a terminologias ou ontologias, mas também pode ser definido pelo fornecimento de texto. Esse é um padrão comum em dados de saúde.

Array of objects (CodeableConcept)
Array of objects (CodeableConcept)
Array of objects (CodeableConcept)
object

Modalidade do atendimento (online ou presencial).
Informar em coding, com system = {host}/fhir/resources/CodeSystem/appointment-type.
ONLINE = Atendimento Online
IN_PERSON = Atendimento Presencial
Quando omitido, o agendamento é tratado como online.

Array of objects (CodeableConcept)
Array of objects (Reference)
priority
number (unsignedInt) ^[0]|([1-9][0-9]*)$

An integer with a value that is not negative (e.g. >= 0)

description
string (string) ^[ \r\n\t\S]+$

Título da agenda

Array of objects (Reference)
start
required
string (instant) ^([0-9]([0-9]([0-9][1-9]|[1-9]0)|[1-9]00)|[1-...

Date/Time que o atendimento deve ocorrer

end
required
string (instant) ^([0-9]([0-9]([0-9][1-9]|[1-9]0)|[1-9]00)|[1-...

Date/Time que o atendimento deve terminar.

minutesDuration
number (positiveInt) ^[1-9][0-9]*$

An integer with a value that is positive (e.g. >0)

Array of objects (Reference)
created
string (dateTime) ^([0-9]([0-9]([0-9][1-9]|[1-9]0)|[1-9]00)|[1-...

Date/Time do agendamento

comment
string (string) ^[ \r\n\t\S]+$

Descrição.

patientInstruction
string (string) ^[ \r\n\t\S]+$

Uma sequência de caracteres.

Array of objects (Reference)
required
Array of objects (Appointment_Participant)

Lista de participantes do agendamento. Precisar ser exatamente dois, um com type = Patient e um com type = Practitioner.

Array of objects (Period)
{
  • "resourceType": "Appointment",
  • "id": "903dAAe9-c57f-4eb3-bd1c-65XXd41exx81",
  • "meta": {
    },
  • "implicitRules": "string",
  • "language": "string",
  • "text": {
    },
  • "contained": [
    ],
  • "extension": [
    ],
  • "modifierExtension": [
    ],
  • "identifier": [
    ],
  • "status": "proposed",
  • "cancelationReason": {
    },
  • "serviceCategory": [
    ],
  • "serviceType": [
    ],
  • "specialty": [
    ],
  • "appointmentType": {
    },
  • "reasonCode": [
    ],
  • "reasonReference": [
    ],
  • "priority": 0,
  • "description": "string",
  • "supportingInformation": [
    ],
  • "start": "2022-05-25T18:42:06.551129+00:00",
  • "end": "2022-05-25T18:42:06.551129+00:00",
  • "minutesDuration": 0,
  • "slot": [
    ],
  • "created": "2022-05-23T19:00:00+00:00",
  • "comment": "string",
  • "patientInstruction": "string",
  • "basedOn": [
    ],
  • "participant": [
    ],
  • "requestedPeriod": [
    ]
}

Campos aceitos na escrita​

Campo FHIRRequeridoDestino no NiloCare
resourceType✅— (deve ser exatamente "Appointment")
identifier✅Chave de correspondência do agendamento (upsert)
participant (ator Patient)✅Paciente do agendamento
participant (ator Practitioner)✅Profissional do agendamento — também usado como autor e responsável pelo agendamento
start✅Data prevista para início
end✅Data prevista para fim
status✅Situação do agendamento
description—Título do agendamento
comment—Observações do agendamento (vazio quando omitido)
appointmentType—Modalidade (online/presencial). Quando omitido, assume online

Os demais campos previstos no schema do Appointment são armazenados no recurso FHIR, mas não afetam o agendamento no NiloCare. Campos que não fazem parte do schema são rejeitados — o payload não aceita atributos desconhecidos.

Identificação e upsert​

O campo identifier é obrigatório e é usado para decidir entre criar e atualizar o agendamento:

  • se algum dos identificadores enviados corresponder a um Appointment já existente, o agendamento correspondente é atualizado;
  • caso contrário, um novo agendamento é criado.

Você pode usar o identificador do seu próprio sistema (ex.: https://www.acmesaude.com.br/integracao/agendamento/) — ele é preservado no recurso. O identificador interno da Nilo, no system https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--scheduling-v2, é adicionado automaticamente após a sincronização.

Participantes​

O paciente e o profissional são localizados a partir de participant.actor.identifier combinado com participant.actor.type. Ambos precisam já existir na Nilo — este endpoint não cria pacientes nem profissionais. Cadastre-os previamente em Paciente e Profissional.

"participant": [
  {
    "actor": {
      "type": "Patient",
      "identifier": {
        "system": "https://www.acmesaude.com.br/integracao/paciente/",
        "value": "1234"
      }
    },
    "status": "accepted"
  },
  {
    "actor": {
      "type": "Practitioner",
      "identifier": {
        "system": "https://www.acmesaude.com.br/integracao/profissional/",
        "value": "456"
      }
    },
    "status": "accepted"
  }
]

Situação (status)​

status enviadoSituação no NiloCare
proposedAgendado
pendingAgendado
bookedAgendado
arrivedAgendado
checked-inAgendado
cancelledCancelado
noshowNão compareceu
fulfilledRealizado

Os demais valores de status previstos no FHIR R4 (como waitlist e entered-in-error) não são aceitos na escrita.

Modalidade (appointmentType)​

Informe appointmentType.coding com system = https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/appointment-type e code igual a ONLINE ou IN_PERSON. Qualquer outro código nesse system é rejeitado. Quando o campo é omitido — ou quando o coding usa outro system — o agendamento é tratado como online.

Validações​

Quando uma validação falha, o job é finalizado com status de erro e um OperationOutcome no campo output, conforme a tabela abaixo.

Mensagemexpressiontype
Nenhum identifier informadoAppointment.identifierrequired
Appointment must have only one participant.actor of type PatientAppointment.participant.actorrequired
Appointment must have only one participant.actor of type PractitionerAppointment.participant.actorrequired
Unable to find PatientAppointment.participant.actornot-found
Unable to find PractitionerAppointment.participant.actornot-found
The start field is requiredAppointment.startrequired
The end field is requiredAppointment.endrequired
The end field must be greater than the start fieldAppointment.endinvalid
The status '<valor>' is not supportedAppointment.statusnot-supported
The appointment type code '<valor>' is not supportedAppointment.appointmentTypenot-supported
Exatamente um de cada tipo

As mensagens sobre participant.actor são retornadas tanto quando falta o participante quanto quando há mais de um participante do mesmo tipo.

Limitações e comportamentos​

  • A integração não suporta escrita de link de sala de vídeo (videoconferência). O campo contained com o recurso Endpoint é gerado pela Nilo e ignorado na escrita — veja Sala de vídeo.
  • O paciente e o profissional precisam existir previamente na Nilo.
  • Não é possível associar mais de um paciente ou mais de um profissional ao mesmo agendamento.
  • O profissional informado é usado também como autor e como responsável pelo agendamento no NiloCare.
  • end deve ser estritamente maior que start.