Ugrás a tartalomra

Fejlesztőknek

API és webhookok

A webshopod vagy más rendszered címként küldi a rendeléseket a Routehive-ba, a kézbesítés állapotát pedig webhookkal vagy lekérdezéssel kapja vissza. A Pro és a Flotta csomagban érhető el.

Gépi leírás (OpenAPI)

Hitelesítés

API-kulcsot a tulajdonos vagy az admin hoz létre az app API és webhookok oldalán. A kulcs csak egyszer látszik. Minden kérés fejlécében küldd, Bearer tokenként. A csak olvasásra szóló kulccsal cím nem vehető fel.

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"]
  }'

Végpontok

GET /api/v1/routes?date=YYYY-MM-DD
Egy nap körei (alapból ma, a cég időzónájában).
GET /api/v1/routes/{id}
Egy kör a megállóival, sorrendben.
POST /api/v1/stops
Új cím, például egy webshop-rendelés.
GET /api/v1/stops/{id}
Egy cím állapota: kézbesítve, sikertelen, beszedett összeg, fotó és aláírás.

Cím felvétele

Ha nem adsz meg kört, a cím a nap Beérkező körébe kerül, onnan a diszpécser osztja ki. Ha ugyanazt a rendelésszámot (reference) újra elküldöd ugyanarra a napra, nem lesz belőle új cím: a meglévőt kapod vissza. Így az újraküldés biztonságos.

Mezők

address
A cím (kötelező). Koordinátával a címkeresés kimarad.
name
A címzett neve vagy cégneve.
phone, email
Telefonszám és e-mail cím az értesítésekhez.
reference
A rendelésszámod: ezzel ismered fel a webhookban, és ez védi ki a duplázást.
cod_amount, payment_required
Utánvét a pénznem legkisebb egységében (forintban egész forint, euróban cent).
date
A Beérkező kör napja (ÉÉÉÉ-HH-NN). Alapból ma.
route_id
Megadott kör a Beérkező helyett, ha még bővíthető.
packages
Csomagkódok: a sofőr kézbesítés előtt beolvassa őket.
require_photo, require_signature
Kötelező fotó vagy aláírás a kézbesítéshez.

Webhookok

A webhook címét ugyanazon az oldalon adod meg, csak https címet. Kiválasztod, mely eseményekről kérsz értesítést. A Routehive minden eseményről JSON-t küld POST kéréssel, a tartalom ugyanaz, mint a cím lekérdezésének válasza.

stop.delivered
Egy cím kézbesítve (beszedett összeggel, fotó és aláírás jelzéssel).
stop.failed
Egy kézbesítés sikertelen (a sofőr megjegyzésével).
route.dispatched
Egy kör kiadva a sofőrnek.
route.completed
Egy kör lezárult.
{
  "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
  }
}

Az aláírás ellenőrzése

Minden kérés X-Routehive-Signature fejlécet kap: t=időbélyeg,v1=aláírás. Az aláírás a HMAC-SHA256 kód a webhook titkával, ezen a szövegen: az időbélyeg, egy pont, majd a nyers törzs. Ha nem egyezik, dobd el a kérést.

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"));
}

Bármely 2xx válasz nyugtázza a küldést. Hibánál egyre ritkábban próbáljuk újra (1 perc, 5 perc, 30 perc, 2 óra, 12 óra, 24 óra). 50 egymás utáni hiba után a webhookot kikapcsoljuk, és levelet küldünk a tulajdonosnak.

Hibák és korlátok

Hibánál a válasz: {"error": {"code": …, "message": …}}. A kód angol, a szöveg a céged nyelvén. Kulcsonként percenként 120 kérés fér bele, felette 429 jön.

API és webhookok

Holnap reggel már így tervezhetsz

Regisztrálj, vedd fel a sofőröket, töltsd be a címeket. Összesen 15 megállóig, 2 körben ingyenes, bankkártya nélkül.