Agenda (Marcações)

Para que serve

A Agenda é o calendário da clínica. É onde se marcam consultas, se vê o dia de trabalho de cada médico e se acompanha o percurso do paciente: marcado → chegou → em atendimento → atendido.

É também o ponto de partida para quase tudo o resto. A partir de um agendamento chega-se ao atendimento clínico, à faturação, à nota de pagamento, às prescrições e ao histórico do paciente.

Quando usar

• Quando um paciente telefona ou vem ao balcão marcar uma consulta.
• Ao início do dia, para ver quantos pacientes estão marcados.
• Quando um paciente chega à clínica, para mudar o estado para Chegou.
• Quando um paciente falta, para registar Faltou ou Não compareceu.
• Quando é preciso reagendar (arrastando o agendamento para outra hora).
• Quando o médico vai começar a consulta.
• Para enviar a confirmação da consulta por WhatsApp.

Quem pode usar

O endereço é /appointments.

Ação	Permissão / perfil necessário	Perfis que têm
Ver o calendário	Nenhuma além de ter sessão iniciada	Todos os utilizadores internos
Ver o painel lateral e criar marcações	create-appointment	admin, superadmin, médico, receção
Abrir o atendimento clínico (Atender)	create-appointment	admin, superadmin, médico, receção
Editar um agendamento pelo endereço direto	perfil médico (doctor)	médico (e admin/superadmin)
Definições de Lembretes	manage-clinic-settings	admin, superadmin, médico, enfermeiro, receção, laboratório
Enviar pedido de avaliação	manage-nps	admin, superadmin, médico, receção
Enviar acesso ao portal do paciente	manage-patient-portal	admin, superadmin, médico, receção
Iniciar teleconsulta	start-telemedicine-session	admin, superadmin, médico

Nota importante: quem não tem create-appointment (por exemplo, o perfil enfermeiro) vê o calendário mas não vê o painel lateral esquerdo e não consegue abrir o formulário de marcação.

Ecrãs e funcionalidades

[CAPTURA: página Agendamentos completa, com o painel lateral à esquerda e o calendário à direita em vista de semana]

1. Página principal — "Agendamentos" (/appointments)

Divide-se em duas colunas:

Coluna esquerda — painel lateral (só para quem pode criar marcações)

• Campo de pesquisa Procurar por Médicos — filtra o calendário para mostrar só a agenda de um médico. Não aparece se quem entrou for médico (nesse caso o calendário já é o dele).
• Botão do caixote do lixo ao lado — Limpar filtro por médico.
• Botão Procurar — abre a janela Procurar consultas.
• Botão Emergências.
• Bloco da sala de espera.

Coluna direita — o calendário

Barra de cima do calendário:

Zona	Botões
Esquerda	anterior, seguinte, hoje
Centro	O período que está a ver (mês, semana ou dia)
Direita	Dia, Semana, Mês, Lista

Barra de baixo do calendário: ano anterior (esquerda) e ano seguinte (direita).

Cada consulta aparece como um bloco colorido, com a hora e o nome do paciente. A cor indica o estado da consulta.

2. Janela "Agendamento do paciente" (criar)

Abre quando seleciona um espaço livre no calendário.

3. Janela "Informações do paciente" (agendamento existente)

Abre quando clica num agendamento já existente. É a janela de trabalho: mostra os dados do paciente e dá acesso a todas as ações.

4. Página de atendimento clínico

Endereço /appointments/{id}/attend. Ver o capítulo Prontuário.

5. Página "Lembretes automáticos"

Definições dos lembretes de consulta enviados por e-mail.

Cada botão, o que faz

No calendário

Botão / gesto	O que faz
anterior / seguinte	Recua ou avança um período
hoje	Volta ao dia de hoje
Dia / Semana / Mês / Lista	Muda a forma de ver a agenda
ano anterior / ano seguinte (em baixo)	Salta um ano
Arrastar sobre um espaço livre	Abre a janela de nova marcação
Clicar num agendamento	Abre a janela Informações do paciente
Arrastar um agendamento para outra hora/dia	Reagenda a consulta
Puxar a borda de baixo de um agendamento	Altera a duração

Na janela "Informações do paciente"

[CAPTURA: janela Informações do paciente aberta, com a fotografia à esquerda e os botões de ação em baixo à direita]

