# Criar token de chat

> Gera, no seu backend, o token de curta duração que o SDK usa para abrir o chat de um usuário final.

Página: https://docs.diligensai.com.br/referencia/token-chat

`POST https://api.diligensai.com.br/api/v1/chat/token`

Autorização: `X-API-Key: <sua API key>`. Chamada do seu backend, com a API key da conta. Nunca do navegador. Veja [Autenticação](https://docs.diligensai.com.br/guias/autenticacao.md).

Esta rota troca a API key por um token de chat para um usuário final. O seu backend a chama a partir de uma rota própria, acessível apenas ao usuário autenticado, e devolve o token ao navegador. O [SDK do chat](https://docs.diligensai.com.br/guias/sdk.md) usa esse token para conversar com a Diligens, e a API key nunca sai do servidor. O código completo da rota do seu backend está em [Crie a rota de token](https://docs.diligensai.com.br/guias/sdk.md#1-crie-a-rota-de-token-no-seu-backend).

**Requisição**

cURL:

```bash
curl -X POST "https://api.diligensai.com.br/api/v1/chat/token" \
  -H "X-API-Key: $DILIGENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "loja-123" }'
```

Node.js:

```javascript
const response = await fetch('https://api.diligensai.com.br/api/v1/chat/token', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.DILIGENS_API_KEY, 'Content-Type': 'application/json' },
  // O external_id vem da SUA sessão, nunca do navegador.
  body: JSON.stringify({ external_id: String(user.id) }),
});
const { token, expires_at } = await response.json();
```

Python:

```python
import os
import requests

response = requests.post(
    "https://api.diligensai.com.br/api/v1/chat/token",
    headers={"X-API-Key": os.environ["DILIGENS_API_KEY"]},
    # O external_id vem da SUA sessão, nunca do navegador.
    json={"external_id": str(user.id)},
    timeout=10,
)
data = response.json()
```

PHP:

```php
<?php
$ch = curl_init('https://api.diligensai.com.br/api/v1/chat/token');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('DILIGENS_API_KEY'),
        'Content-Type: application/json',
    ],
    // O external_id vem da SUA sessão, nunca do navegador.
    CURLOPT_POSTFIELDS => json_encode(['external_id' => (string) $user->id]),
]);
$data = json_decode(curl_exec($ch), true);
```

**Resposta**

201:

```json
{
  "token": "Q2F7...",
  "external_id": "loja-123",
  "expires_at": "2026-09-26T15:05:00Z"
}
```

401:

```json
{ "status": 401, "code": "APIKEY_002", "message": "API key inválida" }
```

> **Obtenha o external_id da sua sessão**
>
> Nunca use um valor enviado pelo navegador. Se o `external_id` vier de um parâmetro da requisição, um usuário poderá abrir o chat e acessar os dados de outro. Consulte [Usuário final](https://docs.diligensai.com.br/guias/usuario-final.md).

## Corpo da requisição

- `external_id` (`string`, obrigatório)

  O identificador, no seu sistema, do usuário que vai conversar, com até 255 caracteres. Se ele ainda não existir na Diligens, será criado.

## Resposta

A API responde com o status `201` e o token em `token`, válido até `expires_at`.

## Regras

- O token é válido por **5 minutos** e pode ser usado quantas vezes for necessário até expirar. Cada chamada gera um novo token, e os anteriores continuam válidos até expirarem.
- O token dá acesso somente ao chat daquele `external_id`. Ele não serve para o `PUT /orders` nem para as outras rotas desta referência.
- Não é necessário guardar o token no seu backend. O SDK o mantém em memória e solicita um novo antes que ele expire.
- A rota funciona mesmo sem créditos (consulte [Créditos](https://docs.diligensai.com.br/guias/creditos.md)) e conta no [limite de chamadas](https://docs.diligensai.com.br/guias/limites.md) da API key.

## Erros

| Status | `code` | Quando |
|---|---|---|
| 400 | `COMMON_002` | `external_id` ausente, vazio ou com mais de 255 caracteres |
| 401 | `APIKEY_002` | API key ausente, inválida ou regenerada |
| 402 | `APIKEY_003` | A conta ainda não tem nenhuma recarga de créditos paga |
| 403 | `EXTUSER_002` | O `external_id` é novo e a conta já chegou ao limite de `external_id`s |
| 429 | `COMMON_005` | Limite de chamadas da API key excedido |

Os detalhes do formato de erro estão em [Erros](https://docs.diligensai.com.br/guias/erros.md).