Pereiti prie turinio

Kūrėjams

API ir „webhook“

Jūsų el. parduotuvė ar kita sistema siunčia užsakymus į Routehive kaip sustojimus ir gauna pristatymo būseną per „webhook“ arba užklausą. Prieinama „Pro“ ir „Fleet“ planuose.

Mašinai skaitomas aprašas (OpenAPI)

Autentifikavimas

API raktą sukuria savininkas arba administratorius programos puslapyje API ir „webhook“. Raktas rodomas tik vieną kartą. Siųskite jį kiekvienos užklausos antraštėje kaip „Bearer“ žetoną. Su tik skaitymo raktu sustojimų pridėti negalima.

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

Galiniai taškai

GET /api/v1/routes?date=YYYY-MM-DD
Vienos dienos maršrutai (numatytai šiandien, įmonės laiko juostoje).
GET /api/v1/routes/{id}
Maršrutas su sustojimais iš eilės.
POST /api/v1/stops
Naujas sustojimas, pavyzdžiui, el. parduotuvės užsakymas.
GET /api/v1/stops/{id}
Sustojimo būsena: pristatyta, nepavyko, surinkta suma, nuotrauka ir parašas.

Sustojimo pridėjimas

Be maršruto sustojimas patenka į tos dienos maršrutą „Gaunami“, iš kurio jį paskirsto dispečeris. Jei tą patį užsakymo numerį (reference) tai pačiai dienai išsiųsite dar kartą, naujas sustojimas nesukuriamas: gausite esamą. Pakartotinis siuntimas saugus.

Laukai

address
Adresas (privaloma). Su koordinatėmis adreso paieška praleidžiama.
name
Gavėjo ar įmonės pavadinimas.
phone, email
Telefonas ir el. paštas pranešimams.
reference
Jūsų užsakymo numeris: pagal jį atpažinsite sustojimą „webhook“ pranešime, jis neleidžia dubliuotis.
cod_amount, payment_required
Išperkamoji suma mažiausiu valiutos vienetu (forintas: sveiki forintai, euras: centai).
date
Maršruto „Gaunami“ diena (MMMM-MM-DD). Numatytai šiandien.
route_id
Konkretus maršrutas vietoj „Gaunami“, jei jį dar galima papildyti.
packages
Siuntinių brūkšniniai kodai: vairuotojas juos nuskenuoja prieš pristatymą.
require_photo, require_signature
Privaloma nuotrauka arba parašas pristatant.

„Webhook“

„Webhook“ adresą nustatote tame pačiame puslapyje (tik https) ir pasirenkate įvykius. Routehive apie kiekvieną įvykį siunčia JSON POST metodu; turinys toks pat kaip sustojimo būsenos atsakymas.

stop.delivered
Sustojimas pristatytas (su surinkta suma ir nuotraukos bei parašo žymomis).
stop.failed
Pristatymas nepavyko (su vairuotojo pastaba).
route.dispatched
Maršrutas išduotas vairuotojui.
route.completed
Maršrutas baigtas.
{
  "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
  }
}

Parašo tikrinimas

Kiekviena užklausa turi antraštę X-Routehive-Signature: t=laiko žyma,v1=parašas. Parašas yra HMAC-SHA256 iš laiko žymos, taško ir neapdoroto turinio su „webhook“ paslaptimi. Jei nesutampa, atmeskite užklausą.

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

Bet koks 2xx atsakymas patvirtina gavimą. Klaidų atveju bandome vis rečiau (1 minutė, 5 minutės, 30 minučių, 2 valandos, 12 valandų, 24 valandos). Po 50 klaidų iš eilės „webhook“ išjungiamas, o savininkas gauna el. laišką.

Klaidos ir ribos

Klaidos atrodo taip: {"error": {"code": …, "message": …}}. Kodas angliškas, pranešimas jūsų įmonės kalba. Kiekvienas raktas gali siųsti 120 užklausų per minutę; virš to gausite 429.

API ir „webhook“

Taip planuokite rytojaus ryto maršrutus

Užsiregistruokite, pridėkite vairuotojus, įkelkite adresus. Nemokamai iš viso 15 sustojimų 2 maršrutuose, nereikia kreditinės kortelės.