Tokens de API


O que é a área de Integrações?

A seção de Integrações é o seu centro de controle para conectar a plataforma Omnichannel a outras ferramentas e sistemas que sua empresa utiliza e também fazer consultas próprias da plataforma.

Para que essa comunicação aconteça de forma segura, é necessário criar uma "senha" especial, conhecida como Chave de API ou Bearer Token. Pense nela como uma chave de acesso exclusiva que autoriza um sistema externo a acessar ou enviar informações para sua conta Omnichannel, sem precisar de seu login e senha de usuário.

Passo a Passo para Gerar sua Chave de API

Etapa 1: Localize a seção de Integrações

Acesse o menu principal da nossa plataforma e clique na opção "Integrações". O GIF abaixo demonstra o caminho exato.


Etapa 2: Inicie o cadastro de uma nova chave

Você verá a tela de gerenciamento de suas chaves de API. Para adicionar uma nova, clique no botão "Criar Novo".


Etapa 3: Identifique sua chave

No formulário que aparecer, dê um nome e uma descrição para sua chave.

  • Nome: Escolha um nome claro e objetivo.

    • Exemplo bom: integracoes_api_convert

    • Exemplo ruim: chave123

    • O nome deve sempre ser em minúsculo

Isso é fundamental para que você possa gerenciar suas integrações no futuro, sabendo exatamente qual chave pertence a qual sistema.


Etapa 4: Copie e salve seu Token Gerado

Pronto! Sua chave de acesso (Bearer Token) foi criada e será exibida na tela.


ALERTA DE SEGURANÇA

Este é o único momento em que o token completo será exibido. Copie-o e guarde-o em um gerenciador de senhas ou em outro local seguro. Uma vez que você saia desta tela, não será possível recuperar o mesmo token. Caso o perca, você precisará revogar a chave antiga e gerar uma completamente nova.



Próximos Passos

Com o seu Bearer Token em mãos, você está pronto para autenticar suas requisições na nossa API. Para saber quais funcionalidades estão disponíveis e como utilizá-las, por favor, consulte a documentação completa da API Omnichannel.


Como Revogar e Substituir uma Chave de API

Pode haver momentos em que você precise substituir uma chave de API, seja por motivos de segurança (como a suspeita de que a chave foi exposta) ou simplesmente para renovar suas credenciais. O ato de revogar uma chave a torna permanentemente inativa.

Siga os passos abaixo para revogar uma chave existente e gerar uma nova em seu lugar:

  1. Navegue até Integrações e localize a chave que deseja substituir. A identificação será feita pelo nome que você deu a ela durante a criação.

  2. Ao lado do nome da chave, clique no ícone de chave ou "Gerar token" (🔑).

  3. O sistema exibirá uma mensagem de confirmação para garantir que a ação não seja acidental. Leia com atenção e, se tiver certeza, confirme a operação.


    AÇÃO IRREVERSÍVEL E DE ALTO IMPACTO

    • Ao confirmar, o token antigo será imediatamente e permanentemente invalidado.

    • Qualquer sistema, aplicação ou serviço que estiver utilizando o token antigo perderá o acesso na mesma hora.

    • Um novo token será gerado e exibido na tela. Assim como na criação inicial, você deve copiá-lo e guardá-lo em local seguro, pois ele não será mostrado novamente.

    • Você precisará atualizar a nova chave em todos os sistemas que utilizavam a antiga para restaurar a integração.

Após a confirmação, o novo token será apresentado. Certifique-se de atualizar suas aplicações com esta nova credencial para que a comunicação com a API Omnichannel continue funcionando normalmente.



Caso de uso

Requisição para o endpoint de departamentos

Devemos substituir “/%7BserverUrl%7D“ por chat<nomedaempresa>

curl --request GET \
  --url https:///%7BserverUrl%7D.convert.app.br/api/v1/livechat/department \
  --header 'Content-Type: application/json'


1. Método da Requisição (HTTP Method)

  • O que é: Define a ação que desejamos executar no recurso. Neste caso, GET é utilizado para consultar ou obter dados, sem alterá-los. Outros métodos comuns são POST (criar), PUT (atualizar) e DELETE (remover).

2. Endpoint (URL da Requisição)

  • O que é: É o "endereço" específico do recurso que queremos acessar na API. Ele indica exatamente quais dados estamos solicitando. No exemplo, estamos acessando o recurso livechat/department para obter a lista de departamentos.

3. Cabeçalho de Autorização (Authorization Header)

  • O que é: Uma parte dos "cabeçalhos" (headers) da requisição, usada para enviar as credenciais de autenticação. É aqui que informamos a chave da API (neste caso, um Bearer Token) que prova que temos permissão para fazer essa solicitação.

4. Corpo da Resposta (Response Body)

  • O que é: São os dados que a API retorna após a nossa requisição ser processada com sucesso. O formato comum para esses dados é o JSON, como mostrado na imagem, que organiza a informação de forma estruturada e legível para sistemas.

Para consultar os departamentos, nós executamos uma requisição usando o método (1) GET no endpoint específico (2) /livechat/department. Para garantir o acesso seguro, enviamos nossa chave de autenticação no cabeçalho de autorização (3). Como resultado, a API nos devolveu os dados dos departamentos no corpo da resposta (4).