Connecter votre ERP

Le parcours des données

1. Vos répartiteurs travaillent dans la console (ou l’appli N-Ways Business) : livraisons, livreurs, chauffeurs N-Ways, alertes.
2. Chaque changement est un événement. N-Ways l’envoie à votre adresse HTTPS en quelques secondes, signé avec le secret de votre webhook.
3. Votre ERP met à jour son enregistrement, retrouvé par la référence que vous avez donnée à la livraison ou par l’identifiant N-Ways.
4. Rien n’est perdu. Les appels en échec sont renvoyés pendant environ 22 heures ; vous pouvez en renvoyer un depuis le journal des envois, et récupérer à nouveau tous les événements par date avec l’API d’export.

1. Ajoutez votre adresse

Dans la console : Paramètres → Webhooks → Ajouter un webhook. Donnez une adresse HTTPS joignable depuis internet et choisissez tous les événements ou seulement ceux dont votre ERP a besoin. Le secret de signature (whsec_…) ne s’affiche qu’une fois : rangez-le avec vos autres secrets. Jusqu’à 10 adresses par organisation, chacune avec ses propres en-têtes (une clé d’API pour votre passerelle, par exemple).

Ou avec une clé serveur :

curl -X POST "https://nways.ng/maps/v1/fleet/webhooks" \
  -H "X-NWays-Api-Key: VOTRE_CLE_SERVEUR" -H "Content-Type: application/json" \
  -d '{"url": "https://erp.example.com/nways/events"}'

2. Envoyez un événement de test

Envoyer un test sur le webhook publie un événement ping. Journaux → Envois des webhooks montre chaque tentative, la réponse de votre serveur et le prochain essai. Répondez par un code 2xx en moins de 10 secondes ; faites le travail lent (l’écriture dans l’ERP) après avoir répondu.

3. Vérifiez la signature

Chaque appel porte X-NWays-Signature: t=<secondes unix>,v1=<hex>, où v1 est le HMAC-SHA256 de "<t>.<corps brut>" avec le secret de votre webhook. Vérifiez-la sur le corps brut, avant de le lire, et refusez un horodatage décalé de plus de 5 minutes.

using System.Security.Cryptography;
using System.Text;

static bool Verified(string raw, string header, string secret)
{
    var parts = header.Split(',').Select(p => p.Split('=', 2)).ToDictionary(p => p[0], p => p.Length > 1 ? p[1] : "");
    if (!long.TryParse(parts.GetValueOrDefault("t"), out var t)) return false;
    if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - t) > 300) return false;
    using var mac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var want = Convert.ToHexString(mac.ComputeHash(Encoding.UTF8.GetBytes($"{t}.{raw}"))).ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(want), Encoding.UTF8.GetBytes(parts.GetValueOrDefault("v1", "")));
}

import com.sap.gateway.ip.core.customdev.util.Message
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec

def Message processData(Message message) {
    def raw = message.getBody(String)
    def parts = message.getHeaders()['X-NWays-Signature'].split(',').collectEntries { it.split('=', 2) as List }
    long t = parts.t as long
    if (Math.abs(System.currentTimeMillis() / 1000 - t) > 300) throw new Exception('old signature')
    def mac = Mac.getInstance('HmacSHA256')
    mac.init(new SecretKeySpec(message.getProperty('NWAYS_SECRET').bytes, 'HmacSHA256'))
    def want = mac.doFinal("${t}.${raw}".bytes).encodeHex().toString()
    if (!java.security.MessageDigest.isEqual(want.bytes, (parts.v1 ?: '').bytes)) throw new Exception('bad signature')
    return message
}

import hashlib, hmac, time

def verified(raw: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    if abs(time.time() - int(parts.get("t", 0))) > 300:
        return False
    want = hmac.new(secret.encode(), parts["t"].encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, parts.get("v1", ""))

4. Associez les champs

Où va habituellement chaque champ d’un événement de livraison (data.task). Gardez l’id N-Ways comme référence externe sur votre enregistrement, pour que chaque événement suivant le retrouve ; mettez votre propre numéro de document dans la reference de la livraison à sa création : il revient dans chaque événement.

Statuts : created → assigned → picked_up → arriving → completed, ou failed (avec failureReason) ou cancelled. Un événement peut arriver deux fois ou dans le désordre : gardez les id d’événements déjà traités et fiez-vous au status de la tâche plutôt qu’à l’ordre d’arrivée. Il n’y a aucun champ d’argent, volontairement.

5. Rapprochez

Si votre ERP était arrêté, rien n’est perdu. Renvoyez un envoi depuis Journaux → Envois des webhooks, ou récupérez à nouveau les événements par date (JSON ou CSV, les mêmes contenus que les webhooks) :

curl "https://nways.ng/maps/v1/fleet/events/export?format=json&from=2026-10-01&to=2026-10-16" \
  -H "X-NWays-Api-Key: VOTRE_CLE_SERVEUR"

Livraisons, véhicules et chauffeurs se lisent aussi à tout moment avec l’API Flotte (GET /maps/v1/fleet/tasks, /vehicles, /drivers), pour vérifier chaque nuit que les deux côtés concordent. Utilisez une clé limitée aux adresses IP de vos serveurs et à l’API Flotte.

Quels événements

Tous les événements de la liste des webhooks : livraisons (task.*, delivery.rated), chauffeurs et véhicules (connection.*, driver.availability_changed, vehicle.offline), demandes aux chauffeurs N-Ways (dispatch.*), zones et alertes (zone.*, asset.*). Les contenus portent la version 2026-10-16 ; une version ne fait qu’ajouter des champs.