Introdução à API BulkRoute - BulkRoute Central de Ajuda

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:

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 para gerar sua chave.

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

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:

API Key: o tenant é identificado pela chave — não é necessário enviar nenhum header adicional.
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:

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:

GET /shipments?limit=50&cursor=eyJpZCI6ImFiYzEyMyJ9

Resposta:

{
  "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):

{
  "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 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

Gerar API Key

Crie sua chave de API para começar a integrar.

Configurar Webhooks

Receba notificações push de status de entrega em tempo real.

Catálogo OpenAPI

Explore todos os endpoints com exemplos interativos.

Fluxo de Integração

Veja o fluxo completo ponta a ponta com cURL.

​URLs Base da API

​Formato dos Dados

​Autenticação

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

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

​Multi-tenant

​Rate Limiting

​Paginação

​Tratamento de Erros

​Códigos de status

​Webhooks

​SDKs

​Próximos passos