REFERENCE

Suivre un colis

Interrogez publiquement le statut et les dates clés avec le code de suivi.

GET/getParcelDetails/{tracking_number}Public

cURL

curl 'https://clients.quicklivraison.ma/api/getParcelDetails/PARCEL_EXEMPLE' -H 'Accept: application/json'

Données retournées

La réponse peut contenir tracking_number, situation, status, status_second, les dates de création, ramassage, expédition, livraison et dernière modification, ainsi que store_name.

Valeurs nullesUne date reste null tant que l’étape correspondante n’a pas eu lieu.

Format brut ou français

Par défaut, l’API retourne les codes techniques. Pour recevoir leurs libellés français dans getParcelDetailsApi, getParcelDetails/{code} et les webhooks, ouvrez Profil → API → Paramètres API, puis activez Statuts en français. Le réglage du compte principal s’applique aussi aux clés de sous-utilisateurs.

Contrat de donnéesUne fois votre intégration en production, gardez ce réglage stable. Un consommateur qui attend DELIVERED ne doit pas recevoir soudainement Livré.

1. Liste complète et signification des statuts

status représente l’étape principale du colis. status_second apporte une précision opérationnelle ou le résultat d’une tentative ; il peut être null. Il faut donc conserver et interpréter les deux champs.

Code API	Libellé français	Signification exacte
`NEW_PARCEL`	Nouveau Colis	Colis créé dans le système, pas encore remis au ramasseur.
`WAITING_PICKUP`	Attente De Ramassage	Demande de ramassage enregistrée ; colis en attente de collecte.
`PICKED_UP`	Ramassé	Colis collecté chez l’expéditeur.
`PICKED_UP_RAMASSEUR`	Ramassé	Colis pris en charge par le ramasseur.
`SENT`	Expédié	Colis expédié vers l’agence ou la zone de destination.
`EN_VOYAGE`	En Voyage	Colis en transit entre deux agences ou zones.
`RECEIVED`	Reçu	Colis reçu et enregistré dans une agence Quick Livraison.
`IN_PROGRESS`	En cours	Colis en cours de traitement opérationnel.
`DISTRIBUTION`	Livraison en cours	Colis confié au livreur pour une tentative de livraison.
`DELIVERED`	Livré	Colis remis avec succès au destinataire.
`POSTPONED`	Reporté	Livraison reportée à une autre date.
`PROGRAMMER`	Programmé	Livraison planifiée pour une date convenue.
`LATER`	Plus tard	Destinataire à rappeler ou livraison à traiter ultérieurement.
`NOANSWER`	Pas de réponse + SMS	Le destinataire n’a pas répondu lors de la tentative ; un SMS peut être envoyé.
`DEUX`	Deuxième Appel Pas Réponse	Deuxième tentative d’appel sans réponse.
`TROIS`	Troisième Appel Pas Réponse	Troisième tentative d’appel sans réponse.
`QUATRE`	Quatrième Appel Pas De Réponse	Quatrième tentative d’appel sans réponse.
`UNREACHABLE`	Injoignable	Le destinataire ne peut pas être joint.
`INJOI`	Injoignable (suivi)	Cas d’injoignabilité enregistré pendant le suivi.
`ERR`	Numéro Erroné	Numéro de téléphone incorrect ou inexploitable.
`OUT_OF_AREA`	Hors-zone	Adresse située hors de la zone de livraison prise en charge.
`REFUSE`	Refusé	Le destinataire a explicitement refusé le colis.
`CANCELED`	Annulé	Livraison ou colis annulé.
`ANN`	Annulé (équipe Quick livraison)	Annulation effectuée par l’équipe Quick Livraison.
`CANCELED_BY_VENDEUR`	Annulé par Vendeur	Annulation demandée ou effectuée par l’expéditeur/vendeur.
`CLIENT_INTERESE`	Client intéressé	Le destinataire reste intéressé ; une nouvelle action ou tentative est attendue.
`WAIT_RELANCE`	Attente de relancer	Dossier en attente d’une nouvelle prise de contact.
`RELENCE_NEW_CLIENT`	Relancé nouveau client	Nouvelle relance du destinataire enregistrée.
`RETURNED`	Retourné	Colis engagé dans le circuit de retour après échec, refus ou annulation.
`RETURNED_CLIENT`	Demande de retour	Retour à l’expéditeur demandé ou colis affecté à une demande de retour.
`DOUBLE`	Double	Colis ou demande identifié comme doublon.

Codes futurs ou exceptionnelsL’API peut conserver tel quel un code non encore présent dans cette table. Ne rejetez pas tout le payload si vous rencontrez une nouvelle valeur ; journalisez-la et continuez à identifier le colis par son tracking_number.

2. Statuts liés au retour à l’expéditeur

