API & webhooks Keynex

Connectez votre ERP, votre WMS ou le TMS de vos clients à Keynex : créez des missions ou des ordres de transport, suivez les statuts, l'heure d'arrivée estimée et le CO2, récupérez les factures, et recevez chaque événement en temps réel par webhook.

1. Obtenir une clé d'API

Dans votre espace Keynex : 👥 Équipe & sécurité › 🔌 API & webhooks (rôle Direction ou Administrateur). Chaque clé appartient à votre agence, porte des droits limités (lecture seule, écriture…), n'est affichée qu'une seule fois et peut être révoquée à tout moment. Keynex n'en conserve qu'une empreinte.

curl https://keynex.fr/api/v1/missions?statut=en-cours \
  -H "Authorization: Bearer kx_1a2b3c4d_…"

2. Principes

• JSON en entrée et en sortie, dates AAAA-MM-JJ, heures HH:MM (heure de Paris), montants en euros HT.
• Listes paginées : ?page=1&par_page=50 (200 au plus), réponse { "donnees": [...], "pagination": {...} }.
• Erreurs : { "erreur": { "code": "validation", "message": "…" } } avec les codes HTTP 401, 403, 404, 409, 422, 429.
• Limite : 120 requêtes par minute et par clé (en-têtes X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After).
• Créations idempotentes : envoyez un en-tête Idempotency-Key unique ; rejouer la requête pendant 24 h renvoie la même réponse sans doublon.
• Les règles de Keynex s'appliquent aussi à l'API : prix de grille, CO2 et marge calculés par le serveur, missions livrées ou facturées figées.

3. Points d'accès

Spécification complète au format OpenAPI 3 : /api/v1/openapi.json (importable dans Postman, Insomnia, Swagger…).

4. Webhooks

Déclarez une adresse https:// et choisissez vos événements. Keynex envoie un POST JSON { "id", "type", "cree_le", "donnees" } avec les en-têtes X-Keynex-Evenement, X-Keynex-Livraison et X-Keynex-Signature: t=<horodatage>,v1=<signature>.

• Répondez par un code 2xx en moins de 10 secondes. Sinon Keynex réessaie après 1 min, 5 min, 30 min, 2 h, 6 h puis 24 h ; chaque envoi reste visible et peut être rejoué depuis votre espace.
• Après 5 envois définitivement en échec d'affilée, le webhook est désactivé (réactivable en un clic).
• Un même événement peut arriver deux fois : dédoublonnez sur id.

Vérifier la signature (Node.js)

const crypto = require("crypto");
function signatureValide(entete, corpsBrut, secret) {
  const [, t, v1] = /t=(\d+),v1=([a-f0-9]+)/.exec(entete) || [];
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // anti-rejeu : 5 min
  const attendu = crypto.createHmac("sha256", secret).update(`${t}.${corpsBrut}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(attendu), Buffer.from(v1));
}

Vérifier la signature (PHP)

preg_match('/t=(\d+),v1=([a-f0-9]+)/', $_SERVER['HTTP_X_KEYNEX_SIGNATURE'], $m);
$corps = file_get_contents('php://input');
$ok = abs(time() - (int)$m[1]) <= 300
   && hash_equals(hash_hmac('sha256', $m[1] . '.' . $corps, $secret), $m[2]);

Besoin d'aide ?

Écrivez-nous à contact@keynex.fr.