Catálogo Interativo da API (OpenAPI) - BulkRoute Central de Ajuda

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

Navegue pelos endpoints agrupados por categoria (Auth, Quotes, Shipments, Tracking, etc.)
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
Clique em Try it out para testar o endpoint
Preencha os parâmetros e clique em Execute
A resposta aparece logo abaixo com o status code, headers e body

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

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:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1694025600

Paginação

Endpoints de listagem usam cursor-based pagination:

GET /shipments?limit=50&cursor=eyJpZCI6ImFiYzEyMyJ9

Resposta:

{
  "data": [...],
  "hasMore": true,
  "nextCursor": "eyJpZCI6Inh5ejc4OSJ9"
}

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

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

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

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.

​Como usar o catálogo interativo

​Autenticação

​Ambientes

​Categorias de endpoints

​Auth

​Quotes

​Shipments

​Tracking

​Labels

​Carriers

​Contracts

​Webhooks

​Integrations

​Returns

​Notifications

​Multi-warehouse

​Address

​Carbon

​Insurance

​ML

​EDI

​Convenções da API

​Formato

​Códigos de status

​Rate limiting

​Paginação

​Erros

​SDKs oficiais

​Exemplo Node.js

​Exemplo Python

​Referência completa

Como usar o catálogo interativo

Autenticação

Ambientes

Categorias de endpoints

Auth

Quotes

Shipments

Tracking

Labels

Carriers

Contracts

Webhooks

Integrations

Returns

Notifications

Multi-warehouse

Address

Carbon

Insurance

ML

EDI

Convenções da API

Formato

Códigos de status

Rate limiting

Paginação

Erros

SDKs oficiais

Exemplo Node.js

Exemplo Python

Referência completa