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. Suivez, listez et annulez les commandes par API, ou recevez les statuts par webhook.

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.trackingNumber (ou parcel.id) sert pour track / cancelParcel
  const { events } = await maystro.track(parcel.trackingNumber);
} 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',
]);
$tracked = $maystro->track($parcel->trackingNumber); // ou $parcel->id

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

Méthodes supportées

Méthode	Support	Notes
`createParcel`	oui	Statut renvoyé : `pending`.
`track`	oui	Commande + historique des statuts. Id de commande ou numéro de suivi.
`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`	oui	20 commandes par page ; filtres statut, orderId, mot-clé et date appliqués côté SDK.
`cancelParcel`	oui	Annule la commande (statut 50). Id de commande ou numéro de suivi.
`healthCheck`	oui	Vérifie le token (appel réel).
`getLabels` (extra)	oui	Bordereaux en PDF, une page par commande. Sur `MaystroProvider`.

Imprimer les bordereaux (PDF)

TypeScript

import { MaystroProvider } from '@dz-delivery/core';
import { writeFileSync } from 'node:fs';

const maystro = new MaystroProvider({ apiToken: process.env.MAYSTRO_API_TOKEN! });
const { data, labelCount } = await maystro.getLabels(['172316976800001']); // numéros de suivi ou parcel.id
writeFileSync('bordereaux.pdf', data); // une page par commande trouvée

PHP

use DzDelivery\Models\ClientOptions;
use DzDelivery\Providers\MaystroProvider;

$maystro = new MaystroProvider(ClientOptions::fromArray(['apiToken' => getenv('MAYSTRO_API_TOKEN')]));
$labels  = $maystro->getLabels(['172316976800001']); // numéros de suivi ou $parcel->id
return response($labels->data, 200, ['Content-Type' => 'application/pdf']); // Laravel

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

track et cancelParcel acceptent l’id de commande (parcel.id) ou le numéro de suivi (le display_id Maystro, une requête de plus).
listParcels : Maystro renvoie 20 commandes par page, sans filtre ; le SDK filtre chaque page (statut, orderId, mot-clé, updatedSince).
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 ?

Avec track() : le SDK lit la commande et son historique (history_order) et renvoie des statuts unifiés. Pour être notifié sans interroger l’API, utilisez les webhooks : 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…).