Ir para o conteúdo

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.

Descrição legível por máquina (OpenAPI)

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.

API e webhooks

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.