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

# Referência da API de leitura

> Os 12 endpoints de leitura do QSmartHub e os campos de resposta de cada recurso: unidades, pontos, estações, senhas, chamadas e agendamentos.

A v1 expõe seis recursos, cada um com uma **listagem** (`GET /recurso`, paginada) e um **detalhe** (`GET /recurso/{id}`). Todos exigem `Authorization: Bearer qsh_live_...` e o escopo do recurso. Esta página lista os campos de cada resposta. Os identificadores (`id` e todos os `*_id`) são ULIDs públicos; as datas vêm em UTC com `Z`.

> [!NOTE]
>
> Uma **referência interativa** com Playground (gerada a partir da especificação OpenAPI do QSmartHub) está sendo finalizada. Até lá, esta página descreve o contrato completo de cada recurso.

## Unidades

`GET /units` · `GET /units/{id}` · escopo `units:read`

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | string | Identificador da unidade (ULID) |
| `name` | string | Nome da unidade |
| `code` | string | Código interno |
| `status` | string | `ativa` ou `inativa` |
| `timezone` | string | Fuso horário (ex.: `America/Sao_Paulo`) |
| `city` | string | Cidade |
| `state` | string | UF |

## Pontos de atendimento

`GET /service-points` · `GET /service-points/{id}` · escopo `service-points:read`

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | string | Identificador do ponto (ULID) |
| `name` | string | Nome do ponto (ex.: Bebidas, Retirada) |
| `unit_id` | string | Unidade a que pertence |
| `status` | string | `active` ou `inactive` |

## Estações

`GET /stations` · `GET /stations/{id}` · escopo `stations:read`

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | string | Identificador da estação (ULID) |
| `name` | string | Nome (ex.: Caixa 1) |
| `location` | string | Localização física |
| `state` | string | Estado operacional (ex.: disponível, pausada) |
| `unit_id` | string | Unidade a que pertence |
| `service_point_id` | string | Ponto de atendimento vinculado |

## Senhas

`GET /tickets` · `GET /tickets/{id}` · escopo `tickets:read`

A listagem aceita o filtro `?status=`. Com o escopo `customers:read`, a resposta inclui um bloco `customer` com o nome do visitante.

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | string | Identificador da senha (ULID) |
| `number` | integer | Número exibido ao cliente |
| `status` | string | Situação da senha |
| `priority` | string | `comum` ou `prioritario` |
| `origin` | string | Canal de entrada (`qrcode`, `totem`, `agendamento`) |
| `unit_id` | string | Unidade |
| `service_point_id` | string | Ponto de atendimento |
| `service_id` | string | Serviço |
| `created_at` | string | Criação (UTC) |
| `called_at` | string | Última chamada (UTC), ou `null` |
| `finished_at` | string | Finalização (UTC), ou `null` |
| `service_seconds` | integer | Tempo de atendimento em segundos, ou `null` |
| `customer` | object | `{ name }`, apenas com `customers:read` |

## Chamadas

`GET /calls` · `GET /calls/{id}` · escopo `calls:read`

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | string | Identificador da chamada (ULID) |
| `ticket_id` | string | Senha atendida |
| `service_point_id` | string | Ponto de atendimento |
| `station_id` | string | Estação, ou `null` antes da chamada |
| `operator_id` | string | Operador, ou `null` |
| `state` | string | `aguardando`, `chamada`, `em_atendimento`, `finalizada` |
| `outcome` | string | Desfecho, ou `null` |
| `recalls` | integer | Quantas rechamadas |
| `queued_at` | string | Entrada na fila (UTC) |
| `called_at` | string | Chamada (UTC), ou `null` |
| `recalled_at` | string | Última rechamada (UTC), ou `null` |
| `ended_at` | string | Encerramento (UTC), ou `null` |
| `service_seconds` | integer | Duração do atendimento em segundos, ou `null` |

## Agendamentos

`GET /appointments` · `GET /appointments/{id}` · escopo `appointments:read`

Com o escopo `customers:read`, a resposta inclui um bloco `customer` com nome, e-mail e telefone.

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | string | Identificador do agendamento (ULID) |
| `status` | string | Situação do agendamento |
| `origin` | string | Origem |
| `unit_id` | string | Unidade |
| `service_id` | string | Serviço |
| `service_point_id` | string | Ponto de atendimento |
| `ticket_id` | string | Senha gerada no check-in, ou `null` |
| `scheduled_for` | string | Data e hora locais do atendimento |
| `customer` | object | `{ name, email, phone }`, apenas com `customers:read` |


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