Prijeđi na sadržaj

Za razvojne inženjere

API i webhookovi

Vaša web-trgovina ili drugi sustav šalje narudžbe u Routehive kao stanice i dobiva status dostave putem webhooka ili upita. Dostupno u paketima Pro i Flota.

Strojno čitljiv opis (OpenAPI)

Autentifikacija

API ključ stvara 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 točke

GET /api/v1/routes?date=YYYY-MM-DD
Rute jednog dana (zadano danas, u vremenskoj zoni tvrtke).
GET /api/v1/routes/{id}
Ruta sa stanicama redom.
POST /api/v1/stops
Nova stanica, primjerice narudžba iz web-trgovine.
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 narudžbe (reference) za isti dan pošaljete ponovno, nova stanica ne nastaje: dobivate postojeću. Ponovno slanje je sigurno.

Polja

address
Adresa (obavezno). Uz koordinate traženje adrese se preskače.
name
Ime primatelja ili naziv tvrtke.
phone, email
Telefon i e-pošta za obavijesti.
reference
Vaš broj narudžbe: po njemu prepoznajete stanicu u webhooku i sprječava duplikate.
cod_amount, payment_required
Pouzeće u najmanjoj jedinici valute (forinta: cijele forinte, euro: centi).
date
Dan rute Pristigle (GGGG-MM-DD). Zadano danas.
route_id
Određena ruta umjesto Pristiglih, ako se još može dopunjavati.
packages
Crtični 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 (s naplaćenim iznosom i oznakom fotografije i potpisa).
stop.failed
Dostava nije uspjela (s napomenom vozača).
route.dispatched
Ruta je izdana 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, točke i sirovog tijela uz tajnu webhooka. Ako se ne podudara, 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 primitak. Kod pogrešaka pokušavamo sve rjeđe (1 minuta, 5 minuta, 30 minuta, 2 sata, 12 sati, 24 sata). Nakon 50 uzastopnih pogrešaka webhook se isključuje, a vlasnik dobiva e-poštu.

Pogreške i ograničenja

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

API i webhookovi

Isplanirajte sutrašnje jutarnje rute ovako

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