Skip to main content
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 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 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:
number
default:"1"
Número da página.
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:

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:
Os códigos possíveis:
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: 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: O detalhe de cada recurso, com todos os campos de resposta, fica na Referência da API.