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

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

O acesso ao Swagger UI exige autenticação (Basic Auth). Solicite as credenciais ao suporte (suporte@bulkroute.com.br) ou à sua equipe técnica.

Como usar o Swagger UI

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, clique no botão Authorize no topo do Swagger UI e informe sua API Key (X-API-Key: bk_live_...) ou JWT (Bearer <token>).

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
POST /auth/forgot-password — Solicitar reset de senha
POST /auth/reset-password — Resetar senha com token
POST /auth/change-password — Alterar senha
POST /auth/accept-invite — Aceitar convite de equipe
GET /auth/sse-token — Token para SSE

Quotes

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

POST /quotes — Calcular cotação com múltiplos carriers
GET /quotes/logs — Histórico de cotações (audit log)
GET /quotes/stats — Estatísticas de cotações (admin)

Orders

Criação e gestão de envios (shipments).

POST /orders — Criar novo envio
POST /orders/reverse — Criar envio de logística reversa
GET /orders — Listar envios (com filtros)
GET /orders/stats — Estatísticas de despacho
GET /orders/scheduling/options — Opções de agendamento
POST /orders/dispatch-all — Despachar múltiplos pedidos
POST /orders/{id}/dispatch — Despachar pedido específico
POST /orders/{id}/pickup — Solicitar coleta
PATCH /orders/{id}/status — Atualizar status
PATCH /orders/{id}/scheduling — Atualizar agendamento

Tracking

Rastreio unificado de envios.

GET /tracking/{code} — Status e timeline de rastreio por código
GET /tracking/shipments — Listar shipments do tenant (paginado)
GET /tracking/live — Shipments em trânsito (mapa Tracking Live)
GET /tracking/carrier-distribution — Distribuição por carrier
POST /tracking/driver/location — Atualizar localização do motorista
POST /tracking/own-fleet/update — Atualizar status de frota própria

Labels

Emissão de etiquetas de envio.

POST /labels — Gerar etiqueta (PDF ou ZPL)
POST /labels/{id}/reprint — Reimprimir etiqueta
POST /labels/{id}/cancel — Cancelar etiqueta
GET /labels/{trackingCode}/download — Baixar etiqueta gerada
POST /labels/{trackingCode}/public-link — Gerar link público de download

Carriers

Gestão de transportadoras conectadas.

GET /carriers — Listar carriers ativos
POST /carriers — Criar carrier (admin)
GET /carriers/{id} — Detalhar carrier
PUT /carriers/{id} — Atualizar carrier
DELETE /carriers/{id} — Desativar carrier
GET /carriers/{code}/scorecard — Scorecard de performance
GET /carriers/{code}/health — Health check de carrier
POST /carriers/{code}/register-webhook — Registrar webhook no carrier
GET /carriers/health — Health check de todos carriers
GET /carriers/benchmark — Benchmark comparativo
GET /carriers/sla-alerts — Alertas de SLA
GET /carriers/scorecards — Scorecards de todos carriers

Contracts

Contratos de frete por carrier.

GET /contracts — Listar contratos
POST /contracts — Criar contrato
GET /contracts/{id} — Detalhar contrato
PUT /contracts/{id} — Atualizar contrato
DELETE /contracts/{id} — Remover contrato

Webhooks

Webhooks inbound de carriers e outbound para seu sistema.

POST /webhooks/{carrierCode} — Endpoint público para receber webhooks de carriers
POST /webhooks/retry — Reprocessar webhook específico
POST /webhooks/retry-all — Reprocessar todos webhooks falhos
POST /webhooks/asaas — Webhook de pagamentos Asaas

Integrations

Integrações com ERPs e e-commerce.

GET /integrations — Listar integrações ativas
POST /integrations — Criar integração
GET /integrations/{id} — Detalhar integração
PUT /integrations/{id} — Atualizar integração
DELETE /integrations/{id} — Remover integração
POST /integrations/{id}/test — Testar conexão da integração