Botão	O que faz	Condição
WhatsApp	Abre o WhatsApp com uma mensagem de confirmação já escrita	Fica desativado se o paciente não tiver telefone
Pedir avaliação	Abre o WhatsApp com o pedido de avaliação da consulta	Só quando o estado é atendido e tem manage-nps
Enviar acesso ao portal	Envia ao paciente, por WhatsApp, o acesso ao portal	Precisa de manage-patient-portal e de telefone
Iniciar teleconsulta	Abre a sala de vídeo da consulta	Precisa de start-telemedicine-session e de consulta associada
Enviar link de vídeo	Envia ao paciente o link da teleconsulta por WhatsApp	Igual à anterior, mais telefone do paciente
Email	Desativado. Aparece "Disponível em breve"	—
SMS	Desativado. Aparece "Disponível em breve"	—
Mudar estado	Abre a lista de estados possíveis	—
Mais opções	Abre um menu com as ações abaixo	—
Detalhes	Abre Modificar agendamento do paciente, para corrigir data, hora, médico, etc.	—
Apagar	Apaga o agendamento. Pede confirmação	—

Menu "Mais opções"

Opção	O que faz
Auditar agendamento	Mostra quem criou, quem alterou e o quê
Visualizar prescrições	Mostra a medicação prescrita na consulta (só se houver consulta associada)
Histórico do paciente	Mostra os prontuários anteriores do paciente
Termos e documentos	Termos de consentimento e documentos do paciente
Tarefas	Lista de tarefas ligadas a este agendamento
Agendar retorno	Marca uma consulta de seguimento para o mesmo paciente
Produtos / Medicamentos	Abre a página de prescrições deste agendamento
Nota de pagamento	Gera a nota de pagamento com referência Multicaixa. Ver Faturação da consulta
Faturação	Abre o construtor de faturas. Ver Faturação da consulta

Na janela "Agendamento do paciente"

Botão	O que faz
Cancelar	Fecha sem guardar
Guardar agendamento	Cria a marcação. Enquanto grava mostra "A guardar…"

O botão Guardar agendamento fica desativado enquanto não escolher um paciente. Aparece a nota "Selecione um paciente para continuar."

Na janela "Tarefas do agendamento"

Botão	O que faz
Caixa de texto Nova tarefa (ex.: recolher resultados)	Escreve a tarefa
Lista Prioridade	Baixa, Normal ou Alta
Campo Prazo	Data limite da tarefa
Ícone de visto na tarefa	Concluir ou Marcar como pendente
Ícone do caixote	Apagar a tarefa

Cada campo do formulário

Janela "Agendamento do paciente"

O formulário está dividido em secções.

Secção Paciente

Campo	Obrigatório	Como se preenche	Notas
Nome do paciente	Sim	Escreva parte do nome e escolha da lista que aparece	Sem paciente escolhido não é possível guardar
Data de nascimento	Não	Calendário (dd/mm/aaaa)	Preenche-se sozinho quando escolhe o paciente
Telefone	Não	Texto	Preenche-se sozinho quando escolhe o paciente. Se o alterar aqui, o contacto do paciente é atualizado na ficha dele

Secção Agendamento

Campo	Obrigatório	Como se preenche	Notas
Data de início	Sim	Data e hora	Já vem preenchida com o espaço que selecionou no calendário
Data de fim	Não	Data e hora	Ver a regra de duração mais abaixo
Estado	Sim	Lista	Escolha Agendado para uma marcação nova
Esta marcação é uma consulta	Não	Interruptor	Ligue-o para marcações que originam consulta clínica. Só assim aparecem os campos da secção Consulta

Secção Consulta (só aparece com o interruptor ligado)

Campo	Obrigatório	Como se preenche
Profissional	Não	Lista de médicos da clínica
Procedimento	Não	Lista de procedimentos
Especialidade	Não	Lista de especialidades
Consulta recorrente	Não	Interruptor. Abre as opções de repetição

Opções de Consulta recorrente

Aparecem quando liga o interruptor Consulta recorrente.

Campo	Como se preenche
Frequência	Lista: Diariamente, Semanalmente, Bimensalmente, Mensalmente. A opção vazia diz «Selecione uma frequência»
Número de ocorrências	Quantas vezes a consulta se repete. Mínimo 1
Intervalo	De quanto em quanto tempo se repete. A dica diz «Intervalo entre ocorrências (ex.: a cada 2 dias).» Mínimo 1
Dias da semana	Só aparece se a frequência for Semanalmente. Botões Dom, Seg, Ter, Qua, Qui, Sex, Sáb. Clique para ligar ou desligar cada dia
Dias do mês	Só aparece se a frequência for Mensalmente. Números separados por vírgula. O exemplo sugerido é Ex: 1,15,30
Data final	Data e hora em que a repetição termina
Duração do atendimento	A duração de cada uma das consultas repetidas
Exceções (datas a excluir)	Datas em que a consulta não se realiza. Escolha a data e clique em Adicionar. Cada exceção adicionada aparece numa lista, com um ícone de caixote do lixo para a remover

