Criar uma chave
A chave é criada pelo provedor, dentro do sistema:
- Acesse Configurações → API pública e clique em Nova chave.
- Dê um nome que identifique o sistema que vai usá-la (ex.: “Chatbot da Empresa X”).
- Marque só as permissões necessárias. Se quiser, restrinja os IPs de origem, ajuste o limite por minuto e defina uma validade.
- Copie a chave exibida. Ela começa com
wsp_e só é mostrada uma vez. Se for perdida, revogue e crie outra.
Por padrão, apenas usuários com perfil Administrador criam e revogam chaves. A permissão pode ser liberada para outros perfis no card de Permissões, em Configurações → Chaves da API pública.
Autenticação
Envie a chave em toda requisição, no cabeçalho Authorization:
Authorization: Bearer wsp_SUA_CHAVE_AQUISe a sua ferramenta não permitir esse cabeçalho, use X-API-Key:
X-API-Key: wsp_SUA_CHAVE_AQUIChave inexistente, revogada ou expirada recebe 401. Chamada de um IP fora da lista autorizada recebe 403.
Endereço da API
A API fica no mesmo endereço do painel do provedor, seguido de /api/v1. O endereço
exato aparece em Configurações → API pública, com botão para copiar.
https://painel.seuprovedor.com.br/api/v1A API é feita para ser chamada de servidor para servidor. Não use a chave em código que roda no navegador ou em aplicativo instalado no celular do assinante: qualquer pessoa conseguiria lê-la. Nesses casos, chame a API a partir do seu backend. Chamadas feitas direto do navegador de outro domínio são bloqueadas.
Permissões
Cada rota exige uma permissão, marcada pelo provedor ao criar a chave:
| Permissão | Libera |
|---|---|
clientes:leitura | Consultar clientes, contratos e a conexão do contrato. |
financeiro:leitura | Consultar faturas e segunda via. |
contratos:desbloqueio | Aplicar desbloqueio de confiança. |
chamados:leitura | Consultar chamados e o histórico. |
chamados:escrita | Abrir, comentar e atualizar chamados. |
planos:leitura | Consultar planos ativos. |
pre_cadastro:escrita | Gerar link de pré-cadastro para novos clientes. |
Os webhooks não usam a chave: são cadastrados pelo provedor e assinados com um segredo próprio.
Limites de uso
Cada chave tem um limite de requisições por minuto, definido pelo provedor na criação (padrão 120/min, até 1.200/min). Toda resposta informa o consumo:
| Cabeçalho | Significado |
|---|---|
X-RateLimit-Limit | Requisições permitidas por minuto. |
X-RateLimit-Remaining | Quantas ainda restam na janela atual. |
X-RateLimit-Reset | Segundos até a janela reiniciar. |
Retry-After | Só na resposta 429: segundos para tentar de novo. |
Ao receber 429, aguarde o tempo de Retry-After antes de repetir. Não repita em loop.
Revogar uma chave
O provedor revoga a chave em Configurações → API pública. A revogação vale na hora: a
próxima chamada recebe 401 chave_revogada. Uma chave revogada não volta a funcionar; é preciso criar outra.