Senhas

Uma senha é uma entrada numa fila emitida a um cliente quando este entra. É a unidade central do sistema de filas — tudo, desde o visor até à interface do balcão, gira em torno das senhas.

O que contém uma senha

• Número da senha — um número inteiro sequencial visível ao cliente, apresentado no recibo do quiosque, mostrado no visor e visível na lista de espera do balcão. Os números têm âmbito de uma fila e incrementam de forma monótona — nunca são reiniciados.
• Hash da senha — uma cadeia aleatória de 22 carateres com 128 bits de entropia. Este hash é a credencial anónima do cliente (ver abaixo).
• Estado — um de seis valores (ver abaixo).
• Fila — a fila a que a senha pertence.
• Registos de data/hora — quando a senha foi criada, chamada, concluída, etc.
• Anotações (opcional) — metadados inseridos pelo pessoal: nome do cliente, número de pessoas e uma nota em texto livre. Consulte Anotações da senha.

Estados da senha

Uma senha passa pelos seguintes estados ao longo do seu ciclo de vida:

Estado	Terminal?	Significado
WAITING	Não	O cliente está na fila, à espera de ser chamado.
CALLED	Não	Um balcão chamou esta senha; o cliente deve dirigir-se ao balcão.
SKIPPED	Não	O balcão passou esta senha. Pode ser chamada de novo — o pessoal pode devolvê-la a WAITING.
COMPLETED	Sim	O balcão marcou o atendimento como concluído.
CANCELED	Sim	O cliente cancelou o seu próprio lugar na fila.
NO_SHOW	Sim	O balcão confirmou que o cliente está ausente. Contabilizado separadamente de SKIPPED na análise.

Transições de estado

WAITING  → CALLED   → COMPLETED
                    ↘ SKIPPED   → WAITING  (o balcão chama o cliente de novo)
                               ↘ NO_SHOW  (o balcão confirma a ausência)
                               ↘ CANCELED (o cliente cancela o seu lugar adiado)
WAITING  → CANCELED  (iniciado pelo cliente)
CALLED   → CANCELED  (iniciado pelo cliente)
SKIPPED  → CANCELED  (iniciado pelo cliente — remove do conjunto de senhas chamáveis)

SKIPPED vs. NO_SHOW

SKIPPED é um adiamento chamável novamente — o cliente foi passado, mas a senha continua ativa. O pessoal pode chamar o cliente de volta usando a ação Devolver à fila na vista de consulta do balcão, ou premindo Anular nos 5 segundos seguintes ao salto. A subscrição de notificações push de um cliente saltado mantém-se ativa, para que a notificação push de chamada de volta o alcance mesmo que a página da senha tenha sido fechada.

NO_SHOW é uma ausência confirmada e terminal. A senha é removida do conjunto de senhas chamáveis novamente e é contabilizada separadamente na análise. Use este estado quando tiver a certeza de que o cliente saiu.

Consulte Lidar com Ausências para o fluxo de trabalho completo do balcão.

Anotações da senha

O pessoal pode anexar metadados leves a qualquer senha usando a ação Anotar no balcão:

• Nome do cliente — mostrado no balcão em permanência. Mostrado no visor apenas se a definição Chamar pelo nome da fila estiver ativa, e mesmo assim apenas de forma reduzida (“Primeiro Nome I.”) — nunca o nome completo.
• Número de pessoas — sempre mostrado no balcão e transmitido ao visor (uma contagem de baixa sensibilidade).
• Nota — nota interna em texto livre. Apenas no balcão; nunca enviada ao visor ou ao cliente.

O motivo de um salto (inserido no campo Motivo para ignorar (opcional) quando uma senha é saltada) é guardado no campo de nota da senha e é visível na vista de consulta do balcão.

As anotações podem ser adicionadas ou atualizadas em qualquer momento enquanto a senha não estiver num estado terminal.

Transferir uma senha

Uma senha WAITING pode ser transferida para outra fila do mesmo estabelecimento usando o botão Transferir no balcão. Isto é útil quando um cliente entrou na fila errada ou quando a triagem revela que precisa de um serviço diferente.

Regras de transferência:

• Apenas senhas WAITING podem ser transferidas. As senhas CALLED têm de ser concluídas, saltadas ou marcadas como ausência primeiro.
• A fila de origem e a fila de destino têm de estar no mesmo estabelecimento.
• A fila de destino tem de estar ACTIVE.
• O balcão tem de estar atribuído tanto à fila de origem como à fila de destino.
• É necessária uma subscrição ativa.

