İçeriğe atla

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.

Makine tarafından okunabilir açıklama (OpenAPI)

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.

API ve webhook'lar

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.