Skip to main content
O QSmartHub modela uma operação de atendimento com um vocabulário pequeno e fixo. Entender essas entidades, e como uma senha se move entre elas, é o que faz a API e os webhooks fazerem sentido. Esta página define cada termo e mostra o ciclo de vida de uma senha de ponta a ponta.

Vocabulário

Cada entidade responde a uma pergunta. Na API, os recursos têm nomes em inglês; na interface do QSmartHub, os nomes são em português. Use esta tabela para ir de um ao outro.

A hierarquia

As entidades se encaixam numa hierarquia única, da conta até a pessoa que atende: Empresa › Unidade › Ponto de Atendimento › Estação › Operador
  • Empresa é a sua conta no QSmartHub. Seu token sempre pertence a uma empresa, e a API nunca devolve dados de outra.
  • Unidade é um local da operação (por exemplo, uma loja ou filial), com endereço e fuso horário próprios.
  • Ponto de Atendimento é aquilo que o cliente veio resolver (por exemplo, Bebidas ou Retirada).
  • Estação é onde e por quem o atendimento acontece (por exemplo, Caixa 1 ou Sala 2).
  • Operador é a pessoa que assume uma estação para atender.

Ponto de Atendimento não é Estação

Ponto de Atendimento responde “o que o cliente veio resolver”. Estação responde “onde e quem atende”. São coisas diferentes, e a senha vive essa diferença.
Uma senha nasce em um Ponto de Atendimento, sem estação. Ela só ganha uma Estação no momento da Chamada, quando um operador a chama para atender. Por isso o evento ticket.created nunca traz station_id: no nascimento, ainda não existe estação.

Senha e Chamada

A Senha (tickets) é a jornada inteira do cliente, que pode passar por mais de um ponto. A Chamada (calls) é o episódio de atendimento de uma senha em um ponto. Uma senha pode ter mais de uma chamada ao longo da jornada. A Chamada tem um ciclo de vida próprio: No QSmartHub, chamar é iniciar: a chamada e o início do atendimento acontecem no mesmo instante. Além de finalizada, uma chamada pode terminar como ausente (o cliente não compareceu), cancelada ou transferida (encaminhada para outro ponto).

O ciclo de uma senha, passo a passo

Avance pelos passos abaixo para ver uma senha percorrer o ponto, a chamada e a estação, e quais campos cada evento carrega. Repare que station_id só aparece a partir da Chamada.

Número exibido e ID interno

Toda senha carrega dois identificadores diferentes, e a API expõe os dois:
  • number é o número exibido ao cliente no painel (por exemplo, 23). Ele é para mostrar, não para rastrear: pode repetir entre pontos e ao longo do tempo.
  • id é o identificador interno da senha, um ULID público estável. Use-o para seguir a mesma senha entre chamadas, entre páginas da API e nos webhooks.
Sempre que precisar correlacionar um webhook com um registro da API, use os campos de id (como ticket_id, call_id, appointment_id), nunca o number.