Guia de Acesso às APIs da Plataforma Channel

Introdução

Este guia detalhado visa ajudar usuários avançados a configurar e acessar as APIs da Plataforma Channel de forma autônoma, garantindo que você possa realizar operações com segurança e eficiência. Abaixo, você encontrará um passo a passo desde o acesso à administração do Channel até a utilização dos tokens de acesso para consumo das APIs.

O uso das APIs da plataforma é destinado a profissionais com conhecimento técnico avançado e familiaridade com a integração de sistemas por meio de APIs. É fundamental que o usuário que vá utilizar essas funcionalidades tenha uma compreensão sólida de como APIs funcionam e como implementá-las corretamente. Ressaltamos que o suporte ao usuário não é o canal apropriado para aprendizado sobre o uso de APIs. Portanto, recomendamos que, caso haja necessidade de suporte técnico, apenas profissionais qualificados e experientes sejam responsáveis por essa interface, garantindo assim a melhor utilização dos recursos e eficiência no atendimento.

A autorização para o uso das APIs deve ser formalmente concedida pelo representante responsável no contrato com a JExperts, pois o acesso permitirá visualizar e manipular todos os dados da plataforma.

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.

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.
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.
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.

Recomendação de Segurança: Sempre trate o Client Secret como um dado altamente confidencial. Compartilhar esse segredo pode comprometer a segurança da sua aplicação.

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:

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.
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.
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.
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:

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:
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>'
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:
curl --location --request GET '<URL-API>' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <SEU_TOKEN_DE_ACESSO>' \ --data '{}'
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:

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