API marchands v1
Créez vos colis depuis votre boutique (WooCommerce, Shopify, YouCan, ERP…), imprimez les étiquettes, suivez les livraisons et recevez les changements de statut en temps réel.
AuthentificationEndpointsCréer un colisErreursWebhooksStatuts
Authentification
Générez une clé dans Intégrations (compte marchand) puis envoyez-la à chaque requête :
Authorization: Bearer mdk_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
URL de base : https://messagerie.mediadesk.ma/api/v1 · Réponses en JSON UTF-8 · Montants en dirhams (MAD) · Dates ISO 8601 (heure du Maroc) · Limite : 120 requêtes / minute / clé.
Endpoints
/meVérifier la clé : marchand associé/servicesServices disponibles (EXPRESS_24, STANDARD_48, ECO)/citiesVilles desservies (id, noms fr/ar, nombre de quartiers et de codes postaux)/cities/{id}/districts?postal_code=20250Quartiers desservis d'une ville (id, noms, code postal ; filtres postal_code, q)/coverage?q=20250Livrez-vous ici ? Code postal, quartier ou ville → covered (true / false) et détails/relay-points?city=RabatPoints relais actifs (code, adresse, GPS, horaires, jours de garde)/quote?city=Rabat&weight_g=1500&cod_amount=300Tarif avant création/shipmentsCréer un colis → numéro de suivi + lien étiquette/shipments?status=DELIVERED&from=2026-11-01Lister vos colis (filtres : status, reference, phone, from, to, per_page ≤ 100)/shipments/{tracking}Détail, historique public, tentatives de livraison et preuves (photo / signature, liens signés 7 jours)/shipments/{tracking}/labelLien d'étiquette 10×15 signé (valable 7 jours)/shipments/{tracking}/cancelAnnuler (uniquement avant ramassage)/shipments/{tracking}/returnDemander le retour d'un colis non livré (pas pendant une tournée). Frais de retour appliqués à la remise./pickupsVos ramassages (filtre ?status=requested|assigned|done|failed|cancelled)/pickupsDemander un ramassage : {date: "AAAA-MM-JJ", window: morning|afternoon|evening, tracking_numbers?: [], expected_count?, address?, note?}. Même jour possible avant 14h, pas le dimanche. Un créneau déjà ouvert est complété (200, merged: true)./pickups/{code}Annuler un ramassage tant que le livreur n'est pas passé/shipments/{tracking}/returnRetirer la demande de retour, tant que l'agence ne l'a pas lancé/payoutsSolde à recevoir + historique des virements/payouts/{code}Détail d'un virement, colis par colis/webhooksLister vos webhooks/webhooksAjouter un webhook (renvoie le secret une seule fois)/webhooks/{id}Désactiver un webhookCréer un colis
Vous pouvez envoyer city / district par leur nom (accents et majuscules ignorés, français ou arabe) et service par son code, ou bien les *_id de /cities. Avec postal_code (5 chiffres), la ville peut être omise : elle est déduite du code, qui sert aussi à choisir le bon quartier quand un nom existe sous plusieurs codes.
@__raw_block_0__{{ $base }}/shipments \
-H "Authorization: Bearer $MEDIADESK_KEY" \
-H "Content-Type: application/json" \
-d '{
"merchant_reference": "WC-10293",
"service": "STANDARD_48",
"recipient_name": "Salma Bennani",
"recipient_phone": "0661234567",
"city": "Casablanca",
"district": "Maarif",
"address_text": "Rue Abou Bakr El Kadiri, Imm 12, Apt 4",
"landmark": "En face de la pharmacie",
"lat": 33.5862, "lng": -7.6326,
"weight_g": 800,
"cod_amount": 299,
"description": "Chaussures T38",
"can_open": true
}'
| Champ | Obligatoire | Détail |
|---|---|---|
recipient_name | oui | Nom du destinataire |
recipient_phone | oui | Mobile marocain : 06…, 07…, 05…, +212… |
city / city_id | oui | Ville desservie |
address_text | oui | Adresse (≤ 500 caractères) |
weight_g | oui | Poids en grammes (1 – 70 000) |
cod_amount | oui | Montant à encaisser en DH, 0 si déjà payé |
merchant_reference | conseillé | Votre n° de commande — unique : renvoyer la même référence renvoie 409 avec le colis existant (pas de doublon) |
service / service_type_id | non | Par défaut STANDARD_48 |
district / district_id, landmark, lat, lng | non | Aide le livreur à trouver l'adresse |
relay_point | non | Code d'un point relais de la ville (ex. CAS-R01) : le client retire le colis avec un code reçu par SMS, et y paie le CRBT |
recipient_phone_alt, pieces, description, declared_value, is_fragile, can_open | non | can_open = le client peut ouvrir avant de payer |
Réponse 201 : l'objet colis, avec tracking_number (ex. MD000000014MA), amounts (frais figés à la création), label_url et tracking_url.
Erreurs
{ "error": { "code": "validation_failed", "message": "…", "fields": { "recipient_phone": ["Numéro marocain invalide"] } } }
401 | unauthenticated | Clé absente, invalide ou révoquée |
404 | not_found | Colis / ressource introuvable (ou appartenant à un autre marchand) |
409 | duplicate_reference · not_cancellable · return_not_possible · return_not_cancellable | Référence déjà utilisée · colis déjà pris en charge · retour impossible à ce stade |
422 | validation_failed · unknown_city | Données invalides |
429 | rate_limited | Plus de 120 requêtes/minute |
Webhooks
À chaque changement de statut d'un de vos colis, nous envoyons un POST JSON à votre URL (https). Répondez 2xx en moins de 5 secondes ; sinon nous réessayons après 1, 5, 15, 60, 180, 360, 720 et 1440 minutes. Traitez les messages de façon idempotente avec id.
POST /webhooks/mediadesk
Content-Type: application/json
X-Mediadesk-Event: shipment.status_changed
X-Mediadesk-Delivery: whd_42
X-Mediadesk-Signature: t=1794240000,v1=5f2c…
{
"id": "whd_42",
"event": "shipment.status_changed",
"created_at": "2026-11-09T16:06:14+01:00",
"data": {
"tracking_number": "MD000000014MA",
"merchant_reference": "WC-10293",
"status": "DELIVERED",
"status_label": { "fr": "Livré", "ar": "تم التسليم" },
"occurred_at": "2026-11-09T16:06:14+01:00",
"city": "Casablanca",
"reason": null,
"cod_amount": 299.0,
"cod_collected": true,
"attempts": 2,
"total_fee": 24.49,
"delivery_attempt": {
"attempt": 2,
"outcome": "delivered",
"attempted_at": "2026-11-09T16:06:14+01:00",
"reason": null,
"call_result": "answered",
"location": { "lat": 33.5862, "lng": -7.6326 },
"proof": {
"photo_url": "https://…/preuves-signees/42/photo?expires=…&signature=…",
"signature_url": "https://…/preuves-signees/42/signature?expires=…&signature=…",
"expires_at": "2026-11-16T16:06:14+01:00"
}
}
}
}
delivery_attempt est présent pour les statuts DELIVERED, DELIVERY_FAILED, POSTPONED et REFUSED. Chaque livraison a au moins une preuve (photo du colis remis ou signature du client). Les liens expirent après 7 jours : téléchargez les images si vous devez les conserver, ou rappelez GET /shipments/{tracking} pour obtenir de nouveaux liens.
Vérifier la signature
Calculez HMAC-SHA256(secret, t + "." + corps brut) et comparez à v1. Refusez si t a plus de 5 minutes.
// PHP
$raw = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_MEDIADESK_SIGNATURE']), $sig);
$expected = hash_hmac('sha256', $sig['t'] . '.' . $raw, getenv('MEDIADESK_WEBHOOK_SECRET'));
if (!hash_equals($expected, $sig['v1']) || abs(time() - (int) $sig['t']) > 300) { http_response_code(400); exit; }
$event = json_decode($raw, true);
// Node.js (Express: app.post(path, express.raw({ type: 'application/json' }), handler))
const [t, v1] = req.get('X-Mediadesk-Signature').split(',').map(p => p.split('=')[1]);
const expected = crypto.createHmac('sha256', process.env.MEDIADESK_WEBHOOK_SECRET).update(`${t}.${req.body}`).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) && Math.abs(Date.now() / 1000 - t) < 300;
Statuts
| Code | Français | العربية |
|---|---|---|
CREATED | Créé | تم الإنشاء |
PICKUP_SCHEDULED | Ramassage planifié | الاستلام مبرمج |
PICKED_UP | Ramassé | تم الاستلام |
AT_ORIGIN_HUB | Au centre de départ | في مركز الانطلاق |
IN_TRANSIT | En transit | في الطريق |
AT_DEST_HUB | À l'agence de livraison | في وكالة التوزيع |
OUT_FOR_DELIVERY | En cours de livraison | في طور التوصيل |
DELIVERED | Livré | تم التسليم |
DELIVERY_FAILED | Échec de livraison | تعذر التسليم |
POSTPONED | Reporté | مؤجل |
AT_RELAY_POINT | Au point relais | في نقطة الاستلام |
REFUSED | Refusé | مرفوض |
RETURN_IN_TRANSIT | Retour en cours | في طريق الإرجاع |
RETURNED_TO_MERCHANT | Retourné au marchand | أعيد إلى التاجر |
LOST | Perdu | مفقود |
DAMAGED | Endommagé | متضرر |
CANCELLED | Annulé | ملغى |
Frais additionnels : un refus ajoute les frais de refus, un retour au marchand ajoute les frais de retour (voir amounts.extra_fees).