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

# Começando com a API do QSmartHub

> Gere sua chave qsh_live_, autentique com Bearer e faça a primeira requisição de leitura à API de Integrações do QSmartHub.

Este guia leva você da chave de API à primeira resposta `200` da API de Integrações do QSmartHub. Toda a v1 é de leitura e autenticada por um token Bearer que começa com `qsh_live_`.

## Pré-requisitos

> [!NOTE]
>
> A API está incluída nos planos **Business** e superiores. A **avaliação de 14 dias** também libera a API e os webhooks. Nos planos Básico e Profissional, a chave existe mas a API responde `403 plan_required`.

Para **gerar** uma chave, é preciso administrar a conta (perfil de proprietário ou administrador). Para **consumir** a API, basta ter a chave em mãos.

## 1. Gere sua chave

**1. Abra Integrações › Chaves de API**

No painel do QSmartHub, abra a área de **Integrações** e a aba **Chaves de API**.

**2. Crie a chave e escolha os escopos**

Dê um nome à chave e selecione os escopos de leitura que ela precisa (veja [Escopos](#escopos)). Opcionalmente, limite a chave a unidades específicas e defina uma data de validade.

**3. Copie o segredo (ele aparece uma única vez)**

O segredo começa com `qsh_live_` e **não é exibido de novo**. Guarde-o num cofre de segredos. Se perder, revogue a chave e gere outra.

> [!WARNING]
>
> Trate a chave como uma senha. Ela não deve aparecer em código versionado, em URLs nem no navegador. Revogar uma chave tem efeito imediato na próxima requisição.

## 2. Autentique

Envie o segredo no cabeçalho `Authorization`, com o esquema `Bearer`, em toda requisição:

```http theme={null}
Authorization: Bearer qsh_live_sua_chave_aqui
```

## 3. Faça a primeira requisição

Liste as unidades da sua conta. Esta é uma chamada de leitura, sem corpo:

```bash theme={null}
curl https://app.qsmarthub.com/api/integrations/v1/units \
  -H "Authorization: Bearer qsh_live_sua_chave_aqui"
```

> [!NOTE]
>
> O caminho `/api/integrations/v1` é definitivo. O **host de produção** ainda será confirmado pela equipe do QSmartHub; ajuste-o quando receber a URL oficial.

A resposta é paginada e tem o formato abaixo (dados fictícios, no mesmo shape real):

```json theme={null}
{
  "data": [
    {
      "id": "01JQ8Z3K7M9W0X1Y2Z3A4B5C6D",
      "name": "Loja Centro",
      "code": "CENTRO",
      "status": "ativa",
      "timezone": "America/Sao_Paulo",
      "city": "São Paulo",
      "state": "SP"
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": null },
  "meta": { "current_page": 1, "from": 1, "last_page": 1, "per_page": 25, "to": 1, "total": 1 }
}
```

Controle a página com `?page=` e o tamanho com `?per_page=` (padrão 25, máximo 100). Veja [Visão geral da API](https://developers.qsmarthub.com/visao-geral-api.md) para paginação, erros e limites em detalhe.

## Escopos

Cada chave carrega um conjunto de escopos de leitura. Uma requisição a um recurso sem o escopo correspondente é recusada. Os escopos de leitura são:

| Escopo | Libera |
| - | - |
| `units:read` | Unidades |
| `service-points:read` | Pontos de atendimento |
| `stations:read` | Estações |
| `tickets:read` | Senhas |
| `calls:read` | Chamadas |
| `appointments:read` | Agendamentos |
| `customers:read` | Dados pessoais do cliente (nome, e-mail, telefone) nas senhas e agendamentos |

> [!WARNING]
>
> `customers:read` é o único escopo que expõe dados pessoais, e sempre num bloco `customer` separado. Conceda-o apenas quando a integração realmente precisar desses dados.

## Isolamento por empresa e por unidade

Seu token pertence a **uma empresa**, e a API nunca devolve dados de outra. Um recurso de outra empresa, ou um `id` que não existe na sua, responde `404` (nunca `403`): a API não revela a existência de registros que não são seus.

Além disso, uma chave pode ser **limitada a unidades específicas**. Nesse caso ela só enxerga os dados dessas unidades, mesmo que a conta tenha outras.

## Limites por plano

As requisições são limitadas por minuto, por token, conforme o plano:

| Plano | API de leitura | Webhooks | Requisições por minuto |
| - | - | - | - |
| Básico | Não | Não | 0 |
| Profissional | Não (configurável) | Não | 60 |
| Business | Sim | Sim | 300 |
| Premium | Sim | Sim | 600 |
| Enterprise | Sim | Sim | 1000 |

Ao ultrapassar o limite, a API responde `429`. Veja como ler os cabeçalhos de limite em [Visão geral da API](https://developers.qsmarthub.com/visao-geral-api.md).


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