API Maystro Delivery en Node.js et PHP

Créez vos commandes Maystro, calculez les frais et listez les points relais avec le SDK dz-delivery. Le suivi passe par les webhooks Maystro, avec un mapping des statuts fourni.

Installer

TypeScript · npm

npm install @dz-delivery/core

PHP · Composer

composer require dz-delivery/sdk

Node.js ≥ 18 (aucune dépendance) ou PHP ≥ 8.2 (Guzzle 7). Le même code fonctionne ensuite pour les autres transporteurs : seule la configuration du client change.

Identifiants Maystro

Option	Header envoyé	Où la trouver
`apiToken`	`Authorization: Token <apiToken>`	Token de votre boutique dans l’application Maystro

Documentation officielle : Maystro Delivery API.

Maystro en TypeScript / Node.js

TypeScript

import { createClient, isShippingError } from '@dz-delivery/core';

const maystro = createClient('maystro', {
  apiToken: process.env.MAYSTRO_API_TOKEN!,
});

const wilayas = await maystro.getWilayas();
const communes = await maystro.getCommunes(16);

// Stop desks / points relais : communeId obligatoire chez Maystro
const desks = await maystro.getStopDesks({ wilayaId: 16, communeId: communes[0].id });

const quote = await maystro.getFees({ toWilayaId: 16, toCommuneId: communes[0].id });

try {
  const parcel = await maystro.createParcel({
    recipientName: 'Mohamed Amine',
    phone: '0550123456',
    address: 'Cité 221 lots, n°98',
    wilayaId: 16,
    communeName: 'Bab Ezzouar',
    productName: 'T-shirt',
    price: 2500,
    orderId: 'ORDER-1001',
  });
  // parcel.id = id de commande Maystro, à garder pour les webhooks
} catch (err) {
  if (isShippingError(err)) console.error(err.code, err.message);
}

Maystro en PHP / Laravel

PHP

use DzDelivery\ClientFactory;

$maystro = ClientFactory::create('maystro', [
    'apiToken' => getenv('MAYSTRO_API_TOKEN'),
]);

$communes = $maystro->getCommunes(16);
$desks    = $maystro->getStopDesks(['wilayaId' => 16, 'communeId' => $communes[0]->id]);
$quote    = $maystro->getFees(['toWilayaId' => 16, 'toCommuneId' => $communes[0]->id]);

$parcel = $maystro->createParcel([
    'recipientName' => 'Mohamed Amine',
    'phone'         => '0550123456',
    'address'       => 'Cité 221 lots, n°98',
    'wilayaId'      => 16,
    'communeName'   => 'Bab Ezzouar',
    'productName'   => 'T-shirt',
    'price'         => 2500,
    'orderId'       => 'ORDER-1001',
]);
// $parcel->id : à stocker pour relier les webhooks

Guide PHP complet (Laravel, erreurs, tests) : guide-php.md.

Méthodes supportées

Méthode	Support	Notes
`createParcel`	oui	Statut renvoyé : `pending`.
`track`	NOT_SUPPORTED	Pas d’API de suivi chez Maystro : utilisez les webhooks.
`getFees`	oui	Tarifs domicile et stop desk.
`getWilayas / getCommunes`	oui	Le `id` de wilaya est le code officiel.
`getStopDesks`	oui	Stop desks et points relais, `communeId` obligatoire.
`listParcels`	NOT_SUPPORTED	Pas d’API de liste chez Maystro.
`cancelParcel`	NOT_SUPPORTED	Pas d’endpoint d’annulation documenté.
`healthCheck`	oui	Vérifie le token (appel réel).

Suivre les colis Maystro avec les webhooks

Configurez une URL HTTPS dans l’application Maystro (Paramètres → Webhooks). L’événement OrderStatusChanged contient payload.id (l’id de commande) et payload.status (code numérique) que le SDK convertit en statut unifié.

TypeScript

import { mapMaystroStatus } from '@dz-delivery/core';

// event = JSON décodé depuis message.data (base64)
if (event.event === 'OrderStatusChanged') {
  const status = mapMaystroStatus(event.payload.status); // 41 → 'delivered'
  // mettre à jour la commande dont carrier_id = event.payload.id
}

PHP

use DzDelivery\Support\StatusMapper;

if (($event['event'] ?? null) === 'OrderStatusChanged') {
    $status = StatusMapper::maystro($event['payload']['status'] ?? null); // 41 → 'delivered'
}

Exemple complet (décodage base64, sécurisation de l’URL) : guide PHP §7.

À savoir sur l’API Maystro

Pas de track ni cancelParcel : ces méthodes lèvent NOT_SUPPORTED sans appel HTTP. Le suivi se fait par webhooks.
getStopDesks exige un communeId ; l’id renvoyé s’utilise comme stopDeskId à la création.
Les frais viennent de l’API tarifaire Maystro, avec repli automatique sur l’ancienne API d’options de livraison.
Les webhooks Maystro ne sont pas signés : protégez l’URL (par exemple avec un secret long dans la query string).

Mapping natif détaillé (endpoints, champs, statuts) : PROVIDERS.md.

FAQ Maystro

Comment suivre un colis Maystro par API ?

Maystro n’expose pas d’endpoint de suivi : les changements de statut arrivent par webhook. Le SDK fournit mapMaystroStatus / StatusMapper::maystro() pour les convertir en statuts unifiés.

Où trouver le token API Maystro ?

C’est le token de votre boutique dans l’application Maystro ; passez-le tel quel en apiToken.

Comment calculer les frais Maystro ?

getFees({ toWilayaId, toCommuneId }) renvoie le tarif domicile (deliveryFee) et stop desk (stopDeskFee) en DZD.

Autres transporteurs

Même interface, mêmes statuts normalisés (pending, in_transit, delivered…).