Spring til indhold

Til udviklere

API og webhooks

Din webshop eller et andet system sender ordrer til Routehive som stop og får leveringsstatus tilbage via webhook eller forespørgsel. Tilgængelig i Pro- og Flåde-pakken.

Maskinlæsbar beskrivelse (OpenAPI)

Godkendelse

Ejeren eller en administrator opretter API-nøglen på siden API og webhooks i appen. Nøglen vises kun én gang. Send den i headeren på hver forespørgsel som Bearer-token. Med en skrivebeskyttet nøgle kan der ikke tilføjes stop.

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

Endpoints

GET /api/v1/routes?date=YYYY-MM-DD
Ruterne for en dag (standard i dag, i virksomhedens tidszone).
GET /api/v1/routes/{id}
En rute med dens stop i rækkefølge.
POST /api/v1/stops
Et nyt stop, for eksempel en webshopordre.
GET /api/v1/stops/{id}
Status for et stop: leveret, mislykket, opkrævet beløb, foto og underskrift.

Tilføj et stop

Uden rute kommer stoppet på dagens Indgående-rute, hvorfra disponenten fordeler det. Sender du det samme ordrenummer (reference) for den samme dag igen, oprettes der ikke et nyt stop: du får det eksisterende tilbage. Det er derfor sikkert at sende igen.

Felter

address
Adressen (påkrævet). Med koordinater springes adressesøgningen over.
name
Modtagerens eller virksomhedens navn.
phone, email
Telefon og e-mail til notifikationer.
reference
Dit ordrenummer: det genkender du stoppet på i webhooken, og det forhindrer dubletter.
cod_amount, payment_required
Efterkrav i valutaens mindste enhed (forint: hele forint, euro: cent).
date
Dagen for Indgående-ruten (ÅÅÅÅ-MM-DD). Standard i dag.
route_id
En bestemt rute i stedet for Indgående, hvis den stadig kan udvides.
packages
Pakkestregkoder: chaufføren scanner dem før leveringen.
require_photo, require_signature
Påkrævet foto eller underskrift ved levering.

Webhooks

Webhook-URL'en angives på samme side (kun https), hvor du også vælger hændelserne. Routehive sender en JSON med POST for hver hændelse; indholdet er det samme som svaret på status for et stop.

stop.delivered
Et stop er leveret (med opkrævet beløb og angivelse af foto og underskrift).
stop.failed
En levering mislykkedes (med chaufførens note).
route.dispatched
En rute er udsendt til chaufføren.
route.completed
En rute er afsluttet.
{
  "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
  }
}

Kontrol af signaturen

Hver forespørgsel har headeren X-Routehive-Signature: t=tidsstempel,v1=signatur. Signaturen er HMAC-SHA256 af tidsstemplet, et punktum og den rå body med webhook-hemmeligheden. Stemmer den ikke, så afvis forespørgslen.

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

Ethvert 2xx-svar bekræfter modtagelsen. Ved fejl prøver vi igen med stadig længere mellemrum (1 minut, 5 minutter, 30 minutter, 2 timer, 12 timer, 24 timer). Efter 50 fejl i træk slås webhooken fra, og ejeren får en e-mail.

Fejl og grænser

Fejl ser sådan ud: {"error": {"code": …, "message": …}}. Koden er på engelsk, beskeden på virksomhedens sprog. Hver nøgle kan lave 120 forespørgsler i minuttet; derover får du 429.

API og webhooks

Planlæg morgendagens ruter på denne måde

Tilmeld dig, tilføj dine chauffører, indlæs dine adresser. Gratis til i alt 15 stop på 2 ruter, intet kreditkort.