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

# Catálogo Interativo da API (OpenAPI)

> Explore e teste todos os endpoints da API do BulkRoute diretamente pelo navegador.

A referência completa de endpoints da API do BulkRoute é gerada automaticamente a partir da nossa especificação OpenAPI 3.1 oficial. Você pode simular requisições diretamente pelo navegador usando sua API Key de testes.

## Como usar o catálogo interativo

1. **Navegue pelos endpoints** agrupados por categoria (Auth, Quotes, Shipments, Tracking, etc.)
2. Clique em qualquer endpoint para expandir os detalhes:
   * Parâmetros de URL, query e body
   * Schema de resposta com exemplos
   * Códigos de status HTTP esperados
3. Clique em **Try it out** para testar o endpoint
4. Preencha os parâmetros e clique em **Execute**
5. A resposta aparece logo abaixo com o status code, headers e body

<Note>
  Para testar endpoints autenticados, adicione o header `X-API-Key: bk_live_...` ou `Authorization: Bearer <jwt>` no painel de autenticação do catálogo.
</Note>

## Autenticação

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

| Método         | Header                        | Uso                                               |
| :------------- | :---------------------------- | :------------------------------------------------ |
| **API Key**    | `X-API-Key: bk_live_...`      | Integrações de ERP, e-commerce, sistemas externos |
| **Bearer JWT** | `Authorization: Bearer <jwt>` | Painel admin, apps mobile, sessões de usuário     |

A maioria dos endpoints aceita ambos. Endpoints de auth (`/auth/login`, `/auth/refresh`, `/auth/register`) não exigem autenticação.

## Ambientes

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

Use o seletor de servidor no topo do catálogo para alternar entre ambientes.

## Categorias de endpoints

### Auth

Autenticação e registro de usuários/tenants.

* `POST /auth/login` — Login com e-mail/senha
* `POST /auth/refresh` — Renovar access token
* `POST /auth/register` — Registrar novo usuário/tenant

### Quotes

Cotação de frete multi-carrier em tempo real.

* `POST /quotes/calculate` — Calcular cotação com múltiplos carriers
* `GET /quotes/{id}` — Consultar cotação anterior

### Shipments

Criação e gestão de envios.

* `POST /shipments` — Criar novo envio
* `GET /shipments` — Listar envios (com filtros)
* `GET /shipments/{id}` — Detalhar envio específico
* `PATCH /shipments/{id}` — Atualizar envio
* `DELETE /shipments/{id}` — Cancelar envio

### Tracking

Rastreio unificado de envios.

* `GET /tracking/{code}` — Status atual do rastreio
* `GET /tracking/{code}/events` — Linha do tempo de eventos

### Labels

Emissão de etiquetas de envio.

* `POST /labels` — Gerar etiqueta (PDF ou ZPL)
* `GET /labels/{id}` — Baixar etiqueta gerada

### Carriers

Gestão de transportadoras conectadas.

* `GET /carriers` — Listar carriers ativos
* `GET /carriers/{code}` — Detalhar carrier
* `GET /carriers/{code}/scorecard` — Scorecard de performance

### Contracts

Contratos de frete por carrier.

* `GET /contracts` — Listar contratos
* `POST /contracts` — Criar contrato

### Webhooks

Webhooks inbound de carriers.

* `POST /webhooks/{carrierCode}` — Endpoint para receber webhooks de carriers

### Integrations

Integrações com ERPs e e-commerce.

* `GET /integrations` — Listar integrações ativas
* `POST /integrations/bling/sync` — Disparar sincronização do Bling

### Returns

Logística reversa / devoluções.

* `POST /returns` — Criar solicitação de devolução
* `GET /returns` — Listar devoluções

### Notifications

Notificações enviadas e logs.

* `GET /notifications/logs` — Logs de notificações (WhatsApp, SMS, e-mail)

### Multi-warehouse

Cotação com múltiplos armazéns.

* `POST /multi-warehouse/quote` — Cotação considerando múltiplos CDs

### Address

Validação de endereço e CEP.

* `GET /address/validate-cep?cep=...` — Validar CEP e autocompletar endereço

### Carbon

Emissões de carbono por envio.

* `GET /carbon/emissions?shipmentId=...` — Calcular CO₂ de um envio

### Insurance

Seguro de carga.

* `POST /insurance/quote` — Cotar seguro para um shipment
* `POST /insurance` — Contratar apólice

### ML

Modelos de machine learning do orquestrador.

* `POST /ml/predict` — Predição de score para um carrier

### EDI

Intercâmbio eletrônico de dados (EDI).

* `GET /edi` — Listar transações EDI
* `POST /edi/upload` — Upload de arquivo EDI

## Convenções da API

### Formato

* **Content-Type**: `application/json` em todas as requisições e respostas
* **Properties**: `camelCase` em todos os payloads
* **Datas**: ISO 8601 UTC (ex: `2026-09-06T18:30:00Z`)
* **Moedas**: BRL em centavos ou decimal (ver schema de cada endpoint)
* **CEP**: string de 8 dígitos numéricos (ex: `"01310100"`)

### Códigos de status

| Código | Significado                                      |
| :----- | :----------------------------------------------- |
| `200`  | Sucesso                                          |
| `201`  | Criado                                           |
| `204`  | Sucesso sem conteúdo (delete)                    |
| `400`  | Erro de validação (body/params inválidos)        |
| `401`  | Não autenticado                                  |
| `403`  | Sem permissão (tenant errado, role insuficiente) |
| `404`  | Recurso não encontrado                           |
| `409`  | Conflito (duplicado, estado inválido)            |
| `422`  | Erro de negócio (validação semântica)            |
| `429`  | Rate limit excedido                              |
| `500`  | Erro interno do servidor                         |

### Rate limiting

* **Autenticado com API Key**: 100 req/min por tenant
* **Autenticado com JWT**: 60 req/min por usuário
* **Sem autenticação** (auth endpoints): 10 req/min por IP

Headers de rate limit em toda resposta:

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

### 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"
}
```

### 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" }
  ]
}
```

## SDKs oficiais

O BulkRoute mantém SDKs para as principais linguagens:

| Linguagem   | Instalação                          | Repo           |
| :---------- | :---------------------------------- | :------------- |
| **Node.js** | `npm install @bulkroute/client`     | `sdks/node/`   |
| **Python**  | `pip install bulkroute-client`      | `sdks/python/` |
| **PHP**     | `composer require bulkroute/client` | `sdks/php/`    |

### Exemplo Node.js

```typescript theme={null}
import { BulkRouteClient } from '@bulkroute/client';

const client = new BulkRouteClient({ apiKey: 'bk_live_...' });

const quote = await client.quotes.calculate({
  destinationZip: '01310100',
  originZip: '80000000',
  items: [{ weight: 30, length: 100, width: 60, height: 40, value: 1500, quantity: 1 }],
});

console.log(quote.options); // array de carriers com preço e prazo
```

### Exemplo Python

```python theme={null}
from bulkroute_client import BulkRouteClient

client = BulkRouteClient(api_key='bk_live_...')

quote = client.quotes.calculate(
    destination_zip='01310100',
    origin_zip='80000000',
    items=[{'weight': 30, 'length': 100, 'width': 60, 'height': 40, 'value': 1500, 'quantity': 1}],
)

print(quote.options)
```

## Referência completa

Os endpoints abaixo são gerados automaticamente a partir da especificação OpenAPI 3.1. Navegue pela aba **API Reference** no menu lateral para explorar cada endpoint com parâmetros, exemplos e testes interativos.