Pređi na sadržaj

Za programere

API i webhookovi

Vaša onlajn prodavnica ili drugi sistem šalje porudžbine u Routehive kao stanice i dobija status dostave putem webhooka ili upita. Dostupno u paketima Pro i Fleet.

Mašinski čitljiv opis (OpenAPI)

Autentifikacija

API ključ kreira vlasnik ili administrator na stranici API i webhookovi u aplikaciji. Ključ se prikazuje samo jednom. Šaljite ga u zaglavlju svakog zahtjeva kao Bearer token. Ključem samo za čitanje ne mogu se dodavati stanice.

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

Krajnje tačke

GET /api/v1/routes?date=YYYY-MM-DD
Rute jednog dana (podrazumijevano danas, u vremenskoj zoni firme).
GET /api/v1/routes/{id}
Ruta sa stanicama po redu.
POST /api/v1/stops
Nova stanica, na primjer porudžbina iz onlajn prodavnice.
GET /api/v1/stops/{id}
Stanje stanice: dostavljeno, neuspjelo, naplaćeni iznos, fotografija i potpis.

Dodavanje stanice

Bez rute stanica ide u rutu Pristigle za taj dan, odakle je dispečer dodjeljuje. Ako isti broj porudžbine (reference) za isti dan pošaljete ponovo, nova stanica ne nastaje: dobijate postojeću. Ponovno slanje je bezbjedno.

Polja

address
Adresa (obavezno). Uz koordinate pretraga adrese se preskače.
name
Ime primaoca ili naziv firme.
phone, email
Telefon i e-pošta za obavještenja.
reference
Vaš broj porudžbine: po njemu prepoznajete stanicu u webhooku i sprečava duplikate.
cod_amount, payment_required
Pouzeće u najmanjoj jedinici valute (forinta: cijele forinte, euro: centi).
date
Dan rute Pristigle (GGGG-MM-DD). Podrazumijevano danas.
route_id
Određena ruta umjesto Pristiglih, ako se još može dopunjavati.
packages
Bar-kodovi paketa: vozač ih skenira prije dostave.
require_photo, require_signature
Obavezna fotografija ili potpis pri dostavi.

Webhookovi

Adresu webhooka postavljate na istoj stranici (samo https) i birate događaje. Routehive za svaki događaj šalje JSON metodom POST; sadržaj je isti kao odgovor o stanju stanice.

stop.delivered
Stanica je dostavljena (sa naplaćenim iznosom i oznakom fotografije i potpisa).
stop.failed
Dostava nije uspjela (sa napomenom vozača).
route.dispatched
Ruta je izdata vozaču.
route.completed
Ruta je završena.
{
  "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
  }
}

Provjera potpisa

Svaki zahtjev ima zaglavlje X-Routehive-Signature: t=vremenska oznaka,v1=potpis. Potpis je HMAC-SHA256 vremenske oznake, tačke i sirovog tijela uz tajnu webhooka. Ako se ne poklapa, odbacite zahtjev.

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

Svaki odgovor 2xx potvrđuje prijem. Kod grešaka pokušavamo sve rjeđe (1 minut, 5 minuta, 30 minuta, 2 sata, 12 sati, 24 sata). Nakon 50 uzastopnih grešaka webhook se isključuje, a vlasnik dobija e-poštu.

Greške i ograničenja

Greške izgledaju ovako: {"error": {"code": …, "message": …}}. Kod je na engleskom, poruka na jeziku vaše firme. Svaki ključ može poslati 120 zahtjeva u minuti; iznad toga dobijate 429.

API i webhookovi

Isplanirajte sutrašnje jutarnje rute ovako

Registrujte se, dodajte vozače, učitajte adrese. Besplatno za ukupno 15 stanica u 2 rute, bez kreditne kartice.