Endpoints · Lecture
Lire et suivre les bordereaux
Toutes ces lectures sont cloisonnées à votre compte. Scope read.
| Endpoint | Description |
|---|---|
GET /shipping | Liste paginée — filtres : status, from, to, groupReference, page (défaut 1), limit (défaut 50) |
GET /shipping/:id | Un bordereau par identifiant |
GET /shipping/reference/:referenceNumber | Un bordereau par numéro de référence |
GET /shipping/tracking/:referenceNumber | Suivi condensé — statut et localisation du colis |
GET /shipping/labels | Tous vos bordereaux, sans pagination — { success, shippings } |
GET /shipping/stats | Statistiques du compte |
GET /shipping/auth/test | Vérifie vos identifiants |
Les trois premières renvoient le document complet — donc plus de champs que la projection de POST /shipping. Ne présumez pas que les deux formes sont identiques : seuls les champs de la projection sont stables. deliveryCode est retiré de toutes ces lectures, sans exception.
GET /shipping/labels n'est pas paginé
Il renvoie l'intégralité de vos bordereaux, triés du plus récent au plus ancien, dans une seule réponse — sans page ni limit. Sur un compte actif depuis des mois, la réponse devient lourde et lente. Pour un usage régulier, préférez GET /shipping et sa pagination ; réservez /labels aux exports ponctuels.
Le champ deliverer n'a pas la même forme partout. C'est la source d'erreur la plus fréquente sur ces lectures :
GET /shipping,/shipping/:id,/shipping/reference/:ref,/shipping/labels→ un objet une fois le livreur assigné et sa fiche résolue :{ _id, firstname, lastname, phoneNo, profilepic, userRating }.- Ces mêmes lectures → la chaîne brute de l'identifiant du livreur (
"6612a9f4c3b25d1e8a77f430") si un livreur est assigné mais que sa fiche n'a pas pu être résolue. - Ces mêmes lectures →
nulltant qu'aucun livreur n'est assigné. GET /shipping/tracking/:ref→ une chaîne :"Prénom Nom"composé, ounull. Jamais un objet.- Dans les webhooks → un objet
{ id, name, phoneNumber }dontnameetphoneNumbervalent toujoursnull.
Trois formes pour un seul champ : testez le type
deliverer est tantôt un objet, tantôt une chaîne, tantôt null — sur le même endpoint. Un code qui fait deliverer.firstname sans garde lira undefined sur la chaîne et lèvera sur le null. Testez typeof deliverer === 'object' && deliverer !== null d'abord.
Les champs sont firstname, lastname et phoneNo — pas name, pas phoneNumber. Le nom complet est à composer vous-même. Cette liste blanche est exhaustive : il n'y a pas d'email, pas de position GPS, pas d'adresse.
Pour joindre un livreur, la source fiable est GET /shipping/:id (champ phoneNo) — pas la charge utile du webhook.
GET /shipping/tracking/:ref renvoie { success, tracking: { referenceNumber, status, statusLabel, createdAt, pickupTime, deliveryTime, estimatedDelivery, from, to, deliverer } } — statusLabel est un libellé français destiné à l'affichage ; branchez sur status. from et to ne sont que des villes.
Les clés non renseignées sont absentes du JSON, pas à null. pickupTime et deliveryTime n'apparaissent pas tant que le colis n'a pas été enlevé / livré. Utilisez un accès tolérant à la clé manquante (?., .get()).
Toutes ces lectures sont cloisonnées à votre compte : un :id ou une référence appartenant à un autre marchand renvoie 404, pas 403 — l'API ne confirme jamais l'existence d'un bordereau qui n'est pas le vôtre.