Për zhvilluesit
API dhe webhook
Dyqani juaj online ose një sistem tjetër i dërgon porositë në Routehive si ndalesa dhe merr statusin e dorëzimit me webhook ose me pyetje. I disponueshëm në paketat Pro dhe Fleet.
Vërtetimi
Çelësin API e krijon pronari ose administratori në faqen API dhe webhook të aplikacionit. Çelësi shfaqet vetëm një herë. Dërgojeni në kokën e çdo kërkese si token Bearer. Me çelës vetëm për lexim nuk mund të shtohen ndalesa.
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"]
}'Pikat fundore
GET /api/v1/routes?date=YYYY-MM-DD- Rrugët e një dite (si parazgjedhje sot, në zonën kohore të kompanisë).
GET /api/v1/routes/{id}- Një rrugë me ndalesat sipas radhës.
POST /api/v1/stops- Një ndalesë e re, p.sh. një porosi nga dyqani online.
GET /api/v1/stops/{id}- Statusi i një ndalese: dorëzuar, dështuar, shuma e mbledhur, foto dhe nënshkrim.
Shtimi i një ndalese
Pa rrugë, ndalesa shkon te rruga Hyrëse e ditës, prej nga e cakton dispeçeri. Nëse e dërgoni përsëri të njëjtin numër porosie (reference) për të njëjtën ditë, nuk krijohet ndalesë e re: merrni atë ekzistuese. Ridërgimi është i sigurt.
Fushat
address- Adresa (e detyrueshme). Me koordinata, kërkimi i adresës anashkalohet.
name- Emri i marrësit ose i kompanisë.
phone, email- Telefoni dhe emaili për njoftimet.
reference- Numri juaj i porosisë: me të e njihni ndalesën në webhook dhe ai parandalon dyfishimet.
cod_amount, payment_required- Pagesë në dorëzim në njësinë më të vogël të monedhës (forint: forinta të plotë, euro: centë).
date- Dita e rrugës Hyrëse (VVVV-MM-DD). Si parazgjedhje sot.
route_id- Një rrugë e caktuar në vend të Hyrëses, nëse ende mund të plotësohet.
packages- Barkodet e pakove: shoferi i skanon para dorëzimit.
require_photo, require_signature- Foto ose nënshkrim i detyrueshëm në dorëzim.
Webhook
Adresën e webhook-ut e vendosni në të njëjtën faqe (vetëm https) dhe zgjidhni ngjarjet. Routehive dërgon një JSON me POST për çdo ngjarje; përmbajtja është e njëjtë me përgjigjen e statusit të ndalesës.
stop.delivered- Një ndalesë u dorëzua (me shumën e mbledhur dhe treguesit e fotos dhe nënshkrimit).
stop.failed- Një dorëzim dështoi (me shënimin e shoferit).
route.dispatched- Një rrugë iu dha shoferit.
route.completed- Një rrugë përfundoi.
{
"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
}
}Verifikimi i nënshkrimit
Çdo kërkesë ka kokën X-Routehive-Signature: t=vula kohore,v1=nënshkrimi. Nënshkrimi është HMAC-SHA256 i vulës kohore, një pike dhe trupit të papërpunuar, me sekretin e webhook-ut. Nëse nuk përputhet, refuzojeni kërkesën.
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"));
}Çdo përgjigje 2xx e konfirmon marrjen. Në rast gabimi provojmë gjithnjë e më rrallë (1 minutë, 5 minuta, 30 minuta, 2 orë, 12 orë, 24 orë). Pas 50 gabimeve radhazi, webhook-u çaktivizohet dhe pronari merr një email.
Gabimet dhe kufijtë
Gabimet duken kështu: {"error": {"code": …, "message": …}}. Kodi është në anglisht, mesazhi në gjuhën e kompanisë suaj. Çdo çelës mund të bëjë 120 kërkesa në minutë; mbi këtë merrni 429.
Planifikoni kështu itineraret e nesërme të mëngjesit
Regjistrohuni, shtoni shoferët tuaj, ngarkoni adresat tuaja. Falas për gjithsej 15 ndalesa në 2 itinerare, pa kartë krediti.