Vai al contenuto

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.

Descrizione leggibile dalle macchine (OpenAPI)

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.

API e webhook

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.