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

# Introdução à API BulkRoute

> Informações gerais, autenticação, ambientes e convenções para desenvolvedores e integradores.

A API REST do BulkRoute permite integrar cotações de frete, criação de pedidos de envio, etiquetas e rastreamento diretamente nos seus sistemas (ERP, Checkout, WMS).

## URLs Base da API

| Ambiente                  | URL Base                                   |
| :------------------------ | :----------------------------------------- |
| **Produção**              | `https://api.bulkroute.com.br/api`         |
| **Homologação / Staging** | `https://staging-api.bulkroute.com.br/api` |
| **Desenvolvimento Local** | `http://localhost:3000/api`                |

## Formato dos Dados

* Todas as requisições aceitam e retornam `application/json`.
* Códigos de status HTTP padrão são utilizados (`200`, `201`, `400`, `401`, `403`, `500`).
* Todas as propriedades nos payloads JSON seguem a convenção `camelCase`.
* Datas em formato ISO 8601 UTC (ex: `2026-09-06T18:30:00Z`).
* CEPs como string de 8 dígitos numéricos (ex: `"01310100"`).

## Autenticação

A API suporta dois métodos de autenticação:

### 1. API Key (recomendado para integrações)

Envie a chave no header `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"
```

Veja [Chaves de API](/api-reference/api-keys) para gerar sua chave.

### 2. Bearer JWT (para sessões de usuário)

```bash theme={null}
curl -X GET "https://api.bulkroute.com.br/api/shipments" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json"
```

O JWT é obtido via `POST /auth/login` e renovado via `POST /auth/refresh`.

## Multi-tenant

Cada requisição está associada a um **tenant** (empresa). O tenant é resolvido automaticamente:

1. **API Key**: o tenant é identificado pela chave — não é necessário enviar nenhum header adicional.
2. **JWT**: o tenant é identificado pelo `tenantId` no payload do token.

Você só consegue acessar dados do seu próprio tenant. Tentar acessar dados de outro tenant retorna `403 Forbidden`.

## Rate Limiting

| Método   | Limite  | Janela                   |
| :------- | :------ | :----------------------- |
| API Key  | 100 req | por minuto (por tenant)  |
| JWT      | 60 req  | por minuto (por usuário) |
| Sem auth | 10 req  | por minuto (por IP)      |

Headers de rate limit em toda resposta:

```http theme={null}
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1694025600
```

Quando você excede o limite, a API retorna `429 Too Many Requests` com o header `Retry-After` indicando quantos segundos esperar.

## Paginação

Endpoints de listagem usam **cursor-based pagination**:

```http theme={null}
GET /shipments?limit=50&cursor=eyJpZCI6ImFiYzEyMyJ9
```

Resposta:

```json theme={null}
{
  "data": [...],
  "hasMore": true,
  "nextCursor": "eyJpZCI6Inh5ejc4OSJ9"
}
```

| Parâmetro | Default | Máximo                          |
| :-------- | :------ | :------------------------------ |
| `limit`   | 50      | 100                             |
| `cursor`  | —       | string opaca do cursor anterior |

## Tratamento de Erros

Erros seguem o formato RFC 7807 (Problem Details):

```json theme={null}
{
  "type": "https://docs.bulkroute.com.br/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "detail": "destinationZip is required",
  "instance": "/quotes/calculate",
  "errors": [
    { "field": "destinationZip", "message": "is required" }
  ]
}
```

### Códigos de status

| Código | Significado            |
| :----- | :--------------------- |
| `200`  | Sucesso                |
| `201`  | Criado                 |
| `204`  | Sucesso sem conteúdo   |
| `400`  | Erro de validação      |
| `401`  | Não autenticado        |
| `403`  | Sem permissão          |
| `404`  | Recurso não encontrado |
| `409`  | Conflito (duplicado)   |
| `422`  | Erro de negócio        |
| `429`  | Rate limit excedido    |
| `500`  | Erro interno           |

## Webhooks

Além de consultar a API, você pode receber eventos push em tempo real via webhooks. Veja [Webhooks & Eventos](/api-reference/webhooks) para configurar.

## SDKs

O BulkRoute mantém SDKs oficiais para acelerar sua integração:

| Linguagem | Instalação                          |
| :-------- | :---------------------------------- |
| Node.js   | `npm install @bulkroute/client`     |
| Python    | `pip install bulkroute-client`      |
| PHP       | `composer require bulkroute/client` |

## Próximos passos

<CardGroup cols={2}>
  <Card title="Gerar API Key" icon="key" href="/api-reference/api-keys">
    Crie sua chave de API para começar a integrar.
  </Card>

  <Card title="Configurar Webhooks" icon="webhook" href="/api-reference/webhooks">
    Receba notificações push de status de entrega em tempo real.
  </Card>

  <Card title="Catálogo OpenAPI" icon="code" href="/api-reference/openapi">
    Explore todos os endpoints com exemplos interativos.
  </Card>

  <Card title="Fluxo de Integração" icon="route" href="/onboarding/quickstart">
    Veja o fluxo completo ponta a ponta com cURL.
  </Card>
</CardGroup>