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

# Visão geral da API de leitura

> Escopo da v1 somente leitura do QSmartHub: versionamento, paginação, formato de erro padronizado e limites de requisição por plano.

A API de Integrações do QSmartHub é uma API REST de **leitura somente**. Esta página reúne as regras que valem para todos os endpoints: versionamento, paginação, formato de erro e limites de requisição.

## Somente leitura

Todos os endpoints da v1 são `GET`. Não existe `POST`, `PUT`, `PATCH` nem `DELETE`: você não cria nem altera registros por esta versão. Para **reagir a mudanças** na operação, use [webhooks](https://developers.qsmarthub.com/webhooks.md) em vez de consultar a API em intervalos curtos (polling). O QSmartHub avisa seu sistema quando algo acontece, o que é mais barato e mais rápido do que ficar perguntando.

## Versionamento

A versão faz parte do caminho: `/api/integrations/v1`. Dentro da `v1`, só entram mudanças **aditivas** (novos campos, novos recursos). Remover ou renomear um campo exigiria uma nova versão. Escreva seu código para **ignorar campos que não conhece**, e nada quebra quando a API cresce.

## Autenticação

Toda requisição leva o cabeçalho `Authorization: Bearer qsh_live_...`. O token define a empresa, os escopos e, opcionalmente, as unidades visíveis. Veja [Começando](https://developers.qsmarthub.com/comecando.md) para gerar e usar a chave.

## Paginação

Os endpoints de listagem (`index`) são paginados. Controle a página e o tamanho por query:

**page** `number` (default: 1)

Número da página.

**per\_page** `number` (default: 25)

Itens por página. Entre 1 e 100. Fora dessa faixa, a API responde `400`.

A resposta traz os itens em `data` e a navegação em `links` e `meta`:

```json theme={null}
{
  "data": [ /* ... */ ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "from": 1, "last_page": 4, "per_page": 25, "to": 25, "total": 92 }
}
```

## Formato de erro

Os erros seguem o padrão **RFC 9457** (`application/problem+json`). O corpo sempre tem um `code` estável, que é o campo para o seu código decidir o que fazer:

```json theme={null}
{
  "type": "https://qsmarthub.com/api/problemas/insufficient_scope",
  "title": "Escopo insuficiente",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "Esta chave não tem o escopo 'tickets:read'.",
  "request_id": "c0ffee00-0000-0000-0000-000000000000"
}
```

Os códigos possíveis:

| `code` | HTTP | Quando acontece |
| - | - | - |
| `unauthenticated` | 401 | Sem cabeçalho `Authorization`, ou chave inválida |
| `token_revoked` | 401 | A chave foi revogada |
| `token_expired` | 401 | A chave passou da validade |
| `insufficient_scope` | 403 | A chave não tem o escopo exigido pela rota |
| `plan_required` | 403 | O plano da conta não inclui a API, ou a chave está suspensa |
| `not_found` | 404 | O recurso não existe, ou não é da sua empresa |
| `validation_failed` | 422 | Parâmetro inválido na requisição |
| `rate_limited` | 429 | Limite de requisições por minuto excedido |

> [!TIP]
>
> Use o `request_id` da resposta ao relatar um problema ao suporte: ele identifica a requisição exata nos registros do QSmartHub.

## Limites de requisição

As requisições são limitadas **por minuto e por token**, conforme o plano (Business 300, Premium 600, Enterprise 1000). Toda resposta traz os cabeçalhos de limite:

| Cabeçalho | Significado |
| - | - |
| `X-RateLimit-Limit` | Teto de requisições no minuto |
| `X-RateLimit-Remaining` | Quantas ainda restam na janela atual |
| `Retry-After` | Segundos até poder tentar de novo (presente no `429`) |

Ao exceder o limite, a API responde `429` com `code` `rate_limited`. Respeite o `Retry-After` antes de repetir.

## Recursos

A v1 expõe seis recursos de leitura, cada um com uma listagem e um detalhe por `id`:

| Recurso | Endpoints | Escopo |
| - | - | - |
| Unidades | `GET /units`, `GET /units/{id}` | `units:read` |
| Pontos de atendimento | `GET /service-points`, `GET /service-points/{id}` | `service-points:read` |
| Estações | `GET /stations`, `GET /stations/{id}` | `stations:read` |
| Senhas | `GET /tickets`, `GET /tickets/{id}` | `tickets:read` |
| Chamadas | `GET /calls`, `GET /calls/{id}` | `calls:read` |
| Agendamentos | `GET /appointments`, `GET /appointments/{id}` | `appointments:read` |

O detalhe de cada recurso, com todos os campos de resposta, fica na [Referência da API](https://developers.qsmarthub.com/referencia.md).


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