Aller au contenu

Pour les développeurs

API et webhooks

Votre boutique en ligne ou un autre système envoie les commandes à Routehive comme arrêts et récupère le statut de livraison par webhook ou par requête. Disponible dans les offres Pro et Flotte.

Description lisible par machine (OpenAPI)

Authentification

Le propriétaire ou un administrateur crée la clé API sur la page API et webhooks de l'application. La clé n'est affichée qu'une fois. Envoyez-la dans l'en-tête de chaque requête comme jeton Bearer. Une clé en lecture seule ne peut pas ajouter d'arrêt.

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

Points d'accès

GET /api/v1/routes?date=YYYY-MM-DD
Les tournées d'un jour (par défaut aujourd'hui, dans le fuseau de l'entreprise).
GET /api/v1/routes/{id}
Une tournée avec ses arrêts, dans l'ordre.
POST /api/v1/stops
Un nouvel arrêt, par exemple une commande en ligne.
GET /api/v1/stops/{id}
Statut d'un arrêt : livré, échec, montant encaissé, photo et signature.

Ajouter un arrêt

Sans tournée, l'arrêt va dans la tournée Entrantes du jour, d'où le répartiteur l'attribue. Si vous renvoyez le même numéro de commande (reference) pour le même jour, aucun nouvel arrêt n'est créé : vous recevez l'existant. Le renvoi est donc sans risque.

Champs

address
L'adresse (obligatoire). Avec des coordonnées, le géocodage est sauté.
name
Nom du destinataire ou de l'entreprise.
phone, email
Téléphone et e-mail pour les notifications.
reference
Votre numéro de commande : il identifie l'arrêt dans les webhooks et évite les doublons.
cod_amount, payment_required
Contre-remboursement dans la plus petite unité de la devise (forint : forints entiers, euro : centimes).
date
Jour de la tournée Entrantes (AAAA-MM-JJ). Par défaut aujourd'hui.
route_id
Une tournée précise au lieu de la tournée Entrantes, si elle peut encore être complétée.
packages
Codes-barres des colis : le chauffeur les scanne avant la livraison.
require_photo, require_signature
Photo ou signature obligatoire pour la livraison.

Webhooks

Indiquez l'URL du webhook sur la même page (https uniquement) et choisissez les événements. Routehive envoie un JSON en POST pour chaque événement ; le contenu est le même que la réponse du statut d'un arrêt.

stop.delivered
Un arrêt a été livré (avec le montant encaissé et les indicateurs photo et signature).
stop.failed
Une livraison a échoué (avec la note du chauffeur).
route.dispatched
Une tournée a été envoyée au chauffeur.
route.completed
Une tournée est terminée.
{
  "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
  }
}

Vérifier la signature

Chaque requête porte l'en-tête X-Routehive-Signature : t=horodatage,v1=signature. La signature est le HMAC-SHA256 de l'horodatage, d'un point et du corps brut, avec le secret du webhook. Si elle ne correspond pas, rejetez la requête.

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

Toute réponse 2xx confirme la réception. En cas d'erreur, nous réessayons de moins en moins souvent (1 minute, 5 minutes, 30 minutes, 2 heures, 12 heures, 24 heures). Après 50 échecs consécutifs, le webhook est désactivé et le propriétaire reçoit un e-mail.

Erreurs et limites

Les erreurs ont la forme {"error": {"code": …, "message": …}}. Le code est en anglais, le message dans la langue de votre entreprise. Chaque clé peut faire 120 requêtes par minute ; au-delà, vous recevez 429.

API et webhooks

Planifiez ainsi vos tournées dès demain matin

Inscrivez-vous, ajoutez vos chauffeurs, chargez vos adresses. Gratuit jusqu'à 15 arrêts au total, en 2 tournées, sans carte bancaire.