Skoči na vsebino

Za razvijalce

API in spletni kavlji

Vaša spletna trgovina ali drug sistem pošilja naročila v Routehive kot postanke in prejme stanje dostave prek spletnega kavlja ali poizvedbe. Na voljo v paketih Pro in Flota.

Strojno berljiv opis (OpenAPI)

Preverjanje pristnosti

Ključ API ustvari lastnik ali skrbnik na strani API in spletni kavlji v aplikaciji. Ključ je prikazan le enkrat. Pošljite ga v glavi vsake zahteve kot žeton Bearer. S ključem samo za branje ni mogoče dodajati postankov.

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

Končne točke

GET /api/v1/routes?date=YYYY-MM-DD
Poti enega dne (privzeto danes, v časovnem pasu podjetja).
GET /api/v1/routes/{id}
Pot s postanki po vrstnem redu.
POST /api/v1/stops
Nov postanek, na primer spletno naročilo.
GET /api/v1/stops/{id}
Stanje postanka: dostavljeno, neuspešno, pobrani znesek, fotografija in podpis.

Dodajanje postanka

Brez poti gre postanek v pot Dohodne tistega dne, od koder ga dodeli dispečer. Če isto številko naročila (reference) za isti dan pošljete znova, nov postanek ne nastane: dobite obstoječega. Ponovno pošiljanje je varno.

Polja

address
Naslov (obvezno). S koordinatami se iskanje naslova preskoči.
name
Ime prejemnika ali podjetja.
phone, email
Telefon in e-pošta za obvestila.
reference
Vaša številka naročila: po njej prepoznate postanek v spletnem kavlju in preprečuje podvojitve.
cod_amount, payment_required
Plačilo po povzetju v najmanjši enoti valute (forint: celi forinti, evro: centi).
date
Dan poti Dohodne (LLLL-MM-DD). Privzeto danes.
route_id
Določena pot namesto Dohodnih, če jo je še mogoče dopolniti.
packages
Črtne kode paketov: voznik jih pred dostavo skenira.
require_photo, require_signature
Obvezna fotografija ali podpis ob dostavi.

Spletni kavlji

Naslov spletnega kavlja nastavite na isti strani (samo https) in izberete dogodke. Routehive pri vsakem dogodku pošlje JSON z metodo POST; vsebina je enaka odgovoru o stanju postanka.

stop.delivered
Postanek je dostavljen (s pobranim zneskom in podatkom o fotografiji in podpisu).
stop.failed
Dostava ni uspela (z voznikovo opombo).
route.dispatched
Pot je izdana vozniku.
route.completed
Pot je zaključ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
  }
}

Preverjanje podpisa

Vsaka zahteva ima glavo X-Routehive-Signature: t=časovni žig,v1=podpis. Podpis je HMAC-SHA256 časovnega žiga, pike in surove vsebine s skrivnostjo spletnega kavlja. Če se ne ujema, zahtevo zavrnite.

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

Vsak odgovor 2xx potrdi prejem. Ob napakah poskušamo vedno redkeje (1 minuta, 5 minut, 30 minut, 2 uri, 12 ur, 24 ur). Po 50 zaporednih napakah se spletni kavelj izklopi, lastnik pa prejme e-pošto.

Napake in omejitve

Napake so oblike {"error": {"code": …, "message": …}}. Koda je v angleščini, sporočilo v jeziku vašega podjetja. Vsak ključ lahko pošlje 120 zahtev na minuto; nad tem dobite 429.

API in spletni kavlji

Že jutri zjutraj lahko načrtujete tako

Registrirajte se, dodajte voznike, naložite naslove. Brezplačno skupaj do 15 postankov v 2 turah, brez plačilne kartice.