Se escrever uma data de exceção num formato errado, aparece a mensagem «Por favor, insira uma data válida no formato AAAA-MM-DD.»

Secção Faturação e opções

Campo	Obrigatório	Como se preenche
Convénio	Não	Lista de convénios da clínica. A opção vazia diz «Selecione o convénio»
Bloqueado	Não	Interruptor
Aplicar desconto	Não	Interruptor

Regra automática de duração

O sistema corrige sozinho durações que não fazem sentido:

• Se não indicar Data de fim → a consulta fica com 30 minutos.
• Se a Data de fim for igual ou anterior à de início → 30 minutos.
• Se a duração for de 6 horas ou mais → 30 minutos.

Isto evita o problema de uma seleção de "dia inteiro" (na vista de mês) criar um bloco de 24 horas partido em dois dias.

Estados possíveis de um agendamento

Estado no ecrã	Quando usar
Agendado	Marcação criada, ainda não aconteceu
Em espera	O paciente aguarda
Em atendimento	A consulta está a decorrer
Reagendado	Foi mudado de data
Faltou	O paciente não veio
Não compareceu	O paciente não veio (variante)
Chegou	O paciente chegou à clínica
Cancelado	A consulta foi cancelada
atendido	A consulta foi realizada
Retorno	Consulta de seguimento

Nota: o estado atendido é escrito em minúsculas no sistema. O estado passa automaticamente a atendido quando o médico grava o registo clínico.

Exemplo prático

Situação: a Sra. Ana Ferreira telefona na segunda-feira. Quer consulta de Clínica Geral com o Dr. Paulo Neto, na quarta-feira de manhã. É a rececionista Marta que atende.

1. A Marta inicia sessão e vai a Agenda → Calendario.
2. Clica em Semana para ver a semana inteira.
3. No painel esquerdo, escreve Paulo no campo Procurar por Médicos e escolhe Paulo Neto. O calendário passa a mostrar só a agenda dele.
4. Vê que quarta-feira às 09:00 está livre. Arrasta com o rato das 09:00 às 09:30.
5. Abre a janela Agendamento do paciente, com o aviso "Agendamento para quarta-feira, 4 de fevereiro de 2026 09:00".
6. No campo Nome do paciente escreve Ana Fer e escolhe Ana Ferreira na lista. A Data de nascimento e o Telefone preenchem-se sozinhos.
7. Confirma Data de início 04/02/2026 09:00 e Data de fim04/02/2026 09:30.
8. Em Estado escolhe Agendado.
9. Liga o interruptor Esta marcação é uma consulta.
10. Em Profissional escolhe Paulo Neto; em Procedimento, Consulta de Clínica Geral; em Especialidade, Clínica Geral.
11. Em Convénio escolhe Particular.
12. Clica em Guardar agendamento.
13. Aparece a mensagem verde "Consulta agendada com sucesso!" e o bloco surge no calendário.
14. A Marta clica no bloco recém-criado, e na janela que abre clica em WhatsApp. Abre-se o WhatsApp com a mensagem de confirmação já escrita. Envia-a à Sra. Ana.

Quarta-feira, 08:55 — a Sra. Ana chega:

15. A Marta clica no agendamento das 09:00.
16. Clica em Mudar estado e escolhe Chegou.
17. Aparece "Status atualizado com sucesso" e o bloco muda de cor.

09:00 — o Dr. Paulo:

18. Abre a agenda, clica no agendamento e usa a ficha do paciente para entrar no atendimento (ver Prontuário).

Fluxo completo

RECEÇÃO
  1. Agenda → Calendario
  2. Escolher vista (Dia / Semana / Mês / Lista)
  3. (opcional) Filtrar por médico
  4. Arrastar sobre o espaço livre
  5. Preencher: paciente → datas → Estado "Agendado"
  6. Ligar "Esta marcação é uma consulta" → profissional, procedimento,
     especialidade, convénio
  7. Guardar agendamento
  8. Clicar no bloco → WhatsApp (confirmar ao paciente)

NO DIA DA CONSULTA
  9. Paciente chega → clicar no bloco → Mudar estado → "Chegou"
 10. Médico abre o agendamento → Atender → escreve o prontuário
 11. Ao gravar o prontuário, o estado passa a "atendido"
 12. Receção → Mais opções → Faturação (ou Nota de pagamento)
 13. (opcional) Pedir avaliação ao paciente

Erros comuns e como resolver

