Somente leitura
Todos os endpoints da v1 sãoGET. 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çalhoAuthorization: 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:
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:
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 porid:
O detalhe de cada recurso, com todos os campos de resposta, fica na Referência da API.