Information
- OpenAPI version:
3.0.1
Visão geral
API pública do MSP Desk v1
Seção intitulada “API pública do MSP Desk v1”API REST pública do MSP Desk, para integração de sistemas externos. Toda requisição exige uma chave de API no cabeçalho Authorization: Bearer <chave>, no formato mspd_live_…, com o escopo exigido por cada operação (veja a extensão x-required-scope). Um escopo grupo:write inclui o grupo:read do mesmo grupo: a chave criada ou editada só com o :write fica gravada e exibida também com o :read. A API pública é habilitada por empresa. Enquanto ela não estiver habilitada, toda requisição é recusada com 403 public_api_disabled, mesmo com uma chave válida — salvo quando a MSP Works concede à empresa alguns escopos de leitura (escopos liberados por concessão): aí só esses escopos funcionam, e as demais operações respondem 403 scope_requires_public_api (marcar o escopo na chave não resolve; é preciso habilitar a API pública). As chaves continuam guardadas e voltam a funcionar por inteiro assim que a empresa for habilitada.
Limites de uso
| Camada | Taxa | Burst |
|---|---|---|
| Chave inválida por IP | 20/min | 20 |
| Empresa | 200/min | 40 |
| Chave | 100/min (50% da empresa) | 20 |
| Executar relatório | 10/min | 2 |
| Impressão/PDF | 10/min | 2 |
| Upload de anexo | 30/min | 5 |
| Concorrência por empresa | 5 em andamento | — |
O limite de chave inválida por IP só é consumido por requisições recusadas na autenticação: 401 (chave ausente, inválida, revogada, expirada ou inativa) e os 403 account_inactive e public_api_disabled. Uma chave aceita nunca é bloqueada pelas falhas de outros clientes no mesmo IP. Esgotado, a tentativa recusada seguinte recebe 429 com layer=ip no lugar do 401 ou do 403.
Toda resposta de uma requisição com chave válida traz os cabeçalhos RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset, referentes ao balde mais restritivo consumido (ou consultado) nessa requisição. O 401 e os 403 account_inactive (empresa inativa) e public_api_disabled (API pública não habilitada para a empresa) não os trazem, porque ainda não há balde de empresa ou chave a informar; o 429 com layer=ip traz os do balde de IP. Ao atingir o limite, a resposta é 429 com Retry-After (segundos até a próxima ficha) e o corpo indica a camada responsável no campo layer (ip, company, key, operation ou concurrency; quando layer=operation, o campo operation informa qual operação pesada — report, pdf ou upload).
Guias e referência da API pública
Authentication
Seção intitulada “Authentication”Chave de API da empresa (Configurações → Chaves de API), informada no cabeçalho Authorization: Bearer <chave>. O formato é mspd_live_….
Security scheme type: http
Bearer format: mspd_live_…