Skip to main content
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

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). 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.
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:

3. Faça a primeira requisição

Liste as unidades da sua conta. Esta é uma chamada de leitura, sem corpo:
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):
Controle a página com ?page= e o tamanho com ?per_page= (padrão 25, máximo 100). Veja Visão geral da API 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:
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: Ao ultrapassar o limite, a API responde 429. Veja como ler os cabeçalhos de limite em Visão geral da API.