Page Comparison

Introdução

...

1. Pré-requisitos

Para acessar as APIs da Plataforma Channel, é necessário ter uma credencial de integração cadastrada. As credenciais, incluindo o Client ID e o Client Secret, devem ser solicitadas diretamente ao time de suporte da JExperts, que será responsável por fornecê-las - suporte_channel@jexperts.com.br

Uma vez que a aplicação tenha sido criada, a plataforma irá gerar dois componentes essenciais para o acesso à API: o Client Secret e o Client ID.

1. Client ID:

   • Este é o identificador único da sua aplicação e será utilizado em todas as chamadas à API para autenticar sua aplicação junto ao sistema.

2. Client Secret:

   • Este é o segredo da sua aplicação, utilizado junto com o Client ID para gerar tokens de acesso. Atenção: O Client Secret é exibido apenas uma vez. Após fechar a janela, ele se tornará indecifrável.

   • Importante: Copie o Client Secret e o armazene em um local seguro (por exemplo, um gerenciador de senhas). Nunca compartilhe o Client Secret publicamente.

3. Chave Privada (Private Key):

   • Algumas APIs podem exigir autenticação com chave privada. Caso isso seja necessário, a plataforma também disponibilizará uma chave privada (Private Key) que você deve salvar junto com o Client ID e o Client Secret.
     

2. Gerenciamento de Tokens de Acesso

As APIs da Plataforma Channel utilizam um sistema de tokens de acesso para realizar a autenticação e a autorização de requisições. Isso significa que, ao acessar as APIs, a aplicação precisa de um token válido para provar que tem permissão para usar os recursos disponíveis. Os tokens permitem que sua aplicação interaja com as APIs de maneira segura e controlada.

O que é um Token de Acesso?

Um token de acesso é como um "bilhete de entrada" digital que contém informações sobre quem está acessando o sistema e quais permissões essa pessoa ou aplicação tem. Ele serve para identificar o aplicativo que está solicitando o acesso aos dados da API e garantir que ele tem os privilégios corretos.

• O token de acesso contém detalhes como a identidade da aplicação e os privilégios de acesso, permitindo que a API saiba exatamente quem está solicitando os dados e o que essa aplicação pode ou não fazer.

• Em sistemas que utilizam padrões de autenticação como OAuth ou OpenID Connect, como é o caso da Plataforma Channel, os tokens são usados para evitar que o usuário precise autenticar a cada requisição. Depois de obter o token, você o utiliza para todas as chamadas subsequentes até que ele expire.

Como os Tokens de Acesso Funcionam?

Agora que você já sabe o que é um token de acesso, veja como ele funciona na prática:

1. Geração do Token:

   • Após criar sua aplicação e obter o Client ID e o Client Secret, você usará essas credenciais para solicitar um token de acesso. Isso é feito através de uma requisição à API de autenticação da plataforma.

2. Validade do Token:

   • Uma vez gerado, o token de acesso tem uma validade limitada, que no caso da Plataforma Channel é de 600 segundos (ou seja, 10 minutos). Isso significa que, após 10 minutos, o token expira e você precisará gerar um novo para continuar acessando os recursos da API.

3. Renovação do Token:

   • Quando o token expirar, será necessário fazer outra requisição para obter um novo token de acesso. Isso garante que o sistema continue verificando se a aplicação ainda tem permissão para acessar os dados.

4. Formato do Token:

   • Os tokens de acesso gerados pela Plataforma Channel estão no formato JSON Web Token (JWT). Esse formato é muito utilizado em sistemas modernos, pois é leve (compacto), seguro e fácil de integrar com diferentes linguagens e plataformas.

Exemplo de Uso do Token com cUrl

Aqui está um exemplo prático de como o token de acesso funciona em uma requisição de API:

1. Solicitação do Token:
   Você faz uma solicitação à API de autenticação com o Client ID e o Client Secret. Em troca, o sistema devolve um token de acesso válido por 600 segundos.

   Exemplo de requisição:

   Code Block
   language bash
   curl --location 'https://<AMBIENTE>.jexperts.cloud/api/oauth/token' \ --header 'content-type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'client_id=<SEU_CLIENT_ID>' \ --data-urlencode 'client_secret=<SEU_CLIENT_SECRET>'

2. Utilizando o Token:
   Depois de obter o token, você o incluirá no cabeçalho das suas próximas requisições para acessar os dados da API.

   Exemplo de requisição com o token:

   Code Block
   language bash
   curl --location --request GET '<URL-API>' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <SEU_TOKEN_DE_ACESSO>' \ --data '{}'

3. Renovando o Token:
   Quando o token expirar (após 600 segundos), você deverá fazer uma nova solicitação para obter outro. Esse processo garante que o acesso seja sempre controlado e seguro.

Exemplo de Uso do Token com PowerBI

Abaixo o código de uma função para retorno dos dados escrita em Linguagem M (Power Query).

(name as text) => let
    Fonte = Json.Document(
        Web.Contents(
            apiAddress,
            [
                // Relative path + paramenter ("name")
                RelativePath = "public/" & name,
                Headers=[
                    //#"x-access-token" = getToken()
                    Authorization = "Bearer " & getToken()
                ]
            ]
        )
    )
in
    Fonte

Na função:

• parâmetros externos:

  • name: nome da API que se deseja. Neste exemplo “public“ está sendo concatenado em RelativePath, portanto este atributo não deve contê-lo. Exemplo: se o nome da função fosse get ou getAPI, então a chamada será respectivamente get(“projects”) ou getAPI(“projects”).

• parâmetros internos:

  • apiAddress: é o endereço URL das APIs. Para o Channel é: https://api-bi.jexperts.com.br.

  • getToken(): esta é uma função gerada através do exemplo em Token - Exemplos para Power BI. A função retorna o token necessário a cada solicitação de dados.

Nomeando a função citada como getJSON, um exemplo de consulta baseada no swagger para obter public/projects fica:

= getJSON(“projects”)

Boas Práticas de Segurança

• Armazene as credenciais de forma segura: O Client ID e o Client Secret devem ser protegidos, já que são as "chaves" que permitem que sua aplicação acesse o sistema. Nunca compartilhe essas informações em público.

• Atualize regularmente: Tokens expiram rapidamente por motivos de segurança. Planeje sempre a renovação para garantir o funcionamento contínuo da aplicação sem interrupções.

• Use ferramentas confiáveis: Gerenciadores de senhas e ambientes seguros devem ser utilizados para armazenar essas informações.

8. Links úteis

Documentação Swagger da API da Plataforma Channel

Tutoriais da Microsoft sobe o Uso de Tokens

Perguntas Frequentes sobre API