Geliştiriciler için
API ve webhook'lar
Online mağazanız veya başka bir sisteminiz siparişleri Routehive'a durak olarak gönderir ve teslimat durumunu webhook ya da sorguyla geri alır. Pro ve Fleet paketlerinde kullanılabilir.
Kimlik doğrulama
API anahtarını sahip veya yönetici uygulamanın API ve webhook'lar sayfasında oluşturur. Anahtar yalnızca bir kez gösterilir. Her isteğin başlığında Bearer belirteci olarak gönderin. Salt okunur anahtarla durak eklenemez.
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"]
}'Uç noktalar
GET /api/v1/routes?date=YYYY-MM-DD- Bir günün rotaları (varsayılan bugün, şirketin saat diliminde).
GET /api/v1/routes/{id}- Durakları sırayla bir rota.
POST /api/v1/stops- Yeni bir durak, örneğin bir online sipariş.
GET /api/v1/stops/{id}- Bir durağın durumu: teslim edildi, başarısız, tahsil edilen tutar, fotoğraf ve imza.
Durak ekleme
Rota verilmezse durak günün Gelen rotasına gider, oradan sevk görevlisi atar. Aynı sipariş numarasını (reference) aynı gün için tekrar gönderirseniz yeni durak oluşmaz: mevcut olanı geri alırsınız. Yeniden göndermek güvenlidir.
Alanlar
address- Adres (zorunlu). Koordinat verilirse adres araması atlanır.
name- Alıcının veya şirketin adı.
phone, email- Bildirimler için telefon ve e-posta.
reference- Sipariş numaranız: durağı webhook'ta bununla tanırsınız ve tekrarları önler.
cod_amount, payment_required- Kapıda ödeme, para biriminin en küçük biriminde (forint: tam forint, euro: sent).
date- Gelen rotasının günü (YYYY-AA-GG). Varsayılan bugün.
route_id- Gelen yerine belirli bir rota, hâlâ eklenebiliyorsa.
packages- Paket barkodları: sürücü teslimattan önce okutur.
require_photo, require_signature- Teslimatta zorunlu fotoğraf veya imza.
Webhook'lar
Webhook adresini aynı sayfada belirlersiniz (yalnızca https) ve olayları seçersiniz. Routehive her olay için POST ile bir JSON gönderir; içerik, durak durumu yanıtıyla aynıdır.
stop.delivered- Bir durak teslim edildi (tahsil edilen tutar, fotoğraf ve imza bilgisiyle).
stop.failed- Bir teslimat başarısız oldu (sürücünün notuyla).
route.dispatched- Bir rota sürücüye gönderildi.
route.completed- Bir rota tamamlandı.
{
"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
}
}İmzayı doğrulama
Her istekte X-Routehive-Signature başlığı bulunur: t=zaman damgası,v1=imza. İmza, zaman damgası, bir nokta ve ham gövdenin webhook sırrıyla HMAC-SHA256 değeridir. Eşleşmezse isteği reddedin.
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"));
}Herhangi bir 2xx yanıtı alındıyı onaylar. Hatalarda giderek seyrekleşen aralıklarla yeniden deneriz (1 dakika, 5 dakika, 30 dakika, 2 saat, 12 saat, 24 saat). Art arda 50 hatadan sonra webhook kapatılır ve sahibe e-posta gider.
Hatalar ve sınırlar
Hatalar şöyle görünür: {"error": {"code": …, "message": …}}. Kod İngilizcedir, mesaj şirketinizin dilindedir. Her anahtar dakikada 120 istek yapabilir; üstünde 429 alırsınız.
Yarın sabahın rotalarını böyle planlayın
Kaydolun, sürücülerinizi ekleyin, adreslerinizi yükleyin. 2 rotada toplam 15 durak için ücretsiz, kredi kartı gerekmez.