Kehittäjille
API ja webhookit
Verkkokauppasi tai muu järjestelmä lähettää tilaukset Routehiveen pysähdyksinä ja saa toimituksen tilan takaisin webhookilla tai kyselyllä. Käytettävissä Pro- ja Fleet-paketeissa.
Tunnistautuminen
API-avaimen luo omistaja tai ylläpitäjä sovelluksen sivulla API ja webhookit. Avain näytetään vain kerran. Lähetä se jokaisen pyynnön otsakkeessa Bearer-tunnisteena. Pelkällä lukuavaimella ei voi lisätä pysähdyksiä.
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"]
}'Rajapinnat
GET /api/v1/routes?date=YYYY-MM-DD- Päivän reitit (oletuksena tänään, yrityksen aikavyöhykkeellä).
GET /api/v1/routes/{id}- Reitti pysähdyksineen järjestyksessä.
POST /api/v1/stops- Uusi pysähdys, esimerkiksi verkkokaupan tilaus.
GET /api/v1/stops/{id}- Pysähdyksen tila: toimitettu, epäonnistui, kerätty summa, kuva ja allekirjoitus.
Pysähdyksen lisääminen
Ilman reittiä pysähdys menee päivän Saapuvat-reitille, josta ajojärjestelijä jakaa sen. Jos lähetät saman tilausnumeron (reference) samalle päivälle uudelleen, uutta pysähdystä ei synny: saat olemassa olevan. Uudelleenlähetys on siis turvallinen.
Kentät
address- Osoite (pakollinen). Koordinaateilla osoitehaku ohitetaan.
name- Vastaanottajan tai yrityksen nimi.
phone, email- Puhelin ja sähköposti ilmoituksia varten.
reference- Tilausnumerosi: sen avulla tunnistat pysähdyksen webhookissa, ja se estää kaksoiskappaleet.
cod_amount, payment_required- Jälkivaatio valuutan pienimpänä yksikkönä (forintti: kokonaiset forintit, euro: sentit).
date- Saapuvat-reitin päivä (VVVV-KK-PP). Oletuksena tänään.
route_id- Tietty reitti Saapuvien sijaan, jos siihen voi vielä lisätä.
packages- Pakettien viivakoodit: kuljettaja lukee ne ennen toimitusta.
require_photo, require_signature- Pakollinen kuva tai allekirjoitus toimituksessa.
Webhookit
Webhookin osoitteen asetat samalla sivulla (vain https), ja siellä valitset myös tapahtumat. Routehive lähettää jokaisesta tapahtumasta JSONin POST-pyynnöllä; sisältö on sama kuin pysähdyksen tilan vastaus.
stop.delivered- Pysähdys toimitettu (kerätyn summan sekä kuva- ja allekirjoitustiedon kanssa).
stop.failed- Toimitus epäonnistui (kuljettajan huomautuksen kanssa).
route.dispatched- Reitti lähetetty kuljettajalle.
route.completed- Reitti valmis.
{
"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
}
}Allekirjoituksen tarkistus
Jokaisessa pyynnössä on otsake X-Routehive-Signature: t=aikaleima,v1=allekirjoitus. Allekirjoitus on HMAC-SHA256 aikaleimasta, pisteestä ja raa'asta sisällöstä webhookin salaisuudella. Jos se ei täsmää, hylkää pyyntö.
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"));
}Mikä tahansa 2xx-vastaus kuittaa vastaanoton. Virheissä yritämme yhä harvemmin (1 minuutti, 5 minuuttia, 30 minuuttia, 2 tuntia, 12 tuntia, 24 tuntia). 50 peräkkäisen virheen jälkeen webhook poistetaan käytöstä ja omistaja saa sähköpostin.
Virheet ja rajat
Virheet näyttävät tältä: {"error": {"code": …, "message": …}}. Koodi on englanniksi, viesti yrityksesi kielellä. Kukin avain voi tehdä 120 pyyntöä minuutissa; sen yli tulee 429.
Suunnittele huomisen aamun reitit näin
Rekisteröidy, lisää kuljettajasi, lataa osoitteesi. Maksuton yhteensä 15 pysähdystä kahdella reitillä, ei luottokorttia.