Agendamentos

Introdução

Um agendamento entre um Paciente e um Profissional.

Principais informações:

Paciente
Profissional
Data

Contexto NiloCare

Esse endpoint permite aos clientes Nilo Saúde manipular agendamentos de profissionais e pacientes na plataforma NiloCare.

Mapeamento de Campos

Recurso FHIR: Appointment

#	Campo	Expressão de caminho no objeto FHIR
1	Título do agendamento	`description`
2	Observações do agendamento	`comment`
3	Situação	`status`
4	Data prevista para início	`start`
5	Data prevista para fim	`end`
6	Data de criação	`created`
7	Paciente	`participant.where(actor.type='Patient').actor`
8	Profissional	`participant.where(actor.type='Practitioner').actor`
9	Sala de vídeo	`contained.where(resourceType='Endpoint').address`
10	Modalidade (online/presencial)	`appointmentType.coding.where(system='https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/appointment-type').code`

Atenção à inversão de nomes

O título do agendamento no NiloCare é enviado em description, e as observações em comment.

* Demais atributos previstos no schema do Appointment são armazenados nos payloads, mas não afetados pelo sistema.

Especificações de comportamento FHIR - NiloCare

Definição dos participantes

O FHIR permite associar diversos atores a um agendamento, porém o NiloCare só permite associar um profissional e um paciente.

Ao cadastrar ou atualizar um agendamento, a lista participant deve conter exatamente um ator do tipo Patient e exatamente um ator do tipo Practitioner. Nenhum ou mais de um de cada tipo resulta em erro — veja Cadastrar/atualizar.

Cada ator é identificado por participant.actor.type (Patient ou Practitioner) e por participant.actor.identifier, que é usado para localizar o paciente e o profissional já existentes na Nilo. O campo participant.actor.reference é preenchido pela Nilo nas respostas, mas não é usado para resolver o ator na escrita.

Situação do agendamento

Nas leituras (Nilo → FHIR), a situação do agendamento no NiloCare é traduzida para status da seguinte forma:

Situação no NiloCare	`status`
Agendado	`booked`
Reagendado	`booked`
Recorrente	`booked`
Liberado	`proposed`
Cancelado	`cancelled`
Não compareceu	`noshow`
Bloqueado / indisponível	`waitlist`
Realizado	`fulfilled`

Na escrita (FHIR → Nilo), o mapeamento aceito está descrito em Cadastrar/atualizar.

Agendamentos cancelados

Ao cancelar um agendamento, o NiloCare pode limpar as datas do registro. Por isso um Appointment com status = cancelled pode ser retornado sem start e sem end.

Modalidade do atendimento (online ou presencial)

A modalidade do agendamento é definida pelo campo appointmentType, informada em coding com system = https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/appointment-type e um dos códigos abaixo:

`code`	Modalidade
`ONLINE`	Atendimento Online
`IN_PERSON`	Atendimento Presencial

Quando o campo appointmentType é omitido (ou o coding não usa o system acima), o agendamento é tratado como online por padrão.

Sala de vídeo

A funcionalidade de sala de vídeo permite a criação automática de links para videoconferência em agendamentos. Esta funcionalidade está disponível exclusivamente para clientes habilitados durante o processo de implantação.

Habilitação

Para verificar se possui esta funcionalidade habilitada ou solicitar a ativação, entre em contato com o suporte Nilo.

Pré-requisitos para criação

Para que uma sala de vídeo seja criada automaticamente, o agendamento deve atender aos seguintes critérios:

Datas válidas: Possuir data de início e fim no futuro (agendamentos retroativos não geram sala)
Status apropriado: Agendamentos com status fulfilled, noshow ou cancelled não terão sala criada

Como funciona o processo

1. Criação inicial do agendamento

Quando você cria um agendamento, a resposta inicial não conterá o link da sala de vídeo, pois sua criação ocorre de forma assíncrona:

{
  "resourceType": "Appointment",
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "identifier": [
    {
      "use": "usual",
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--scheduling-v2",
      "value": "789"
    },
    {
      "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": {
          "use": "usual",
          "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--patient-v2",
          "value": "123"
        },
        "reference": "Patient/d77bd7b0-144d-4789-9e81-062a375addb8"
      },
      "status": "accepted"
    },
    {
      "actor": {
        "type": "Practitioner",
        "identifier": {
          "use": "usual",
          "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/almanac-api--professional",
          "value": "456"
        },
        "reference": "Practitioner/1e8f3c9e-6f4b-4c3b-9d2e-1c2b3a4d5e6f"
      },
      "status": "accepted"
    }
  ]
}

Tempo de processamento

A criação da sala de vídeo é concluída normalmente em poucos segundos, mas pode levar até alguns minutos durante períodos de alta demanda.

2. Agendamento atualizado com sala

Após o processamento, o agendamento é atualizado com o campo contained contendo um recurso do tipo Endpoint com o link da videoconferência:

{
  "resourceType": "Appointment",
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "identifier": [
    {
      "use": "usual",
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--scheduling-v2",
      "value": "789"
    },
    {
      "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"
      }
    ]
  },
  "contained": [
    {
      "address": "https://nilovideo.app/f/51236",
      "connectionType": {
        "code": "https"
      },
      "payloadType": [
        {
          "text": "video"
        }
      ],
      "resourceType": "Endpoint",
      "status": "active"
    }
  ],
  "participant": [
    {
      "actor": {
        "type": "Patient",
        "identifier": {
          "use": "usual",
          "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--patient-v2",
          "value": "123"
        },
        "reference": "Patient/d77bd7b0-144d-4789-9e81-062a375addb8"
      },
      "status": "accepted"
    },
    {
      "actor": {
        "type": "Practitioner",
        "identifier": {
          "use": "usual",
          "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/almanac-api--professional",
          "value": "456"
        },
        "reference": "Practitioner/1e8f3c9e-6f4b-4c3b-9d2e-1c2b3a4d5e6f"
      },
      "status": "accepted"
    }
  ]
}

Como verificar a criação da sala

Você pode acompanhar a criação da sala de vídeo através de duas abordagens:

Método	Descrição	Recomendação
Consulta via API	Realizar requests periódicas para verificar se o campo `contained` está presente	Adequado para verificações pontuais
Webhook ⭐	Receber notificações automáticas quando a sala for criada	Recomendado para automação

Usando consulta via API

Consulte o agendamento e verifique a presença do campo contained. Veja mais detalhes em Consultar Agendamento.

Usando webhooks (recomendado)

Configure um webhook para receber notificações automáticas sobre atualizações nos agendamentos. Consulte nossa documentação completa sobre Webhooks de Agendamentos.

Introdução​

Contexto NiloCare​

Mapeamento de Campos​

Especificações de comportamento FHIR - NiloCare​

Definição dos participantes​

Situação do agendamento​

Modalidade do atendimento (online ou presencial)​

Sala de vídeo​

Pré-requisitos para criação​

Como funciona o processo​

1. Criação inicial do agendamento​

2. Agendamento atualizado com sala​

Como verificar a criação da sala​

Usando consulta via API​

Usando webhooks (recomendado)​