Autenticação e chaves
A API reconhece quem chama por uma chave secreta, enviada em toda requisição no cabeçalho Authorization: Bearer <chave>. Cada chave pertence a uma organização e só faz o que os seus escopos permitem.
curl "https://chat.forsi.com.br/api/v1/me" -H "Authorization: Bearer $FORSI_CHAVE"A chave tem o formato fcv2_live_<id>_<segredo> (nos exemplos, fcv2_live_EXAMPLE). Guardamos só um resumo (sha256) e não temos como mostrar a chave de novo: perdeu, crie outra.
Criar uma chave#
- Entre como dono ou gestor em Configurações → API e webhooks e toque em Nova chave.
- Dê um nome que diga qual integração vai usar a chave (
ERP,site,n8n) e marque só os escopos de que ela precisa. - Se quiser, defina a validade e a lista de IPs que podem usar a chave.
- Copie a chave na hora e guarde no cofre de segredos ou numa variável de ambiente do servidor. Ela não aparece de novo.
O que a API confere em cada chamada#
A conferência segue esta ordem, e a primeira que falhar responde:
| Ordem | O que confere | Se falhar |
|---|---|---|
| 1 | Conexão https | 403 https_obrigatorio |
| 2 | Sem cabeçalho Origin (a chamada não vem de navegador) | 403 origem_nao_permitida |
| 3 | A chave existe, não foi revogada, não venceu e o IP está na lista | 401 nao_autorizado, sempre igual, sem dizer o motivo |
| 4 | Plano com o módulo API e assinatura em dia | 403 modulo_fora_do_plano ou 403 assinatura_bloqueada |
| 5 | Escopo da rota | 403 escopo_insuficiente (o escopo que faltou vem em detalhe) |
| 6 | Limite por minuto | 429 limite_excedido, com Retry-After |
Muitas tentativas com chave errada do mesmo endereço bloqueiam esse endereço por alguns minutos: 429 muitas_falhas, com Retry-After.
Escopos, validade e IPs#
- Cada chave tem escopos (o que pode fazer; veja Escopos e planos). Peça só os que a integração usa.
- A chave pode ter validade (vence sozinha) e uma lista de IPs permitidos.
- Revogar corta na hora.
Trocar a chave sem parar o sistema#
Use Trocar a chave: sai uma chave nova e a antiga continua valendo pelo tempo que você escolher (até 7 dias). Coloque a nova no servidor, confira que as chamadas passam e deixe a antiga vencer.
Quem sou eu#
GET /me aceita qualquer chave válida e mostra a organização, os escopos e a validade da chave, os limites da organização e as caixas (WhatsApps) com o estado da conexão. É a melhor primeira chamada para conferir a configuração.
Perguntas frequentes#
Perdi a chave. Dá para ver de novo?#
Não. Guardamos só um resumo (sha256), que não permite recuperar o texto da chave. Crie outra e revogue a perdida.
Por que o 401 não diz o motivo?#
De propósito. Chave ausente, errada, revogada, vencida ou fora da lista de IPs recebem a mesma resposta, para não ajudar quem tenta adivinhar chaves. Confira no app se a chave está ativa, se não venceu e se o IP do seu servidor está na lista.
Posso usar a mesma chave em duas integrações?#
Pode, mas não é bom. Com uma chave por integração dá para revogar uma sem parar a outra, e a auditoria mostra o nome da chave que fez cada mudança.
A chave vale para outra organização?#
Não. Cada chave pertence a uma organização. Ids de outra organização respondem 404, como se não existissem.