> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bulkroute.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Chaves de API & Autenticação

> Como gerar, rotacionar e autenticar suas chamadas via header X-API-Key.

Para integrar sistemas externos (ERP, e-commerce, WMS), utilize uma **Chave de API (API Key)** vinculada ao seu tenant.

## Como Gerar sua Chave de API

1. Acesse o **Painel do BulkRoute** como Administrador.
2. Navegue até **Configurações da Empresa** > **Chaves de API**.
3. Clique em **Gerar Nova Chave**.
4. Dê um nome de identificação (ex: *Integração Bling Produção*).
5. Copie o valor gerado (iniciado pelo prefixo `bk_live_...`).

<Warning>
  A chave completa é exibida **apenas uma vez** por motivos de segurança. Armazene-a com segurança em seu gerenciador de segredos ou variáveis de ambiente. Se perder, será necessário gerar uma nova.
</Warning>

## Como Autenticar as Requisições

Envie a chave no cabeçalho HTTP `X-API-Key`:

```bash theme={null}
curl -X GET "https://api.bulkroute.com.br/api/carriers" \
  -H "X-API-Key: bk_live_1234567890abcdef" \
  -H "Content-Type: application/json"
```

Todas as requisições autenticadas com API Key estão associadas ao tenant da chave — você não precisa enviar nenhum header adicional de tenant.

## Múltiplas Chaves

Você pode ter múltiplas chaves de API ativas simultaneamente. Boas práticas:

| Nome da chave                 | Uso                 | Ambiente |
| :---------------------------- | :------------------ | :------- |
| `Integração Bling Produção`   | Sincronização Bling | Produção |
| `Integração Shopify Produção` | App Shopify         | Produção |
| `Checkout Site Produção`      | Cotação no checkout | Produção |
| `Testes Desenvolvimento`      | Testes de API       | Staging  |

### Por que múltiplas chaves?

* **Isolamento**: se uma chave for comprometida, você revoga só ela sem afetar as outras
* **Auditoria**: o log de requisições mostra qual chave fez cada chamada
* **Rate limiting**: cada chave tem seu próprio limite de 100 req/min

## Revogar uma Chave

1. Acesse **Configurações da Empresa** > **Chaves de API**
2. Localize a chave desejada
3. Clique em **Revogar**
4. Confirme

A chave é imediatamente invalidada — qualquer requisição com ela retorna `401 Unauthorized`.

## Rotacionamento de Chaves

Recomendamos rotacionar suas chaves a cada 90 dias:

1. Gere uma nova chave
2. Atualize seus sistemas com a nova chave
3. Verifique se tudo funciona
4. Revogue a chave antiga

## Segurança

### Boas práticas

* ✅ Armazene a chave em variável de ambiente (`BULKROUTE_API_KEY`)
* ✅ Use gerenciador de segredos (AWS Secrets Manager, Vault, Doppler)
* ✅ Restrinja acesso à chave apenas aos sistemas que precisam
* ✅ Rotacione a cada 90 dias
* ✅ Use chaves separadas para cada ambiente (prod/staging)

### O que NÃO fazer

* ❌ Não commite a chave no repositório git
* ❌ Não hardcode a chave no frontend (JavaScript público)
* ❌ Não compartilhe a chave em chats/e-mails
* ❌ Não use a mesma chave para todos os sistemas
* ❌ Não deixe chaves antigas ativas sem uso

## Identificação do Tenant

Cada chave de API está vinculada a um tenant específico. A API identifica o tenant automaticamente pela chave — você não precisa enviar nenhum header adicional.

Se você precisa acessar múltiplos tenants (ex: agência que gerencia várias empresas), gere uma chave para cada tenant.

## Exemplos por linguagem

### Node.js

```typescript theme={null}
const response = await fetch('https://api.bulkroute.com.br/api/shipments', {
  headers: {
    'X-API-Key': process.env.BULKROUTE_API_KEY,
    'Content-Type': 'application/json',
  },
});
```

### Python

```python theme={null}
import requests

headers = {
    'X-API-Key': os.environ['BULKROUTE_API_KEY'],
    'Content-Type': 'application/json',
}
response = requests.get('https://api.bulkroute.com.br/api/shipments', headers=headers)
```

### PHP

```php theme={null}
$ch = curl_init('https://api.bulkroute.com.br/api/shipments');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . getenv('BULKROUTE_API_KEY'),
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
```

## Próximos passos

* [Introdução à API](/api-reference/introduction) — ambientes, rate limit, paginação
* [Webhooks](/api-reference/webhooks) — receba eventos push em tempo real
* [Catálogo OpenAPI](/api-reference/openapi) — explore todos os endpoints