O que vê	Porquê	O que fazer
Não aparece o painel esquerdo e não consigo abrir a janela de marcação	O seu perfil não tem create-appointment (é o caso do perfil enfermeiro)	Peça a marcação à receção, ou peça permissão ao administrador
Arrasto sobre o calendário e não acontece nada	O limite de marcações do plano da clínica foi atingido	Aparece uma faixa vermelha no painel esquerdo com a explicação. Fale com o administrador
"Não foi possível carregar a agenda" com o botão Tentar novamente	Falha de ligação ao servidor	Verifique a internet e clique em Tentar novamente
"Não foi possível reagendar a consulta. A alteração foi revertida."	O servidor recusou a mudança de data/hora	O agendamento volta ao sítio de origem. Tente de novo; se persistir, use Detalhes para corrigir manualmente
"Este agendamento não está associado a um paciente." ao clicar em WhatsApp	O agendamento foi criado sem paciente	Abra Detalhes e associe o paciente, ou apague e crie de novo
"Telefone do paciente em falta ou inválido." ao clicar em WhatsApp	O paciente não tem telefone, ou o número não está num formato válido de Angola	Corrija o telefone na ficha do paciente (ver Pacientes)
O botão WhatsApp está cinzento e não clica	O paciente não tem telefone registado	Registe o telefone na ficha do paciente
"Não foi possível gerar a ligação do WhatsApp."	Erro inesperado do servidor	Tente novamente. Se persistir, contacte o suporte
A consulta foi criada duas vezes, em dois dias seguidos	Selecionou "dia inteiro" na vista de mês	Apague os dois blocos e volte a marcar na vista de Dia ou Semana
Marquei 2 horas e ficou com 30 minutos	Só são aceites durações abaixo de 6 horas; acima disso o sistema assume 30 minutos	Use Detalhes para corrigir a Data de fim
O botão Guardar agendamento está cinzento	Não escolheu paciente	Escreva o nome no campo Nome do paciente e escolha da lista
Não encontro o paciente na pesquisa	O paciente ainda não está registado	Crie-o primeiro (ver Pacientes)
Cliquei em Atender e apareceu "Consulta não editável"	Já passaram mais de 24 horas sobre a criação da consulta	Não é possível editar. Contacte o administrador
Pedir avaliação não aparece	Ou a consulta ainda não está atendido, ou falta a permissão manage-nps, ou o plano não inclui avaliações	Confirme o estado da consulta; senão fale com o administrador
A opção Lembretes dá erro 404 ou não aparece	Falta a permissão manage-clinic-settings	Fale com o administrador

Dicas e boas práticas

• Trabalhe na vista de Dia ou Semana. A vista de Mês é boa para ter uma visão geral, mas é onde é mais fácil criar marcações com duração errada.
• Reagendar é só arrastar. Não precisa de apagar e criar de novo — assim não perde o histórico do agendamento.
• Atualize os estados em tempo real. Marcar Chegou assim que o paciente entra faz com que o médico saiba, sem ter de perguntar à receção.
• Ligue sempre "Esta marcação é uma consulta" quando é mesmo uma consulta. Sem isso não se cria a consulta associada, e depois não há prontuário, não há prescrições, não há nota de pagamento nem faturação a partir do agendamento.
• Confirme sempre por WhatsApp logo depois de marcar. A janela mostra "Enviado há X" para saber quando foi a última confirmação enviada.
• Use as Tarefas do agendamento para não esquecer pendências ("recolher resultados", "confirmar seguro").
• Ative os Lembretes automáticos (Agenda → Lembretes) para reduzir faltas.

Lembretes automáticos (Agenda → Lembretes)

1. Vá a Agenda → Lembretes.
2. Ligue Enviar lembretes.
3. Ligue Canal: E-mail.
4. Em Antecedência, escolha uma ou mais opções (os botões escolhidos ficam azuis).
5. Clique em Guardar. Aparece "Guardado" a verde.

O WhatsApp continua a ser manual, feito na agenda botão a botão. Os lembretes automáticos são apenas por e-mail.

Por confirmar

• O botão Emergências, no painel lateral esquerdo, não tem ação associada no código. Aparentemente ainda não faz nada.
• A janela Procurar consultas (botão Procurar) não foi analisada em detalhe; os seus campos e filtros não estão documentados.
• Não foi possível confirmar o que fazem exatamente os interruptores Bloqueado e Aplicar desconto — são guardados no formulário, mas não se confirmou o efeito no agendamento.
• Os campos de Consulta recorrente estão documentados acima, mas não foi possível confirmar como é que as consultas repetidas aparecem no calendário, nem se cada repetição gera uma consulta faturável em separado. Confirme com um caso de teste antes de usar esta opção em produção.
• A cor exata associada a cada estado não foi documentada; é calculada pelo sistema a partir do estado.
• O ecrã Emergências e o bloco da sala de espera no painel lateral não foram analisados.
• Existe uma página de assistente de inteligência artificial em /appointments/ask-ollama-form, sem entrada no menu. Não foi documentada.