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

Referência Interativa da API

A referência completa e interativa da API (Swagger UI) está disponível em: https://api.bulkroute.com.br/docs/

O acesso à referência interativa exige autenticação. Solicite as credenciais ao suporte (suporte@bulkroute.com.br) ou à sua equipe técnica.No Swagger UI você pode:

Ver todos os endpoints organizados por categoria
Testar requisições diretamente no navegador
Ver schemas de request e response
Baixar o OpenAPI JSON para gerar SDKs

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.

Formato de Resposta

Todas as respostas seguem um envelope padronizado:

Sucesso

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 137,
    "totalPages": 7
  }
}

O campo meta é opcional e aparece em endpoints de listagem com paginação, ou com metadados extras (ex: processingTimeMs, quotesCount).

Erro

{
  "success": false,
  "error": "destinationZip is required"
}

Erros de validação (Zod) retornam todas as mensagens concatenadas em error, separadas por ; .

Paginação

Endpoints de listagem usam paginação offset com page e limit:

GET /tracking/shipments?page=1&limit=20

Resposta com meta:

{
  "success": true,
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 137,
    "totalPages": 7
  }
}

Parâmetro	Default	Máximo
`page`	1	—
`limit`	20	100

Tratamento de Erros

Erros seguem o envelope { success: false, error: string }:

{
  "success": false,
  "error": "destinationZip 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.

Referência canônica da API

O contrato completo da API (cotação, criação de pedidos, agendamento, rastreio, webhooks) com exemplos cURL está documentado no FLUXO-INTEGRACAO.md do repositório BulkRoute. Use-o como fonte da verdade ao integrar — todos os módulos de plataforma (Magento/Inovarti, Shopify, Nuvemshop, Tray, VTEX) implementam contra o mesmo contrato.

Não há SDK público publicado no momento. As integrações nativas do BulkRoute (Shopify, Nuvemshop, Tray, VTEX) usam um SDK interno TypeScript (@bulkroute/client) que vive no monorepo bulkroute-integrations. Para integrar em Node.js, você pode copiar esse client ou chamar a API REST diretamente — o contrato é o mesmo.

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.

Fluxo de Integração

Veja o fluxo completo ponta a ponta com cURL.

​Referência Interativa da API

​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

​Formato de Resposta

​Sucesso

​Erro

​Paginação

​Tratamento de Erros

​Códigos de status

​Webhooks

​Referência canônica da API

​Próximos passos

Gerar API Key

Configurar Webhooks

Fluxo de Integração

Referência Interativa da API

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

Formato de Resposta

Sucesso

Erro

Paginação

Tratamento de Erros

Códigos de status

Webhooks

Referência canônica da API

Próximos passos