Vue d’ensemble
L’API Partenaire Relay est une API REST qui vous permet d’intégrer la création de colis, le suivi, l’affectation de livreurs et l’estimation des prix directement dans vos propres systèmes ou applications mobiles.
https://relay-partners.didavie.com/api/v1JSON. Content-Type: application/jsonJeton Bearer dans l’en-tête AuthorizationToutes les réponses suivent la même enveloppe :
{ "success": true, "data": { ... } } // 2xx
{ "success": false, "error": "...", "code": "..." } // 4xx / 5xxAuthentification
Chaque requête doit inclure votre clé API. Deux méthodes sont supportées. utilisez celle qui convient à votre environnement.
curl https://relay-partners.didavie.com/api/v1/me \ -H "Authorization: Bearer relay_pk_live_your64hexkeyhere"
curl https://relay-partners.didavie.com/api/v1/me \ -H "X-API-Key: relay_pk_live_your64hexkeyhere"
Le préfixe de la clé détermine l'environnement ciblé. aucun en-tête ni paramètre supplémentaire requis.
Clé Live (relay_pk_live_…)Pointe vers la base de données de production. À utiliser pour les livraisons réelles.
Clé Test (relay_pk_test_…)Pointe vers la base sandbox. Idéal pour les tests d'intégration sans affecter les données réelles.
Permissions (Scopes)
Chaque clé API se voit attribuer un ensemble de permissions à sa création. Les permissions contrôlent les endpoints accessibles. Vérifiez les permissions d’une clé via GET /api/v1/me.
| Permission | Accès accordé |
|---|---|
aucune | GET /api/v1/me. toutes les clés valides |
packages:read | Lister et lire vos colis |
packages:write | Créer, affecter et annuler des colis ; lister les livreurs |
tracking:read | Suivre vos colis par code de suivi |
zones:read | Lire vos zones de livraison configurées |
pricing:read | Consulter les tarifs crédits et estimer les frais de livraison |
Gestion des erreurs
Toutes les erreurs suivent la même enveloppe JSON. Vérifiez toujours success en premier, puis utilisez code pour le traitement programmatique.
{
"success": false,
"error": "Package not found or not accessible with this API key.",
"code": "NOT_FOUND"
}| HTTP | Code | Quand |
|---|---|---|
| 401 | UNAUTHORIZED | Clé API manquante, malformée, expirée ou révoquée |
| 403 | FORBIDDEN | Agence non vérifiée ou clé sans la permission requise |
| 400 | VALIDATION_ERROR | Champs manquants ou invalides |
| 400 | BAD_REQUEST | Requête valide mais l’action ne peut être effectuée (ex. crédits insuffisants) |
| 404 | NOT_FOUND | La ressource n’existe pas ou n’appartient pas à votre agence |
| 409 | INVALID_STATUS | L’action ne peut être effectuée sur une ressource dans son statut actuel |
| 409 | IDEMPOTENCY_CONFLICT | external_order_id et Idempotency-Key pointent vers des colis existants différents |
| 500 | INTERNAL_ERROR | Erreur serveur inattendue. réessayez ou contactez le support |
Système de crédits
Les opérations plateforme (affectation d’un livreur, publication sur la plateforme ouverte) consomment des crédits de votre solde.
- ✓1 crédit = 1 affectation de livreur. Déduit lors de l’appel à POST /packages/:tracking/assign ou quand la plateforme affecte automatiquement un livreur.
- ✓Facturation idempotente. Réaffecter le même colis à un autre livreur ne déduit pas un second crédit. Le champ
already_chargeddans la réponse d’affectation indique si vous avez été facturé. - ✓Vérifiez votre solde à tout moment via
GET /api/v1/me›credits_balance. - ✓Achetez des crédits dans le tableau de bord Partenaire sous Facturation.
- ℹLes colis avec assignment_mode own_fleet sont gratuits à créer. Vous ne payez que lors de l’affectation d’un livreur.
Webhooks sortants
Configurez un webhook dans l'onglet Webhooks pour recevoir des événements en temps réel à chaque changement de statut d'un colis. Relay envoie un payload JSON signé à votre endpoint.
Gérez votre endpoint webhook et votre secret de signature dans l'onglet Webhooks de la page Développeur.
Événements disponibles
Choisissez les événements à recevoir lors de la configuration. Chaque événement se déclenche une seule fois par transition de statut.
| Event | Description |
|---|---|
package.created | Un colis a été créé. |
package.assigned | Un livreur a été assigné au colis. |
package.picked_up | Le livreur a collecté le colis. |
package.delivered | Le colis a été livré. |
package.cancelled | Le colis a été annulé. |
package.issue_reported | Un problème a été signalé sur le colis. |
Structure du payload
Chaque événement utilise la même enveloppe JSON. L'objet data contient les champs du colis pertinents pour l'événement.
{
"event": "package.delivered",
"timestamp": "2026-03-14T12:30:00Z",
"data": {
"tracking_code": "RB042917",
"status": "delivered",
"agency_id": "...",
"delivered_at": "2026-03-14T12:30:00Z"
}
}Vérification de la signature
Chaque requête webhook contient un en-tête X-Relay-Signature. Vérifiez-le toujours avant de traiter le payload.
Format de l'en-tête
X-Relay-Signature: t=1741433712,v1=a3f2b1c8d9...
Étapes de vérification
- Découpez l'en-tête sur , pour extraire t (horodatage unix) et v1 (signature hex).
- Construisez le message signé : t + "." + le corps brut de la requête (octets non parsés).
- Calculez HMAC-SHA256(votre_secret, message) et encodez en hex.
- Comparez votre résultat à v1 en utilisant une comparaison en temps constant.
- Rejetez optionnellement si |now − t| > 300 s pour protéger contre les attaques par rejeu.
Exemple Node.js / Express
import { createHmac, timingSafeEqual } from 'crypto';
app.post('/webhooks/relay', express.raw({ type: 'application/json' }), (req, res) => {
const header = req.headers['x-relay-signature'] ?? '';
const parts = Object.fromEntries(
header.split(',').map((p) => p.split('=') as [string, string])
);
const { t, v1 } = parts;
// Replay guard
if (Math.abs(Date.now() / 1000 - Number(t)) > 300)
return res.status(400).end();
// Verify signature
const message = `${t}.${req.body}`;
const expected = createHmac('sha256', process.env.RELAY_WEBHOOK_SECRET!)
.update(message)
.digest('hex');
if (!timingSafeEqual(Buffer.from(expected), Buffer.from(v1 ?? '')))
return res.status(401).end();
const payload = JSON.parse(req.body.toString());
// handle payload.event ...
res.status(200).end();
});Politique de réessai
Si votre endpoint retourne un statut non-2xx ou ne répond pas en 10 secondes, Relay réessaie jusqu'à 5 fois avec un back-off exponentiel (5 s, 25 s, 2 min, 10 min, 30 min). Les échecs sont comptabilisés dans les stats webhook de votre tableau de bord.
Endpoints
Cliquez sur un endpoint pour développer sa référence complète.