Hoppa till innehåll

För utvecklare

API och webhooks

Din webbutik eller ett annat system skickar beställningar till Routehive som stopp och får leveransstatus tillbaka via webhook eller förfrågan. Finns i paketen Pro och Flotta.

Maskinläsbar beskrivning (OpenAPI)

Autentisering

Ägaren eller en administratör skapar API-nyckeln på sidan API och webhooks i appen. Nyckeln visas bara en gång. Skicka den i headern på varje förfrågan som Bearer-token. Med en skrivskyddad nyckel går det inte att lägga till stopp.

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
Rutterna för en dag (standard i dag, i företagets tidszon).
GET /api/v1/routes/{id}
En rutt med dess stopp i ordning.
POST /api/v1/stops
Ett nytt stopp, till exempel en webbutiksbeställning.
GET /api/v1/stops/{id}
Status för ett stopp: levererat, misslyckat, indrivet belopp, foto och signatur.

Lägga till ett stopp

Utan rutt hamnar stoppet i dagens rutt Inkommande, där ledningscentralen fördelar det. Skickar du samma ordernummer (reference) för samma dag igen skapas inget nytt stopp: du får tillbaka det befintliga. Att skicka igen är alltså säkert.

Fält

address
Adressen (krävs). Med koordinater hoppas adressökningen över.
name
Mottagarens eller företagets namn.
phone, email
Telefon och e-post för aviseringar.
reference
Ditt ordernummer: med det känner du igen stoppet i webhooken, och det förhindrar dubbletter.
cod_amount, payment_required
Postförskott i valutans minsta enhet (forint: hela forint, euro: cent).
date
Dag för rutten Inkommande (ÅÅÅÅ-MM-DD). Standard i dag.
route_id
En viss rutt i stället för Inkommande, om den fortfarande kan utökas.
packages
Paketens streckkoder: föraren skannar dem före leveransen.
require_photo, require_signature
Obligatoriskt foto eller signatur vid leveransen.

Webhooks

Webhookens URL anger du på samma sida (endast https), där du också väljer händelser. Routehive skickar en JSON med POST för varje händelse; innehållet är detsamma som svaret på status för ett stopp.

stop.delivered
Ett stopp har levererats (med indrivet belopp och uppgift om foto och signatur).
stop.failed
En leverans misslyckades (med förarens anteckning).
route.dispatched
En rutt har skickats till föraren.
route.completed
En rutt har avslutats.
{
  "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
  }
}

Kontrollera signaturen

Varje förfrågan har headern X-Routehive-Signature: t=tidsstämpel,v1=signatur. Signaturen är HMAC-SHA256 av tidsstämpeln, en punkt och den råa bodyn med webhookhemligheten. Om den inte stämmer, avvisa förfrågan.

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

Varje 2xx-svar bekräftar mottagandet. Vid fel försöker vi igen allt mer sällan (1 minut, 5 minuter, 30 minuter, 2 timmar, 12 timmar, 24 timmar). Efter 50 fel i rad stängs webhooken av och ägaren får ett e-postmeddelande.

Fel och gränser

Fel ser ut så här: {"error": {"code": …, "message": …}}. Koden är på engelska, meddelandet på ditt företags språk. Varje nyckel kan göra 120 förfrågningar per minut; därutöver får du 429.

API och webhooks

Planera morgondagens rutter så här

Registrera dig, lägg till dina förare, ladda dina adresser. Gratis för totalt 15 stopp på 2 rutter, inget kreditkort.