Kapërce te përmbajtja

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.

Përshkrim i lexueshëm nga makina (OpenAPI)

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.

API dhe webhook

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.