Agenda - Agendamento de Atendimentos

O Agenda é o serviço de agendamento. As organizações cadastram locais e recursos na área administrativa, depois configuram agendas (horários, cota e feriados) em Configurações. Cidadãos agendam atendimentos online ou via totem.

Conceitos Principais

Agendas

Uma Agenda é o container de configuração de agendamento. Ela liga um Recurso a um Local e define suas regras de disponibilidade (Turnos de Trabalho, Tempo médio, Max atendimentos), os campos do formulário e os tipos de documento aceitos.

Categorias e Recursos

• Categoria: Agrupamento de serviços relacionados (ex.: "Saúde", "Documentos Civis"). Serve para organizar os recursos da mesma área.
• Recurso: Serviço a ser realizado, opcionalmente dentro de uma categoria (ex.: "Vacinação", "Certidão de Nascimento")
• Local: Local físico onde o serviço é prestado

Tipos de Documento

Se for necessária verificação de identidade, configure Tipos de Documento (ex.: CPF, RG, Passaporte).

Disponibilidade

A disponibilidade é determinada por:

Configuração	Descrição
Turnos de Trabalho	Dias da semana e horários em que cada recurso aceita agendamentos
Tempo médio	Duração em minutos do atendimento
Núm. guichês (por turno)	Atendimentos em paralelo dentro do turno
Max atendimentos (por turno)	Limite de atendimentos no dia, mesmo que o turno calcule mais vagas
Dias de bloqueio	Intervalo de dias em que um mesmo documento fica bloqueado de novo atendimento
Dias de antecedência	Data máxima permitida para agendamento (ex.: 30 dias de antecedência)
Data início / Data fim	Janela de datas em que a agenda fica disponível (opcionais)
Feriados	Datas em que nenhum agendamento está disponível

Agendamentos

Um registro de Agendamento inclui:

Campo	Descrição
name	Nome do cidadão
email	E-mail de contato
phone	Telefone de contato
documentId	Número do documento
date	Data do agendamento (YYYY-MM-DD)
time	Horário (HH:MM)
resource	Recurso reservado
location	Local de atendimento
status	scheduled, confirmed, canceled, attended
code	Código único de agendamento (para referência do cidadão)
printingInfo	Texto para imprimir na confirmação

Guia do Operador

Configurar um Local

1. Vá em Admin → Locais → Novo
2. Defina nome, descrição, endereço e fuso horário
3. Salve

Configurar uma Categoria

1. Vá em Admin → Categorias → Nova
2. Defina nome e descrição do agrupamento (ex.: "Saúde")
3. Salve

Configurar um Recurso

1. Vá em Admin → Recursos → Novo
2. Selecione a categoria (opcional) e o local
3. Salve

Configurar uma Agenda

1. Vá em Configurações → Agendas → Nova
2. Selecione o Recurso e o Local
3. Defina o Tempo médio de atendimento
4. Defina os Turnos de Trabalho (dias, horários, Núm. guichês e Max atendimentos)
5. Defina Dias de bloqueio, Dias de antecedência e, opcionalmente, Data início/Data fim
6. Defina a Informação de impressão
7. Defina quais campos do formulário são obrigatórios/opcionais/ocultos (e-mail, telefone, documento, data de nascimento) e os Tipos de Documento aceitos
8. Salve

A Agenda é a entidade que o cidadão efetivamente vê e usa para agendar.

Campos do formulário

Campo	Descrição
Tempo médio	Duração média (em minutos) de cada atendimento. É usado para calcular quantas vagas cabem em cada turno
Dias de bloqueio	Por quantos dias o mesmo documento (CPF/RG) fica impedido de marcar outro atendimento depois de já ter um agendamento. Evita que o cidadão agende o mesmo serviço várias vezes em sequência
Dias de antecedência	Até quantos dias no futuro o cidadão pode agendar, contando a partir de hoje (ex.: 30 = só aparecem horários disponíveis nos próximos 30 dias)
Data início	A partir desta data a agenda passa a aceitar agendamentos. Deixe em branco para não restringir (opcional)
Data fim	Até esta data a agenda aceita agendamentos; depois dela fica indisponível. Deixe em branco para não restringir (opcional)
Informação de impressão	Texto exibido/impresso para o cidadão ao concluir o agendamento (ex.: documentos a levar, instruções de comparecimento)
Campos do cidadão	Para cada campo do formulário (e-mail, telefone, documento, data de nascimento), define se é obrigatório, opcional ou oculto no agendamento
Turnos → Núm. guichês	Quantos atendimentos podem ocorrer ao mesmo tempo dentro do turno. Ex.: tempo médio 60min, turno às 08:00, núm. guichês 4 → 4 vagas entre 08:00 e 09:00; com núm. guichês 1, só 1 vaga nesse mesmo horário
Turnos → Max atendimentos	Teto de atendimentos no dia, mesmo que o turno calcule mais vagas. Ex.: turno gera 20 vagas no dia, mas max atendimentos = 10 → a agenda fica indisponível ao atingir 10 agendamentos, mesmo restando vagas

Gerenciar Feriados

1. Vá em Configurações → Feriados
2. Adicione datas de feriado - todos os recursos ficarão indisponíveis nessas datas

Visualizar Agendamentos

1. Vá em Agendamentos para uma lista com filtros (data, local, status)
2. Vá em Calendário para uma visão calendário de todas as reservas

Exportação

A lista de agendamentos suporta exportação para CSV/Excel para relatórios.

Fluxo de Agendamento pelo Cidadão

1. Cidadão acessa o portal de agendamento (ou totem)
2. Seleciona categoria e recurso
3. A API retorna datas disponíveis (GET /api/agendas/{id}/dates)
4. Cidadão seleciona a data
5. A API retorna horários disponíveis (GET /api/agendas/{id}/times?date=YYYY-MM-DD)
6. Cidadão preenche dados pessoais e confirma
7. Agendamento é criado (POST /api/appointments)
8. Código de confirmação e resumo imprimível são retornados

Cancelamento

O cidadão pode cancelar usando o código de agendamento:

DELETE /api/appointments/{id}?code=CODIGO_DO_AGENDAMENTO

Operadores também podem cancelar pelo painel de administração.