Sua chave de API
A chave de API identifica você para o LeadSim. Tudo o que um sistema fizer com ela vale como se você tivesse feito nas telas, com as suas permissões e em seu nome.
Onde fica
Há dois caminhos, e os dois mexem na mesma chave:
- Gestão da Conta › Configurações › Integração API, na barra lateral. A aba Chaves mostra todas as chaves da empresa, com um botão para gerar a sua. É também onde o administrador acompanha o uso.
- Seu nome (canto superior direito) › Integrações › API → Gerenciar. Abre a janela Chave de API, só com a sua chave: prefixo, validade, último uso e os botões Copiar chave, Gerar nova chave e revogar, além do histórico das chaves anteriores.
As duas opções aparecem só para perfis com o menu Integração API. Se você não vê nenhuma delas, veja Não vejo o menu Integração API.
Quem pode gerar chave
Qualquer usuário cujo perfil tenha o menu Integração API. Não há uma chave "da empresa": cada chave pertence a um usuário e herda as permissões dele nas telas.
Para liberar, o administrador abre o perfil em Administração › Perfis, marca o menu Integração API (ele fica em Gestão da Conta › Configurações) e salva. Ao desmarcar o menu, as chaves dos usuários desse perfil param de funcionar na hora (403 error_api_key_no_access) e voltam a funcionar se o menu for devolvido, sem precisar gerar outra.
Usuário dedicado para a integração
Crie um usuário só para a integração (por exemplo Integração ERP), com um perfil que tenha o menu Integração API e apenas os módulos que o sistema externo vai usar, e gere a chave logado nele.
- Contatos, oportunidades, propostas e contratos criados pela API ficam em nome desse usuário, e não de uma pessoa da equipe.
- A chave não cai quando a pessoa que a gerou sai da empresa ou troca de perfil.
- Como cada usuário tem uma chave ativa por vez, um usuário por sistema integrado permite revogar um sem derrubar o outro, e o limite de 300 requisições por minuto não é disputado.
Se o funil é restrito (cada vendedor vê só as próprias oportunidades), o usuário de integração só lista as oportunidades dele. Para o sistema externo enxergar o funil inteiro, use um perfil sem essa restrição ou libere o funil para o usuário de integração.
Gerar a chave
- Clique em + Gerar minha chave (ou Gerar nova chave, se já tem uma ativa).
- Dê um Nome que identifique onde a chave vai ser usada, por exemplo Integração com o ERP.
- Escolha a Validade: 7, 30, 90 ou 365 dias, ou Sem validade.
- Clique em Gerar chave.
O LeadSim mostra a chave (lsk_api_...) uma vez, com o botão de copiar e o link para este guia.
Ao escolher Sem validade, o LeadSim pergunta se você tem certeza: Manter validade volta para a lista de prazos e Usar sem validade confirma. Prefira um prazo e gere uma chave nova quando ele vencer. Se usar sem validade, revogue a chave assim que ela deixar de ser usada.
Uma chave ativa por vez
Cada usuário tem uma chave ativa. Gerar uma nova revoga a anterior na hora, com o motivo Substituída por nova chave. Se um sistema já usa a chave antiga, troque a chave nele antes de desligar o antigo, ou aceite a interrupção até a troca.
Para dois sistemas usarem chaves diferentes, use dois usuários. Veja a recomendação de um usuário dedicado de integração.
Copiar a chave de novo
Perdeu a chave antes de configurar o sistema? Clique em Copiar chave na linha da sua chave (aba Chaves) ou na janela Chave de API. Só o dono vê esse botão, e só enquanto a chave está ativa.
Chaves criadas antes de o LeadSim guardar a cópia cifrada não podem ser copiadas de novo. Se o botão não aparece, gere uma nova chave.
Revogar
Clique no ícone de revogar na linha da chave. A revogação vale na hora e não pode ser desfeita: a próxima requisição com aquela chave responde 401 error_api_key_revoked. A chave fica no histórico como Revogada.
O administrador da empresa também pode revogar a sua chave, na aba Chaves da tela Integração API.
Vencimento
Sete dias antes do vencimento, o LeadSim avisa por e-mail. Gere uma chave nova e troque no sistema integrado antes da data. Depois do vencimento a chave responde 401 error_api_key_expired. Chaves Sem validade não recebem esse aviso.
Quando a chave deixa de funcionar
| Situação | Resposta da API |
|---|---|
| Você gerou uma chave nova | A anterior responde 401 error_api_key_revoked |
| Você ou o administrador revogaram a chave | 401 error_api_key_revoked |
| A validade passou | 401 error_api_key_expired |
| O seu usuário foi desativado | 401 error_api_key_user_inactive |
| O seu perfil perdeu o menu Integração API | 403 error_api_key_no_access |
| A empresa não está ativa no LeadSim | 403 error_api_key_companie_inactive |
Os códigos completos estão em Autenticação e convenções.