Para programadores
API e webhooks
A sua loja online ou outro sistema envia as encomendas à Routehive como paragens e recebe o estado da entrega por webhook ou consulta. Disponível nos planos Pro e Frota.
Autenticação
O proprietário ou um administrador cria a chave de API na página API e webhooks da aplicação. A chave só é mostrada uma vez. Envie-a no cabeçalho de cada pedido como token Bearer. Com uma chave só de leitura não é possível adicionar paragens.
curl -X POST https://routehive.eu/api/v1/stops \
-H "Authorization: Bearer rh_..." \
-H "Content-Type: application/json" \
-d '{
"address": "Budapest, Andrássy út 1.",
"name": "Example Ltd.",
"phone": "+36 30 123 4567",
"reference": "WS-1001",
"cod_amount": 12500,
"packages": ["PKG-1001"]
}'Endpoints
GET /api/v1/routes?date=YYYY-MM-DD- As rotas de um dia (por omissão hoje, no fuso horário da empresa).
GET /api/v1/routes/{id}- Uma rota com as suas paragens, por ordem.
POST /api/v1/stops- Uma nova paragem, por exemplo uma encomenda online.
GET /api/v1/stops/{id}- Estado de uma paragem: entregue, falhada, valor cobrado, foto e assinatura.
Adicionar uma paragem
Sem rota, a paragem vai para a rota Recebidas do dia, de onde o despachante a atribui. Se reenviar o mesmo número de encomenda (reference) para o mesmo dia, não é criada uma nova paragem: recebe a existente. Reenviar é seguro.
Campos
address- A morada (obrigatória). Com coordenadas, a pesquisa da morada é ignorada.
name- Nome do destinatário ou da empresa.
phone, email- Telefone e e-mail para notificações.
reference- O seu número de encomenda: identifica a paragem nos webhooks e evita duplicados.
cod_amount, payment_required- Cobrança na entrega na menor unidade da moeda (forint: forints inteiros, euro: cêntimos).
date- Dia da rota Recebidas (AAAA-MM-DD). Por omissão hoje.
route_id- Uma rota específica em vez de Recebidas, se ainda puder receber paragens.
packages- Códigos de barras das embalagens: o motorista lê-os antes da entrega.
require_photo, require_signature- Foto ou assinatura obrigatória na entrega.
Webhooks
Defina o URL do webhook na mesma página (só https) e escolha os eventos. A Routehive envia um JSON por POST em cada evento; o conteúdo é o mesmo da resposta ao estado de uma paragem.
stop.delivered- Uma paragem foi entregue (com o valor cobrado e indicação de foto e assinatura).
stop.failed- Uma entrega falhou (com a nota do motorista).
route.dispatched- Uma rota foi enviada ao motorista.
route.completed- Uma rota foi concluída.
{
"event": "stop.delivered",
"event_id": "stop_..._delivered_20261120143005123",
"created_at": "2026-11-20T14:30:05Z",
"data": {
"id": "...",
"route_id": "...",
"reference": "WS-1001",
"status": "delivered",
"delivered_at": "2026-11-20T14:30:04Z",
"note": null,
"payment_required": true,
"paid": true,
"cod_amount": 12500,
"collected_amount": 12500,
"has_photo": true,
"has_signature": false
}
}Verificar a assinatura
Cada pedido tem o cabeçalho X-Routehive-Signature: t=carimbo temporal,v1=assinatura. A assinatura é o HMAC-SHA256 do carimbo temporal, de um ponto e do corpo em bruto, com o segredo do webhook. Se não corresponder, rejeite o pedido.
import { createHmac, timingSafeEqual } from "node:crypto";
// header: X-Routehive-Signature, body: the raw request body (string)
function verify(header, body, secret) {
const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const expected = createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
return fresh && timingSafeEqual(Buffer.from(v1, "hex"), Buffer.from(expected, "hex"));
}Qualquer resposta 2xx confirma a receção. Em caso de erro, tentamos de novo cada vez menos (1 minuto, 5 minutos, 30 minutos, 2 horas, 12 horas, 24 horas). Após 50 erros seguidos, o webhook é desativado e o proprietário recebe um e-mail.
Erros e limites
Os erros têm a forma {"error": {"code": …, "message": …}}. O código está em inglês, a mensagem na língua da sua empresa. Cada chave pode fazer 120 pedidos por minuto; acima disso recebe 429.
Planeie assim as rotas de amanhã de manhã
Registe-se, adicione os seus motoristas e carregue os seus endereços. Grátis para 15 paragens no total, em 2 rotas, sem cartão de crédito.