# Chaves de Acesso

A Chave de Acesso é a credencial utilizada para acessar os recursos protegidos do cliente. E essa chave representa a autorização emitida pelo cliente no servidor de autorização do Tray Commerce.

### Como obter a Chave de Acesso

Para que a chave de acesso seja gerada corretamente e você parceiro, consiga utilizar a API da Tray é necessário **cumprir todos os requisitos abaixo**:

**1**. O [registro do aplicativo](https://partners.tray.com.br/loja-de-aplicativos/comece-por-aqui/ponto-de-partida#registro-do-aplicativo) deve ter sido liberado pelo setor de parcerias

**2**. Após a liberação, você precisa ter recebido um e-mail do setor de Parcerias com as chaves <mark style="color:red;">**`consumer_key`**</mark> e <mark style="color:red;">**`consumer_secret`**</mark> que são únicas para cada aplicativo

**3**. Realize um dos procedimento abaixo para gerar o código de autorização <mark style="color:red;">**`code`**</mark> do aplicativo, de acordo com o caso específico do seu aplicativo:

* [Como gerar o code para Aplicativos em Geral](#como-gerar-o-code-para-aplicativos-em-geral)
* [Como gerar o code para Aplicativos com Callback](#como-gerar-o-code-para-aplicativos-com-callback)

{% hint style="danger" %} <mark style="color:red;">**Atenção!**</mark>\
A chave **`code`** é única para cada loja.
{% endhint %}

**4**. Com o <mark style="color:red;">**`code`**</mark> do aplicativo deve ser Gerada a **Chave de Acesso** realizando uma requisição para a [**API de Autorização**](https://partners.tray.com.br/loja-de-aplicativos/autorizacao-e-autenticacao/broken-reference). O retorno dessa API gera o <mark style="color:red;">**`access_token`**</mark> que é a chave de acesso necessária para realizar as requisições desejadas.

{% hint style="info" %}
O retorno da [API de Gerar Chave de Acesso](https://partners.tray.com.br/loja-de-aplicativos/autorizacao-e-autenticacao/broken-reference) possui uma data de expiração das chaves e, quando expirado elas devem ser [atualizadas](#como-atualizar-a-chave-de-acesso).
{% endhint %}

### Como atualizar a Chave de Acesso

Quando as chaves de acesso estiverem expiradas, ou seja, tiver excedido o prazo do campo **`date_expiration_access_token`** será necessário realizar o procedimento de atualização.

Para isto utilize a [API de Atualizar Chave de Acesso](https://partners.tray.com.br/loja-de-aplicativos/autorizacao-e-autenticacao/broken-reference), que gera um novo <mark style="color:red;">**`access_token`**</mark> para continuar realizando requisições nas APIs.

## Como gerar o <mark style="color:red;">**`code`**</mark> para Aplicativos em Geral

Com as chaves <mark style="color:red;">**`consumer_key`**</mark> e <mark style="color:red;">**`consumer_secret`**</mark> em mãos para obter o **`code`** acesse a sua loja e siga os passos abaixo.

1\. No menu lateral esquerdo clique em **Aplicativos**

![imagem](https://developers.tray.com.br/images/aplicativo1-d4be8082.png)

2\. Clique em **Instalar novos aplicativos**

![imagem](https://developers.tray.com.br/images/aplicativo2-ea756503.png)

3\. Procure pelo seu aplicativo e clique em **Instalar aplicativo** depois clique em **Autorizar**

![imagem](https://developers.tray.com.br/images/aplicativo3-bbacf148.png)

4\. O painel com o code será exibido em seguida, mas caso não seja exibido, acesse no painel lateral esquerdo **Aplicativos**, depois procure pelo aplicativo, e clique em **Acessar** que o code será exibido<br>

![](https://developers.tray.com.br/images/code-3f8af340.png)

Salve o **`code`** do aplicativo em um documento seguro no seu computador e realize a [4° etapa](#como-obter-a-chave-de-acesso) para [**Gerar a Chave de Acesso**](https://partners.tray.com.br/loja-de-aplicativos/autorizacao-e-autenticacao/broken-reference).

## Como gerar o <mark style="color:red;">**`code`**</mark> para Aplicativos com Callback

Com as chaves <mark style="color:red;">**`consumer_key`**</mark> e <mark style="color:red;">**`consumer_secret`**</mark> em mãos para obter o **`code`** acesse a sua loja e siga os passos abaixo.&#x20;

O vídeo abaixo explica o processo de autorização de um aplicativo com a URL de Callback:

{% embed url="<https://www.loom.com/share/0b71a97616de4bb580fa018a2507c4df>" %}
&#x20;<br>
{% endembed %}

### Passo 1: Instale seu Aplicativo

1\. No menu lateral esquerdo clique em **Aplicativos**

![imagem ](https://developers.tray.com.br/images/aplicativo1-d4be8082.png)

2\. Clique em **Instalar novos aplicativos**

![imagem](https://developers.tray.com.br/images/aplicativo2-ea756503.png)

3\. Procure pelo seu aplicativo

![imagem](https://developers.tray.com.br/images/aplicativo3-bbacf148.png)

4\. Clique em **Instalar aplicativo**

![](https://3009472676-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKiK39PgUN2ktE5HkETqo%2Fuploads%2F4ixwzkIOriQzPeIDOU8Q%2Fimage.png?alt=media\&token=5e182250-2e38-40a9-a9b4-e7aae712129b)

### Passo 2: Configure a Landing Page para URL de Callback

Com o aplicativo instalado, você será redirecionado para **URL de Callback que deve ter sido informada no cadastro do aplicativo para o time de parcerias**.&#x20;

1\. A URL aberta vem no padrão "[`{{store-adress}}`](https://partners.tray.com.br/loja-de-aplicativos/comece-por-aqui/glossario#store-adress)`/web_api/tray/callback`" com os parâmetros abaixo enviados pela plataforma Tray:&#x20;

<table><thead><tr><th width="150">Parâmetro</th><th width="158.4">Tipo</th><th>Exemplo</th></tr></thead><tbody><tr><td><strong><code>url</code></strong></td><td>String</td><td>https://trayparceiros.commercesuite.com.br</td></tr><tr><td><strong><code>adm_user</code></strong></td><td>String</td><td>roottray</td></tr><tr><td><strong><code>store</code></strong></td><td>String</td><td>1234567</td></tr></tbody></table>

Essa URL com todos os parâmetros deve ser salva para a próxima etapa.

&#x32;**.** Na **URL de callback** da loja deve ser implementada uma Landing Page que apresente os detalhes do aplicativo e disponibilize um botão que inicie a integração com a aplicação. É necessário que a Landing Page seja configurada seguindo as recomendações abaixo:

* Deve informar e apresentar detalhes do aplicativo
* Deve possuir um botão para iniciar a integração, geralmente com o título **Instale agora** ou **Inicie agora**.
* Este botão deve redirecionar o cliente para uma URL de autorização da loja, enviando uma requisição do tipo **GET** conforme abaixo:

## Autenticação

<mark style="color:blue;">`GET`</mark> `{{store-address}}/auth.php`

Requisição que permite e inicia a integração do aplicativo com a loja.

#### Query Parameters

| Name                                               | Type   | Description                                                                                     |
| -------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------- |
| response\_type<mark style="color:red;">\*</mark>   | String | Tipo de solicitação (Valor padrão **code**)                                                     |
| consumer\_secret<mark style="color:red;">\*</mark> | String | Identificação do aplicativo junto ao Tray Commerce.                                             |
| callback<mark style="color:red;">\*</mark>         | String | URL de Callback para o qual o usuário será redirecionado ao clicar no botão, após a autorização |

Exemplo da URL de requisição:

> `{{store-adress}}/auth.php?response_type=code&consumer_key={{consumer_key}}&callback=https://{{url_de_callback}}`

{% hint style="danger" %} <mark style="color:red;">**Atenção!**</mark>\
A **URL de callback** deve fazer o uso do certificado digital (**HTTPS**)/SSL
{% endhint %}

Com o botão configurado, ao clicar você será direcionado para URL de autorização do aplicativo.

### Passo 3: Capture o <mark style="color:red;">`code`</mark>

1\. Quando a página de autorização for exibida (conforme imagem abaixo) clique no botão **Autorizar**&#x20;

![Página de autorização do aplicativo](https://developers.tray.com.br/images/integracao-a7ae58ba.png)

{% hint style="info" %} <mark style="color:blue;">**Observação importante!**</mark>

Após o aplicativo ser autorizado, não será mais exibida essa tela, e você será direcionado automaticamente para a etapa abaixo.
{% endhint %}

2\. Com o aplicativo autorizado ocorre o redirecionamento para **URL de callback** com os dados de acesso do aplicativo passados por parâmetro pela plataforma. Os parâmetros obtidos da URL vem conforme o exemplo abaixo:

> array(5) {&#x20;
>
> &#x20;    \["adm\_user"]=> string(8) "roottray"&#x20;
>
> &#x20;    \["code"]=> string(64) "<mark style="color:red;">**123abcd126g193aaba2962989f00637012b8fab9d657e5a297f7**</mark>"&#x20;
>
> &#x20;    \["api\_address"]=> string(50) "<https://trayparceiros.commercesuite.com.br/web\\_api>"
>
> &#x20;    \[ "store"]=> string(6) "391250"&#x20;
>
> &#x20;    \["store\_host"]=> string(42) "<https://trayparceiros.commercesuite.com.br"&#x20>;
>
> }

Desses dados copie o **code** "que no exemplo acima está destacado em vermelho" e salve em um documento seguro no seu computador.&#x20;

{% hint style="info" %}
Vídeo com orientações sobre o processo de criação da Landing Page
{% endhint %}

Com o **`code`** realize a [4° etapa](#como-obter-a-chave-de-acesso) para [**Gerar a Chave de Acesso**](https://partners.tray.com.br/loja-de-aplicativos/autorizacao-e-autenticacao/broken-reference).