Posicionamento após a transferência — a senha mantém a hora original de entrada do cliente, mais uma penalização de 5 minutos. Isto preserva o tempo de espera já cumprido, impedindo simultaneamente que o cliente passe à frente de clientes que já esperam há mais tempo na fila de destino.

O hash da senha é preservado — o URL da página da senha do cliente mantém-se válido. A senha recebe um novo número sequencial na fila de destino. As atualizações em tempo real são transmitidas de imediato a ambas as filas.

Consulte a secção Transferir uma senha para outra fila do guia do balcão para instruções passo a passo.

O hash da senha como credencial

Os clientes são anónimos — não é necessário nenhum início de sessão ou conta para entrar numa fila. Em vez disso, o hash de 22 carateres da senha serve como prova de posse do cliente. Está incorporado no URL da página da senha:

https://customer.jonot.io/{org}/{location}/{queue}/{ticket-hash}/

Conhecer o hash prova que é o dono dessa senha. A API usa o hash para autorizar:

• ticketByHash — consultar a sua senha e posição
• cancelTicket — cancelar a sua própria senha (funciona para senhas WAITING, CALLED e SKIPPED)

Este design é intencional: remove todo o atrito de entrar numa fila. Sem conta, sem aplicação, sem palavra-passe — apenas um URL.

O hash tem 128 bits de entropia (equivalente a um UUID v4), tornando computacionalmente inviável adivinhar o hash da senha de outro cliente.

Verificação sob tráfego invulgar

Entrar mantém-se sem atrito em uso normal. Como salvaguarda antiabuso, se uma única fila receber um pico anormalmente elevado de entradas num curto espaço de tempo, os clientes que entram pela web (QR code ou link) podem ter de concluir uma rápida verificação “Sou humano” antes de a sua senha ser emitida. A maioria dos visitantes legítimos passa-a de forma invisível. Isto só aparece durante picos de tráfego — em tráfego normal não é mostrada nenhuma verificação — e nunca se aplica ao quiosque presencial, cujas entradas são de confiança por credencial de dispositivo.

Estimativa do tempo de espera

Quando uma senha está no estado WAITING, a página da senha do cliente mostra uma estimativa do tempo de espera. A mesma estimativa é mostrada no ecrã de confirmação pós-entrada do quiosque, para que o cliente saia do quiosque com um número a memorizar. Trata-se de uma estimativa de melhor esforço, não de uma garantia.

A estimativa é calculada a partir dos intervalos de atendimento recentes nessa fila: se existirem senhas concluídas suficientes nos últimos 90 minutos, o servidor calcula um tempo de atendimento mediano e multiplica-o pela posição do cliente na fila (pessoas à frente + 0,5). Quando o cliente é o próximo da fila (zero pessoas à frente), a estimativa é apresentada como zero. Quando o histórico recente é escasso, é usado como alternativa o Tempo de atendimento esperado configurado na fila. A estimativa tem um indicador de confiança (alta quando derivada de dados ao vivo ou quando o cliente é o próximo, baixa quando recorre à predefinição configurada).

A estimativa só é mostrada para senhas WAITING numa fila ACTIVE. Não é mostrada quando a fila está em pausa, e desaparece assim que a senha é chamada.

Experiência do cliente

1. O cliente entra via QR code ou quiosque → é emitida uma senha no estado WAITING.
2. O cliente abre a página da senha → vê a sua posição na fila e, quando disponível, uma estimativa do tempo de espera em tempo real.
3. Quando o balcão chama o seu número, a senha passa a CALLED → a página do cliente atualiza-se de imediato.
4. O cliente dirige-se ao balcão. Após o atendimento, o balcão marca-a como COMPLETED.
5. Se o cliente não responder, o balcão pode:
   • Ignorar → a senha passa a SKIPPED (adiamento chamável de novo). O ecrã do cliente mostra que foi passado, com opções para esperar ou entrar de novo.
   • Ausente → a senha passa a NO_SHOW (terminal). A análise contabiliza este caso separadamente das senhas saltadas.
6. Um cliente saltado pode ser chamado de novo pelo pessoal (volta a WAITING no início da fila), ou pode cancelar o seu lugar e entrar de novo no fim.