Returns

Logística reversa / devoluções.

POST /returns — Criar etiqueta de retorno
GET /returns — Listar devoluções

Notifications

Notificações enviadas e logs.

GET /notifications — 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
POST /multi-warehouse/compare — Comparar opções entre CDs
GET /multi-warehouse/warehouses — Listar CDs ativos

Address

Validação de endereço e CEP.

POST /address/validate-cep — Validar CEP e autocompletar endereço
POST /address/validate — Validar endereço completo
GET /address/cep/{cep} — Buscar endereço por CEP
GET /address/autocomplete — Autocompletar endereço
POST /address/geocode — Geocodificar endereço

Carbon

Emissões de carbono por envio.

GET /carbon/emissions — Emissões de CO₂
GET /carbon/emissions/by-carrier — Emissões por carrier
GET /carbon/emissions/by-month — Emissões por mês
GET /carbon/emissions/comparison — Comparação entre carriers
GET /carbon/emissions/shipment/{id} — Emissões de um shipment
POST /carbon/emissions/shipment/{id}/offset — Compensar emissões
GET /carbon/certificate — Certificado de carbono compensado

Insurance

Seguro de carga.

GET /insurance — Listar apólices
POST /insurance/quote — Cotar seguro para um shipment
GET /insurance/{id} — Detalhar apólice
POST /insurance/{id}/activate — Ativar apólice
POST /insurance/{id}/cancel — Cancelar apólice
GET /insurance/claims — Listar sinistros
GET /insurance/stats — Estatísticas de seguro

ML

Modelos de machine learning do orquestrador.

POST /ml/predict — Predição de score para um carrier
POST /ml/predictions — Predições em lote
POST /ml/train — Treinar modelo
GET /ml/features — Features disponíveis
GET /ml/status — Status do modelo

EDI

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

GET /edi — Listar transações EDI
GET /edi/{id} — Detalhar transação
POST /edi/upload — Upload de arquivo EDI
POST /edi/generate — Gerar arquivo EDI
GET /edi/stats — Estatísticas de EDI
GET /edi/{id}/raw — Arquivo EDI bruto
POST /edi/{id}/retry — Reprocessar transação

Bids (Freight Bids)

Sistema de leilão de frete.

GET /bids — Listar bids
POST /bids — Criar bid
GET /bids/{id} — Detalhar bid
GET /bids/public/{token} — Bid público (para carrier)
POST /bids/public/{token}/accept — Carrier aceita bid
GET /bids/stats — Estatísticas de bids

VRP (Roteirização)

Otimização de rotas com múltiplas paradas.

POST /vrp/optimize — Otimizar rota
GET /vrp — Listar rotas otimizadas
GET /vrp/{id} — Detalhar rota
DELETE /vrp/{id} — Remover rota
PATCH /vrp/{id}/status — Atualizar status da rota
POST /vrp/{id}/reorder — Reordenar paradas
GET /vrp/driver/today — Rota do motorista hoje
PATCH /vrp/stops/{id} — Atualizar parada

Fleet & Drivers

Operações de frota própria e motoristas.

GET /fleet/status — Status da frota
GET /fleet/shipments — Entregas da frota
POST /fleet/heartbeat — Heartbeat do motorista
POST /fleet/checkout — Check-out de jornada
PATCH /fleet/availability — Atualizar disponibilidade
GET /fleet/day-summary — Resumo do dia
POST /fleet/shipments/{id}/checkin — Check-in de entrega
POST /fleet/shipments/{id}/checkout — Check-out de entrega
POST /fleet/shipments/{id}/scan — Escanear pacote
POST /fleet/shipments/{id}/unscan — Remover scan
GET /fleet/shipments/{id}/packages — Pacotes do shipment
GET /driver/events — Eventos do motorista

Export

Exportação de relatórios assíncrona.

