> For the complete documentation index, see [llms.txt](https://docs.troqueedevolva.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.troqueedevolva.com.br/integracoes-externas/token-de-integracao.md).

# Token de integração

O token de integração é uma chave de API que você gera para quem vai desenvolver a integração da sua loja, com permissão limitada e prazo de validade definidos por você.

Ele foi criado para resolver um problema comum: até então, entregar o acesso à API significava entregar a chave da loja inteira, sem prazo e sem como saber quem estava usando. Com o token de integração, o desenvolvedor recebe acesso apenas às solicitações, você acompanha o uso e pode revogar o acesso a qualquer momento, sem mexer no restante da conta.

{% hint style="info" %}
O token de integração é criado pelo administrador da conta, dentro do painel Troque & Devolva.
{% endhint %}

### Criando o token

No painel, abra a área de **Integrações** e a lista de tokens de API. Clique em **Novo token de API** e preencha:

* **Nome da integração**: como esse acesso vai aparecer na sua lista. Use um nome que identifique o projeto ou o parceiro, por exemplo "ERP Bling" ou "Agência Tal".
* **Dados do desenvolvedor**: nome, e-mail e site de quem vai usar o token. Serve para você saber a quem pedir explicação caso veja um uso estranho.
* **Permissões**: marque **Leitura**, **Escrita** ou as duas, dentro de **Solicitações**. Escrita inclui criar, alterar e excluir.
* **Expira em**: a data em que o token deixa de funcionar sozinho.

<figure><img src="/files/lQ5h9415MkknbPumPuRc" alt="" width="563"><figcaption><p>Tela de criação do token de integração</p></figcaption></figure>

Depois é só clicar em **Criar token**.

{% hint style="warning" %}
O campo **Expira em** pode ficar em branco, e nesse caso o token não expira nunca. Recomendamos sempre definir uma data, mesmo que distante. Token sem prazo é token que fica ativo muito tempo depois de o projeto acabar.
{% endhint %}

#### Escolhendo as permissões

* Marque só **Leitura** quando a integração apenas consulta solicitações, por exemplo para alimentar um relatório, um BI ou um painel interno.
* Marque também **Escrita** quando a integração precisa agir sobre as solicitações, por exemplo criar solicitações, autorizar postagem, registrar entrega ou finalizar reembolso.

Na dúvida, comece só com Leitura. Se o desenvolvedor precisar de mais, você cria um novo token com Escrita e revoga o antigo.

### Entregando o token ao desenvolvedor

Assim que o token é criado, aparece a tela **Token criado**, com duas formas de entrega.

{% hint style="danger" %}
Copie o token agora. Por segurança ele não será exibido de novo, nem para você. Se perder, o caminho é criar outro token e revogar esse.
{% endhint %}

<figure><img src="/files/DI4AIPFexYwrxYQySr1Q" alt="" width="563"><figcaption></figcaption></figure>

**Se você mesmo vai usar**, copie o token direto do primeiro campo. Ele tem o formato `ted_` seguido de uma sequência de letras e números.

**Se você vai repassar a um desenvolvedor**, use o link seguro do segundo campo. Ele abre uma única vez e evita que o token circule solto por e-mail ou WhatsApp. O próprio modal mostra a data e a hora em que esse link expira.

O link tem este formato:

```
https://app.troqueedevolva.com.br/integration-tokens/reveal/c8b00ed28595863ec77aad7b64c09a23b76439b588de4e57cba1b5270075e611
```

Quando o desenvolvedor abre, ele vê o nome da loja, o nome da integração, o token e um botão para copiar. A partir daí o link está consumido, e quem tentar abrir de novo vê o aviso de que o link já foi usado.

{% hint style="warning" %}
Porque o link abre uma única vez, não teste o link antes de enviar. Se você abrir para conferir, ele queima, e o desenvolvedor vai receber um link que não mostra mais nada. Nesse caso será preciso criar um token novo.
{% endhint %}

### Usando o token nas chamadas

O token deve ser enviado no header `store_token` em todas as requisições.

Endpoint da API: `https://api.troqueedevolva.com.br`

Exemplo de chamada:

```bash
curl "https://api.troqueedevolva.com.br/request" \
  -H "store_token: ted_sua_chave_aqui"
```

A referência completa das rotas, com parâmetros e exemplos de corpo, está em [docs.api.troqueedevolva.com.br](https://docs.api.troqueedevolva.com.br/).

### O que o token de integração acessa

O token de integração acessa **apenas as rotas de solicitações**, ou seja, as rotas `/request`. Todo o restante continua sendo feito pelo painel.

Com permissão de **Leitura**:

* Listar solicitações
* Detalhar uma solicitação
* Cotar frete de uma solicitação

Com permissão de **Escrita**:

* Criar e editar solicitações
* Criar comentários e anexar arquivos
* Autorizar postagem e cancelar a autorização
* Registrar postagem e registrar entrega
* Rejeitar e arquivar solicitações
* Finalizar reembolso em dinheiro, em vale-trocas, no cartão de crédito ou por produto
* Cadastrar dados de PIX e perguntar a conta bancária ao cliente
* Emitir vale-trocas integrado na plataforma
* Enviar uma pergunta ao cliente e registrar respostas de NPS

Não estão disponíveis para o token de integração, e seguem apenas pelo painel: configurações da loja, usuários, endereços de devolução, e-mails transacionais, respostas pré-definidas, perguntas da loja, dados da loja e criação de conta.

### Acompanhando e revogando

Na lista de tokens você vê, de cada token:

* **Token**: o começo da chave, o suficiente para identificar qual é
* **Permissões**: se é Leitura, Escrita ou as duas
* **Último uso**: quando aquele token chamou a API pela última vez. Enquanto o desenvolvedor não usar, fica sem registro
* **Expira em**: a data definida na criação
* **Situação**: se o token está ativo

Revogue o token quando o projeto terminar, quando o desenvolvedor deixar de atender a loja ou sempre que suspeitar que a chave vazou. A revogação vale na hora, e as chamadas seguintes passam a ser recusadas.

{% hint style="success" %}
Um token por integração. Assim, revogar um projeto não derruba os outros, e o campo **Último uso** mostra de verdade quem ainda está ativo.
{% endhint %}

### Erros mais comuns

**403 Forbidden**

```json
{
    "code": "Forbidden",
    "message": "Rota nao disponivel para token de integracao"
}
```

A rota chamada não é de solicitações. O token de integração só acessa `/request`. Confira o endereço da chamada na referência da API.

**401 Unauthorized**

```json
{
    "code": "Unauthorized",
    "message": "store_token revogado"
}
```

O token foi revogado no painel. É preciso gerar um token novo e reconfigurar a integração com ele.

**429 Too Many Requests**

O limite de requisições foi ultrapassado. Requisições autenticadas têm limite de 15 por segundo e 1000 por minuto. Respeite o header `Retry-After` da resposta e distribua as chamadas ao longo do tempo.

### Boas práticas

1. Um token por integração, nunca o mesmo token para dois parceiros.
2. Sempre defina uma data de expiração.
3. Conceda só Leitura quando a integração não precisa alterar nada.
4. Prefira o link seguro para entregar o token, em vez de colar a chave em e-mail, WhatsApp ou ticket.
5. Revise a lista de tokens periodicamente e revogue o que estiver sem uso.
6. Se o token vazou, revogue primeiro e crie o substituto depois.