Per sviluppatori
API e webhook
Il tuo e-commerce o un altro sistema invia gli ordini a Routehive come fermate e riceve lo stato della consegna via webhook o interrogazione. Disponibile nei piani Pro e Flotta.
Autenticazione
Il titolare o un admin crea la chiave API nella pagina API e webhook dell'app. La chiave viene mostrata una sola volta. Inviala nell'intestazione di ogni richiesta come token Bearer. Con una chiave di sola lettura non si possono aggiungere fermate.
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"]
}'Endpoint
GET /api/v1/routes?date=YYYY-MM-DD- I giri di un giorno (predefinito: oggi, nel fuso orario dell'azienda).
GET /api/v1/routes/{id}- Un giro con le sue fermate, in ordine.
POST /api/v1/stops- Una nuova fermata, ad esempio un ordine online.
GET /api/v1/stops/{id}- Stato di una fermata: consegnata, non riuscita, importo incassato, foto e firma.
Aggiungere una fermata
Senza giro, la fermata finisce nel giro In arrivo del giorno, da cui il dispatcher la assegna. Se reinvii lo stesso numero d'ordine (reference) per lo stesso giorno, non nasce una nuova fermata: ricevi quella esistente. Il reinvio è quindi sicuro.
Campi
address- L'indirizzo (obbligatorio). Con le coordinate la geocodifica viene saltata.
name- Nome del destinatario o dell'azienda.
phone, email- Telefono ed e-mail per le notifiche.
reference- Il tuo numero d'ordine: identifica la fermata nei webhook ed evita i doppioni.
cod_amount, payment_required- Contrassegno nella più piccola unità della valuta (fiorino: fiorini interi, euro: centesimi).
date- Giorno del giro In arrivo (AAAA-MM-GG). Predefinito: oggi.
route_id- Un giro preciso al posto di In arrivo, se può ancora ricevere fermate.
packages- Codici a barre dei colli: l'autista li scansiona prima della consegna.
require_photo, require_signature- Foto o firma obbligatoria per la consegna.
Webhook
Imposta l'URL del webhook nella stessa pagina (solo https) e scegli gli eventi. Routehive invia un JSON in POST per ogni evento; il contenuto è lo stesso della risposta sullo stato della fermata.
stop.delivered- Una fermata è stata consegnata (con importo incassato e indicazione di foto e firma).
stop.failed- Una consegna non è riuscita (con la nota dell'autista).
route.dispatched- Un giro è stato inviato all'autista.
route.completed- Un giro è stato completato.
{
"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
}
}Verificare la firma
Ogni richiesta ha l'intestazione X-Routehive-Signature: t=timestamp,v1=firma. La firma è l'HMAC-SHA256 di timestamp, un punto e il corpo grezzo, con il segreto del webhook. Se non corrisponde, scarta la richiesta.
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"));
}Qualsiasi risposta 2xx conferma la ricezione. In caso di errore riproviamo sempre più di rado (1 minuto, 5 minuti, 30 minuti, 2 ore, 12 ore, 24 ore). Dopo 50 errori consecutivi il webhook viene disattivato e il titolare riceve un'e-mail.
Errori e limiti
Gli errori hanno la forma {"error": {"code": …, "message": …}}. Il codice è in inglese, il messaggio nella lingua della tua azienda. Ogni chiave può fare 120 richieste al minuto; oltre ricevi 429.
Già domani mattina potrà pianificare così
Si registri, aggiunga gli autisti, carichi gli indirizzi. Gratis fino a 15 fermate in totale, in 2 giri, senza carta di credito.