Siirry sisältöön

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.

Koneluettava kuvaus (OpenAPI)

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.

API ja webhookit

Suunnittele huomisen aamun reitit näin

Rekisteröidy, lisää kuljettajasi, lataa osoitteesi. Maksuton yhteensä 15 pysähdystä kahdella reitillä, ei luottokorttia.