RotaCheck API

REST API pra integrar o RotaCheck com seus sistemas: ERP, e-commerce, marketplace ou qualquer aplicação que precise enviar e acompanhar entregas.

A API segue convenções REST, autentica via API key, retorna JSON, e usa códigos HTTP padrão. Todas as URLs começam com:

https://kiqnqabcdxecmfswiejv.supabase.co/functions/v1/api/v1

Beta: a v1 da API está em produção. Mudanças breaking serão anunciadas com 90 dias de antecedência via header Sunset:.

Autenticação

Toda requisição precisa do header X-API-Key com sua chave. Gere chaves no painel API do dashboard.

curl https://kiqnqabcdxecmfswiejv.supabase.co/functions/v1/api/v1/deliveries \
  -H "X-API-Key: rk_live_abc123..."

⚠️ Nunca exponha sua chave no frontend. Ela é equivalente à senha da sua empresa — guarde no backend ou em variáveis de ambiente.

Scopes (permissões)

Cada chave tem um conjunto de scopes que define o que ela pode fazer:

deliveries:read deliveries:write fleet:read fleet:write drivers:read drivers:write analytics:read tracking:write webhooks:manage *

Use o mínimo necessário — chave com * só pra integrações internas.

Rate limits

Por padrão: 60 requisições/minuto e 5.000/dia por chave.

Respostas incluem headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1747234567

Ao estourar você recebe HTTP 429 Too Many Requests. Implemente exponential backoff: 1s, 2s, 4s, 8s.

Erros

Código	Significado
`400`	Requisição inválida (parâmetro faltando, formato errado)
`401`	Chave inválida ou faltando
`403`	Chave válida mas sem scope necessário
`404`	Recurso não encontrado
`429`	Rate limit estourado
`5xx`	Erro do servidor — tente de novo

Erros retornam JSON com detalhes:

{
  "error": {
    "type": "invalid_request",
    "code": "missing_scope",
    "message": "Esta chave não tem scope 'deliveries:write'",
    "request_id": "req_abc123"
  }
}

Deliveries

Recurso principal: entregas com endereço, cliente, motorista atribuído, status, time window.

POST /v1/deliveries deliveries:write

Cria uma nova entrega.

Parâmetros (body JSON)

Nome	Tipo	Descrição
`cliente`obrig	string	Nome do destinatário
`endereco`obrig	string	Endereço completo
`pedido`	string	Número do pedido (NF, OS, etc)
`customer_phone`	string	WhatsApp do cliente (só dígitos)
`weight`	number	Peso em kg
`time_window_start`	time	Janela de entrega — início (HH:MM)
`time_window_end`	time	Janela de entrega — fim (HH:MM)
`required_cnh`	string	CNH mínima exigida (A/B/C/D/E)
`required_skills`	array	Skills exigidas (refrigerado, frágil, etc)

Exemplo

curl -X POST https://kiqnqabcdxecmfswiejv.supabase.co/functions/v1/api/v1/deliveries \
  -H "X-API-Key: rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "cliente": "João Silva",
    "endereco": "Av. Brasil 100, Bauru SP",
    "pedido": "NF-12345",
    "time_window_end": "18:00"
  }'

GET /v1/deliveries deliveries:read

Lista entregas da empresa. Suporta filtros via query string.

Query param	Descrição
`status`	Filtra por status: pendente, em_rota, entregue, parcial
`driver_id`	Filtra por motorista
`from` / `to`	Range de data (ISO 8601)
`limit`	Max 100, default 25

PATCH /v1/deliveries/:id deliveries:write

Atualiza campos de uma entrega. Útil pra reatribuir motorista, mudar status, etc.

Drivers

GET /v1/drivers drivers:read

Lista motoristas com CNH, skills, success_history.

Vehicles

GET /v1/vehicles fleet:read

Lista veículos com capacidade, vehicle_type, features.

Tracking Links

POST /v1/tracking-links tracking:write

Gera link público rotacheckapp.com/t/<TOKEN> pra cliente acompanhar entrega em tempo real.

POST /v1/tracking-links
{ "delivery_id": "uuid-here", "expires_in_hours": 48 }

→ 200 OK
{ "token": "ABC123", "url": "https://rotacheckapp.com/t/ABC123", "expires_at": "2026-05-13T18:00:00Z" }

Analytics

GET /v1/analytics/leaderboard analytics:read

Ranking de motoristas (score 0-100 = 50% sucesso + 30% pontualidade + 20% volume).

GET /v1/analytics/forecast analytics:read

Forecast de demanda 5 semanas à frente baseado em rotas recorrentes + padrão histórico.

Webhooks

Receba eventos em tempo real no seu servidor. Configure URLs no painel de Integrações.

Eventos disponíveis

Evento	Quando dispara
`delivery.created`	Nova entrega cadastrada (manual, import, ou via API)
`delivery.dispatched`	Entrega muda pra status `em_rota`
`delivery.delivered`	Entrega muda pra status `entregue`
`delivery.failed`	Entrega marcada como `parcial` ou `nao_entregue`
`dispatch.auto_assigned`	Auto-dispatch atribuiu motorista (FASE 1.3 / 3.2)

Verificação HMAC

Todo payload é assinado com HMAC-SHA256. Confira o header X-RotaCheck-Signature:

// Node.js
const crypto = require('crypto');
const expected = crypto.createHmac('sha256', WEBHOOK_SECRET)
  .update(req.rawBody)
  .digest('hex');
const actual = req.headers['x-rotacheck-signature'];
if (expected !== actual) return res.status(401).end();