Preskočiť na obsah

Pre vývojárov

API a webhooky

Váš e-shop alebo iný systém posiela objednávky do Routehive ako zastávky a stav doručenia dostáva späť cez webhook alebo dopyt. Dostupné v balíkoch Pro a Flotila.

Strojovo čitateľný opis (OpenAPI)

Overenie

Kľúč API vytvorí vlastník alebo admin na stránke API a webhooky v aplikácii. Kľúč sa zobrazí len raz. Posielajte ho v hlavičke každej požiadavky ako token Bearer. S kľúčom len na čítanie nemožno pridávať zastávky.

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

Endpointy

GET /api/v1/routes?date=YYYY-MM-DD
Trasy jedného dňa (predvolene dnes, v časovom pásme firmy).
GET /api/v1/routes/{id}
Trasa so zastávkami v poradí.
POST /api/v1/stops
Nová zastávka, napríklad objednávka z e-shopu.
GET /api/v1/stops/{id}
Stav zastávky: doručená, neúspešná, vybraná suma, fotka a podpis.

Pridanie zastávky

Bez trasy sa zastávka dostane do trasy Prichádzajúce daného dňa, odkiaľ ju dispečer pridelí. Ak znova pošlete to isté číslo objednávky (reference) na ten istý deň, nová zastávka nevznikne: dostanete existujúcu. Opakované odoslanie je bezpečné.

Polia

address
Adresa (povinná). So súradnicami sa vyhľadanie adresy vynechá.
name
Meno príjemcu alebo názov firmy.
phone, email
Telefón a e-mail pre upozornenia.
reference
Vaše číslo objednávky: podľa neho spoznáte zastávku vo webhooku a bráni duplicitám.
cod_amount, payment_required
Dobierka v najmenšej jednotke meny (forint: celé forinty, euro: centy).
date
Deň trasy Prichádzajúce (RRRR-MM-DD). Predvolene dnes.
route_id
Konkrétna trasa namiesto Prichádzajúcich, ak sa ešte dá rozšíriť.
packages
Čiarové kódy balíkov: vodič ich pred doručením naskenuje.
require_photo, require_signature
Povinná fotka alebo podpis pri doručení.

Webhooky

Adresu webhooku nastavíte na tej istej stránke (len https) a vyberiete udalosti. Routehive pošle pri každej udalosti JSON cez POST; obsah je rovnaký ako odpoveď o stave zastávky.

stop.delivered
Zastávka bola doručená (s vybranou sumou a údajom o fotke a podpise).
stop.failed
Doručenie zlyhalo (s poznámkou vodiča).
route.dispatched
Trasa bola vydaná vodičovi.
route.completed
Trasa bola dokončená.
{
  "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
  }
}

Overenie podpisu

Každá požiadavka má hlavičku X-Routehive-Signature: t=časová pečiatka,v1=podpis. Podpis je HMAC-SHA256 z časovej pečiatky, bodky a surového tela s tajomstvom webhooku. Ak nesedí, požiadavku zahoďte.

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

Akákoľvek odpoveď 2xx potvrdí prijatie. Pri chybách skúšame znova čoraz zriedkavejšie (1 minúta, 5 minút, 30 minút, 2 hodiny, 12 hodín, 24 hodín). Po 50 chybách za sebou sa webhook vypne a vlastník dostane e-mail.

Chyby a limity

Chyby vyzerajú takto: {"error": {"code": …, "message": …}}. Kód je po anglicky, správa v jazyku vašej firmy. Každý kľúč môže poslať 120 požiadaviek za minútu; nad tento limit príde 429.

API a webhooky

Už zajtra ráno môžete plánovať takto

Zaregistrujte sa, pridajte vodičov, nahrajte adresy. Zadarmo spolu do 15 zastávok v 2 trasách, bez platobnej karty.