Mediadesk Messagerie Devenir client Connexion

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

GET/meVérifier la clé : marchand associé
GET/servicesServices disponibles (EXPRESS_24, STANDARD_48, ECO)
GET/citiesVilles desservies (id, noms fr/ar, nombre de quartiers et de codes postaux)
GET/cities/{id}/districts?postal_code=20250Quartiers desservis d'une ville (id, noms, code postal ; filtres postal_code, q)
GET/coverage?q=20250Livrez-vous ici ? Code postal, quartier ou ville → covered (true / false) et détails
GET/relay-points?city=RabatPoints relais actifs (code, adresse, GPS, horaires, jours de garde)
GET/quote?city=Rabat&weight_g=1500&cod_amount=300Tarif avant création
POST/shipmentsCréer un colis → numéro de suivi + lien étiquette
GET/shipments?status=DELIVERED&from=2026-11-01Lister vos colis (filtres : status, reference, phone, from, to, per_page ≤ 100)
GET/shipments/{tracking}Détail, historique public, tentatives de livraison et preuves (photo / signature, liens signés 7 jours)
GET/shipments/{tracking}/labelLien d'étiquette 10×15 signé (valable 7 jours)
POST/shipments/{tracking}/cancelAnnuler (uniquement avant ramassage)
POST/shipments/{tracking}/returnDemander le retour d'un colis non livré (pas pendant une tournée). Frais de retour appliqués à la remise.
GET/pickupsVos ramassages (filtre ?status=requested|assigned|done|failed|cancelled)
POST/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).
DELETE/pickups/{code}Annuler un ramassage tant que le livreur n'est pas passé
DELETE/shipments/{tracking}/returnRetirer la demande de retour, tant que l'agence ne l'a pas lancé
GET/payoutsSolde à recevoir + historique des virements
GET/payouts/{code}Détail d'un virement, colis par colis
GET/webhooksLister vos webhooks
POST/webhooksAjouter un webhook (renvoie le secret une seule fois)
DELETE/webhooks/{id}Désactiver un webhook

Cré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
  }'
ChampObligatoireDétail
recipient_nameouiNom du destinataire
recipient_phoneouiMobile marocain : 06…, 07…, 05…, +212…
city / city_idouiVille desservie
address_textouiAdresse (≤ 500 caractères)
weight_gouiPoids en grammes (1 – 70 000)
cod_amountouiMontant à encaisser en DH, 0 si déjà payé
merchant_referenceconseilléVotre n° de commande — unique : renvoyer la même référence renvoie 409 avec le colis existant (pas de doublon)
service / service_type_idnonPar défaut STANDARD_48
district / district_id, landmark, lat, lngnonAide le livreur à trouver l'adresse
relay_pointnonCode 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_opennoncan_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"] } } }
401unauthenticatedClé absente, invalide ou révoquée
404not_foundColis / ressource introuvable (ou appartenant à un autre marchand)
409duplicate_reference · not_cancellable · return_not_possible · return_not_cancellableRéférence déjà utilisée · colis déjà pris en charge · retour impossible à ce stade
422validation_failed · unknown_cityDonnées invalides
429rate_limitedPlus 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

CodeFrançaisالعربية
CREATEDCrééتم الإنشاء
PICKUP_SCHEDULEDRamassage planifiéالاستلام مبرمج
PICKED_UPRamasséتم الاستلام
AT_ORIGIN_HUBAu centre de départفي مركز الانطلاق
IN_TRANSITEn transitفي الطريق
AT_DEST_HUBÀ l'agence de livraisonفي وكالة التوزيع
OUT_FOR_DELIVERYEn cours de livraisonفي طور التوصيل
DELIVEREDLivréتم التسليم
DELIVERY_FAILEDÉchec de livraisonتعذر التسليم
POSTPONEDReportéمؤجل
AT_RELAY_POINTAu point relaisفي نقطة الاستلام
REFUSEDRefuséمرفوض
RETURN_IN_TRANSITRetour en coursفي طريق الإرجاع
RETURNED_TO_MERCHANTRetourné au marchandأعيد إلى التاجر
LOSTPerduمفقود
DAMAGEDEndommagéمتضرر
CANCELLEDAnnuléملغى

Frais additionnels : un refus ajoute les frais de refus, un retour au marchand ajoute les frais de retour (voir amounts.extra_fees).