Salt la conținut

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ă.

Descriere citibilă de mașină (OpenAPI)

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.

API și webhookuri

Î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.