Code	Rôle dans le retour
`RETURNED`	Le colis a quitté le parcours normal de livraison et se trouve dans le circuit de retour.
`RETURNED_CLIENT`	Une demande de restitution à l’expéditeur est enregistrée ou le colis y est rattaché.
`REFUSE`	Motif fréquent de déclenchement d’un retour : refus explicite du destinataire.
`CANCELED`, `ANN`, `CANCELED_BY_VENDEUR`	Une annulation peut conduire au retour si le colis avait déjà été collecté ou expédié.

Le retour physique peut comporter plusieurs étapes internes. Ne considérez pas un simple REFUSE ou CANCELED comme la preuve que le colis a déjà été remis à l’expéditeur : attendez un statut de retour et, le cas échéant, les documents de retour associés.

3. Refusé, non livré ou en attente

Catégorie	Statuts à surveiller
Refus explicite	`REFUSE`
Annulé	`CANCELED`, `ANN`, `CANCELED_BY_VENDEUR`
Non livré / tentative échouée	`NOANSWER`, `DEUX`, `TROIS`, `QUATRE`, `UNREACHABLE`, `INJOI`, `ERR`, `OUT_OF_AREA`
En attente avant collecte	`NEW_PARCEL`, `WAITING_PICKUP`
En attente d’une nouvelle tentative	`POSTPONED`, `PROGRAMMER`, `LATER`, `WAIT_RELANCE`, `CLIENT_INTERESE`
En cours d’acheminement	`PICKED_UP`, `SENT`, `EN_VOYAGE`, `RECEIVED`, `IN_PROGRESS`, `DISTRIBUTION`
Retour	`RETURNED`, `RETURNED_CLIENT`

« Non livré » n’est pas toujours définitifLes statuts de tentative, report, programmation ou relance peuvent être suivis d’une nouvelle mise en distribution puis d’une livraison réussie.

4. Ordre normal de progression

Le parcours standard est :

Livraison réussie

NEW_PARCEL → WAITING_PICKUP → PICKED_UP → SENT / EN_VOYAGE → RECEIVED → IN_PROGRESS → DISTRIBUTION → DELIVERED

Selon l’organisation de la tournée, certaines étapes intermédiaires peuvent être omises ou répétées. Une tentative non aboutie crée généralement une branche temporaire avant une nouvelle distribution :

Nouvelle tentative

… → DISTRIBUTION → NOANSWER / UNREACHABLE / POSTPONED / PROGRAMMER → IN_PROGRESS → DISTRIBUTION → DELIVERED

Lorsqu’une livraison ne peut pas aboutir et qu’un retour est décidé, le parcours attendu devient :

Retour expéditeur

… → DISTRIBUTION → REFUSE / CANCELED / échec définitif → RETURNED → RETURNED_CLIENT

Bonne pratique d’intégrationTraitez les statuts comme un historique d’événements, pas comme une suite strictement linéaire. Utilisez l’horodatage, status et status_second, acceptez les répétitions et ne remplacez jamais un événement récent par un webhook plus ancien.

5. Historique détaillé du colis

L’endpoint public conserve exactement sa réponse actuelle. Pour demander en plus la chronologie autorisée dans l’espace client, ajoutez include_history=1 et authentifiez la requête avec la clé API du propriétaire du colis.

GET/getParcelDetails/{tracking_number}?include_history=1Clé API du propriétaire

cURL

curl 'https://clients.quicklivraison.ma/api/getParcelDetails/PARCEL_EXEMPLE?include_history=1' \
 -H 'X-API-Key: VOTRE_CLE_API' -H 'Accept: application/json'

Compatibilité préservéeSans include_history=1, aucun champ n’est ajouté. Avec le paramètre, une clé absente ou invalide retourne 401 ; une clé qui ne possède pas le colis retourne 404.

Même logique que l’historique client

Événements du plus récent au plus ancien, comme dans le modal.
FEES_EDIT et les commentaires techniques de scan/mise en agence sont masqués.
Les doublons de même statut, utilisateur et commentaire dans la même heure sont supprimés.
Le statut secondaire devient le statut affiché lorsqu’il existe.
Les libellés spéciaux sont conservés : prêt pour préparation, reçu par agence, facturé et notifications WhatsApp.
Le nom, rôle, zone et contact du livreur suivent les conditions de l’espace client.
Les tentatives DISTRIBUTION sont numérotées.

Champs de chaque événement

Champ	Description
`status_code`	Statut effectif : secondaire lorsqu’il existe, sinon principal.
`status`	Valeur selon le réglage API français du compte.
`status_label_fr`	Libellé français appliqué par le modal client.
`primary_status_code` / `secondary_status_code`	Codes enregistrés dans l’historique.
`situation_code` / `situation`	Situation brute et valeur éventuellement traduite.
`date` / `timestamp`	Date lisible et horodatage Unix.
`comment` / `rating`	Commentaire client-visible et évaluation éventuelle.
`actor` / `secondary_actor`	Intervenant principal et second intervenant autorisés dans le modal.
`delivery_attempt`	Numéro de tentative pour un événement de distribution.