GET /export/{reportType} — Solicitar exportação
GET /export/status/{jobId} — Status do job
GET /export/download/{jobId} — Download do arquivo

CT-e & Auditoria

Auditoria de Conhecimentos de Transporte Eletrônicos.

GET /cte — Listar CT-e
POST /cte/import — Importar CT-e (XML)
POST /cte/import-batch — Importar lote de CT-e
POST /cte/import-excel — Importar via Excel
POST /cte/{id}/audit — Auditar CT-e
GET /cte/divergences — Listar divergências
POST /cte/divergences/{id}/approve — Aprovar divergência
POST /cte/divergences/{id}/reject — Rejeitar divergência
POST /cte/divergences/{id}/dispute — Disputar divergência

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

Formato de Resposta

Todas as respostas seguem o envelope { success, data/error, meta }: Sucesso:

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

Erro:

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

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

Erros

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

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

Exemplos de uso

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, chame a API REST diretamente — o contrato completo está no FLUXO-INTEGRACAO.md.

Exemplo cURL (cotação)

curl -X POST "https://api.bulkroute.com.br/quotes" \
  -H "X-API-Key: bk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "destinationZip": "01310100",
    "originZip": "80000000",
    "items": [{ "weight": 30, "length": 100, "width": 60, "height": 40, "value": 1500, "quantity": 1 }]
  }'

Exemplo Node.js (REST direto)

const res = await fetch('https://api.bulkroute.com.br/quotes', {
  method: 'POST',
  headers: {
    'X-API-Key': 'bk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    destinationZip: '01310100',
    originZip: '80000000',
    items: [{ weight: 30, length: 100, width: 60, height: 40, value: 1500, quantity: 1 }],
  }),
});

const { quotes } = await res.json();
console.log(quotes); // array de carriers com price, deadlineDays, features.appointmentRequired

Exemplo PHP (REST direto)

$ch = curl_init('https://api.bulkroute.com.br/quotes');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: bk_live_...',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'destinationZip' => '01310100',
        'originZip' => '80000000',
        'items' => [['weight' => 30, 'length' => 100, 'width' => 60, 'height' => 40, 'value' => 1500, 'quantity' => 1]],
    ]),
]);
$response = json_decode(curl_exec($ch), true);
print_r($response['quotes']);

Referência interativa

Para testar qualquer endpoint diretamente no navegador, acesse o Swagger UI: https://api.bulkroute.com.br/docs/

O acesso exige credenciais. Solicite ao suporte (suporte@bulkroute.com.br) se ainda não tiver.

​Como usar o Swagger UI

​Autenticação

​Ambientes

​Categorias de endpoints

​Auth

​Quotes

​Orders

​Tracking

​Labels

​Carriers

​Contracts

​Webhooks

​Integrations

​Returns

​Notifications

​Multi-warehouse

​Address

​Carbon

​Insurance

​ML

​EDI

​Bids (Freight Bids)

​VRP (Roteirização)

​Fleet & Drivers

​Export

​CT-e & Auditoria

​Convenções da API

​Formato

​Códigos de status

​Formato de Resposta

​Rate limiting

​Paginação

​Erros

​Exemplos de uso

​Exemplo cURL (cotação)

​Exemplo Node.js (REST direto)

​Exemplo PHP (REST direto)

​Referência interativa

Como usar o Swagger UI

Autenticação

Ambientes

Categorias de endpoints

Auth

Quotes

Orders

Tracking

Labels

Carriers

Contracts

Webhooks

Integrations

Returns

Notifications

Multi-warehouse

Address

Carbon

Insurance

ML

EDI

Bids (Freight Bids)

VRP (Roteirização)

Fleet & Drivers

Export

CT-e & Auditoria

Convenções da API

Formato

Códigos de status

Formato de Resposta

Rate limiting

Paginação

Erros

Exemplos de uso

Exemplo cURL (cotação)

Exemplo Node.js (REST direto)

Exemplo PHP (REST direto)

Referência interativa