Pentru dezvoltatori
API și webhookuri
Magazinul online sau alt sistem trimite comenzile în Routehive ca opriri și primește starea livrării prin webhook sau interogare. Disponibil în pachetele Pro și Flotă.
Autentificare
Proprietarul sau un admin creează cheia API pe pagina API și webhookuri din aplicație. Cheia apare o singură dată. Trimiteți-o în antetul fiecărei cereri ca token Bearer. Cu o cheie doar pentru citire nu se pot adăuga opriri.
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"]
}'Endpointuri
GET /api/v1/routes?date=YYYY-MM-DD- Rutele unei zile (implicit azi, în fusul orar al companiei).
GET /api/v1/routes/{id}- O rută cu opririle ei, în ordine.
POST /api/v1/stops- O oprire nouă, de exemplu o comandă online.
GET /api/v1/stops/{id}- Starea unei opriri: livrată, eșuată, sumă încasată, fotografie și semnătură.
Adăugarea unei opriri
Fără rută, oprirea ajunge în ruta Primite a zilei, de unde dispecerul o alocă. Dacă retrimiteți același număr de comandă (reference) pentru aceeași zi, nu se creează o oprire nouă: primiți înapoi oprirea existentă. Retrimiterea este sigură.
Câmpuri
address- Adresa (obligatorie). Cu coordonate, căutarea adresei este omisă.
name- Numele destinatarului sau al firmei.
phone, email- Telefon și e-mail pentru notificări.
reference- Numărul comenzii: identifică oprirea în webhookuri și previne dublurile.
cod_amount, payment_required- Ramburs în cea mai mică unitate a monedei (forint: forinți întregi, euro: cenți).
date- Ziua rutei Primite (AAAA-LL-ZZ). Implicit azi.
route_id- O rută anume în locul rutei Primite, dacă mai poate primi opriri.
packages- Codurile de bare ale coletelor: șoferul le scanează înainte de livrare.
require_photo, require_signature- Fotografie sau semnătură obligatorie la livrare.
Webhookuri
Setați adresa webhookului pe aceeași pagină (doar https) și alegeți evenimentele. Routehive trimite un JSON prin POST pentru fiecare eveniment; conținutul este același ca răspunsul stării unei opriri.
stop.delivered- O oprire a fost livrată (cu suma încasată și indicatorii de fotografie și semnătură).
stop.failed- O livrare a eșuat (cu nota șoferului).
route.dispatched- O rută a fost trimisă șoferului.
route.completed- O rută a fost finalizată.
{
"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
}
}Verificarea semnăturii
Fiecare cerere are antetul X-Routehive-Signature: t=marcaj de timp,v1=semnătură. Semnătura este HMAC-SHA256 al marcajului de timp, al unui punct și al corpului brut, cu secretul webhookului. Dacă nu se potrivește, respingeți cererea.
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"));
}Orice răspuns 2xx confirmă primirea. La erori reîncercăm tot mai rar (1 minut, 5 minute, 30 de minute, 2 ore, 12 ore, 24 de ore). După 50 de erori la rând, webhookul se dezactivează și proprietarul primește un e-mail.
Erori și limite
Erorile arată așa: {"error": {"code": …, "message": …}}. Codul este în engleză, mesajul în limba companiei. Fiecare cheie poate face 120 de cereri pe minut; peste această limită primiți 429.
Încă de mâine dimineață puteți planifica așa
Înregistrați-vă, adăugați șoferii, încărcați adresele. Gratuit până la 15 opriri în total, în 2 curse, fără card bancar.