> ## Documentation Index
> Fetch the complete documentation index at: https://developers.qsmarthub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conceitos: o modelo de domínio do QSmartHub

> Entenda Empresa, Unidade, Ponto de Atendimento, Estação, Senha e Chamada, e como uma senha percorre a operação do nascimento à finalização.

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.

| Termo no produto | Recurso na API | Responde a |
| - | - | - |
| **Empresa** | (o escopo do seu token) | De quem é a operação? |
| **Unidade** | `units` | Onde a operação acontece? |
| **Ponto de Atendimento** | `service-points` | O que o cliente veio resolver? |
| **Estação** | `stations` | Onde e quem vai atender? |
| **Operador** | campo `operator_id` | Quem está atendendo? |
| **Senha** | `tickets` | Quem está aguardando? |
| **Chamada** | `calls` | O atendimento de uma senha em um ponto |
| **Agendamento** | `appointments` | Uma reserva que vira senha no check-in |

## 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

> [!NOTE]
>
> **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:

| Estado | O que significa |
| - | - |
| `aguardando` | Na fila do ponto, ainda sem estação |
| `chamada` | Um operador chamou a senha para uma estação |
| `em_atendimento` | O atendimento começou na estação |
| `finalizada` | O atendimento daquele ponto terminou |

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**.

Voltar
Avançar

## 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.

> [!TIP]
>
> 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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.