PeekSuivi de colis universelSuivre ton colis
Guides

Suivi de colis open source : le code et le moteur de Peek

8 min de lecture

Peek est un outil de suivi de colis gratuit et open source : son app web, son API et ses apps iPhone et Android sont sur GitHub sous licence Apache 2.0, et c'est un moteur open source distinct, Universal Parcel Scraper, qui interroge ses transporteurs. Peek n'a pas d'API publique avec des clés : pour suivre des colis depuis ton propre code, utilise le scraper, sous forme de commande, de bibliothèque Node ou de serveur HTTP, sans compte ni clé d'API. Tu peux aussi héberger ton propre Peek, ou le lancer sur ton ordinateur avec des colis fictifs.

Pour essayer le scraper depuis ton terminal :

  1. Installe-leIl te faut un Node.js récent (le README indique la version minimale). Lance npm install -g universal-parcel-scraper, ou tape npx universal-parcel-scraper partout où parcel-scraper apparaît ci-dessous.
  2. Identifie le transporteurparcel-scraper detect 1Z999AA10123456784 indique à quel transporteur appartient un numéro, hors ligne.
  3. Récupère l'historiqueparcel-scraper track suivi de ton numéro interroge le transporteur et affiche l'historique du colis en JSON. Si le numéro correspond à plusieurs transporteurs, ajoute par exemple --carrier dhl. Certains transporteurs demandent aussi --postcode, --phone-digits ou --tracking-url.

Peek est-il open source, et sous quelle licence ?

Oui. Le code de Peek est public sur github.com/plhery/peek-delivery-tracker, sous licence Apache 2.0 : l'app web et l'API (Next.js, React, TypeScript), l'app native SwiftUI pour iPhone, iPad et Mac, et l'app Android. Universal Parcel Scraper, que Peek installe depuis npm, est lui aussi sous Apache 2.0 ; seule son image de navigateur TRAWL, facultative, est sous AGPL-3.0.

Peek est un projet non commercial, sans publicité ; le suivi de colis universel le compare aux autres trackers.

Les bugs et les idées vont dans les issues GitHub de Peek, qui sont publiques : n'y mets ni vrais numéros de suivi, ni codes postaux, ni codes de connexion. Les problèmes de sécurité passent par le signalement privé de vulnérabilité de GitHub. CONTRIBUTING.md liste les vérifications à lancer avant une pull request.

Peek a-t-il une API que je peux utiliser ?

Pas d'API publique : Peek ne délivre aucune clé d'API. Son API est celle de l'app, celle qu'appellent le site et les apps iPhone et Android, avec la session de l'utilisateur connecté. Elle est décrite dans un fichier OpenAPI, conservé dans le dépôt sous contracts/openapi.json ; peektracker.com/api lui-même répond 404.

Le catalogue des transporteurs, GET /api/carriers, ne demande pas de connexion. Suivre un colis sans compte non plus, mais une nouvelle recherche doit d'abord passer une vérification du navigateur ou de l'app. Les jetons personnels pour les scripts sont désactivés, sauf si le serveur les active, et les « Réglages » n'ont aucun écran pour en créer un.

Depuis l'extérieur, la seule porte d'entrée est la connexion d'un assistant. Claude, ChatGPT, Gemini ou un autre assistant se connecte à ton compte en OAuth standard et utilise le serveur MCP de Peek, https://peektracker.com/mcp, dans les limites de ce que tu as autorisé. Le même jeton peut lire tes colis en JSON sur GET /api/parcels, et l'intégration Home Assistant de Peek se connecte de la même façon. Voir le guide des assistants, la page de Peek pour les assistants et le guide Home Assistant.

Comment suivre des colis depuis mon propre code sans clé d'API ?

Avec Universal Parcel Scraper, le moteur qui interroge les transporteurs pour Peek. Il trouve le transporteur, lit directement le site de ce transporteur, ne se rabat sur des trackers universels que lorsqu'il le faut, et renvoie le même JSON pour chaque transporteur, chaque scan étant classé dans une étape de livraison commune.

Son README compte plus de 3 500 transporteurs, grâce à plus de 800 adaptateurs dédiés et à des services de repli universels. Dans son benchmark de 100 transporteurs choisis pour les acheteurs en Europe, les adaptateurs renvoient un historique pour 91 d'entre eux, 95 avec tous les services de repli, contre 73 pour le meilleur agrégateur seul.

En plus de la ligne de commande, il fonctionne de trois façons :

OùComment
NodeImporte createTracker depuis universal-parcel-scraper/node ; tracker.track({ number }) renvoie le transporteur, qui a répondu, les scans, l'étape actuelle et ce qu'affiche le transporteur, comme la livraison prévue
Un navigateurDétection du transporteur seulement, avec parseTrackingInput : aucun import Node, aucune requête
HTTPparcel-scraper serve --port 8080, ou l'image Docker ghcr.io/plhery/universal-parcel-scraper, taguée uniquement avec les numéros de version publiés ; puis un POST sur /v1/track. Le serveur met les réponses en cache en mémoire et limite le débit des appelants ; il n'a pas de base de données et n'interroge jamais de lui-même

Avant de bâtir dessus :

  • Il répond à une recherche à la fois. Garder les colis et les vérifier à nouveau, c'est à toi de le faire : c'est la part qu'ajoute Peek.
  • Certains sites de transporteurs ne répondent qu'à un navigateur. Pour ceux-là, il lui faut un Chromium qu'il pilote via des paquets facultatifs, ou son service de navigateur TRAWL. L'image Docker embarque Chromium.
  • Les services de repli sont à activer. Seul UPU est actif par défaut ; ParcelsApp, Ship24, 17TRACK, Postal Ninja et Track718 attendent que tu les actives, et chacun de ceux que tu actives reçoit le numéro de suivi.
  • Une recherche envoie le numéro au transporteur, avec le code postal, le lien ou les chiffres du numéro de téléphone quand il les demande. Aucune télémétrie.

Puis-je héberger mon propre Peek ?

Oui. Un Peek auto-hébergé, c'est un seul conteneur qui tourne en continu, avec l'app web, l'API et le worker qui interroge sans cesse les transporteurs, à côté de Supabase pour la connexion et Postgres, derrière HTTPS. Il te faut :

  • une stack Supabase (Auth, PostgREST et Postgres) avec une sauvegarde et une restauration testées ;
  • un serveur SMTP, si la connexion par e-mail ou l'e-mail de livraison est activé ;
  • un hébergeur capable de construire l'image à partir du Dockerfile et de garder le conteneur en marche. L'hébergement serverless ne convient pas : le worker doit rester en vie.

Le push web, les notifications iPhone (une équipe Apple et une clé APNs) et les notifications Android (Firebase) sont facultatifs. Les assistants aussi : sans ASSISTANT_ACCOUNTS, /mcp et /oauth n'existent pas. Cette variable liste les comptes qui peuvent se connecter, ou * pour tout le monde, et demande CANONICAL_ORIGIN. Quand elle est définie, PERSONAL_TOKENS=on active les jetons personnels pour tes scripts, créés via l'API. docs/DEPLOYMENT.md donne les étapes, de la base de données et de la connexion jusqu'aux mises à jour, aux sauvegardes et au changement d'hébergeur.

Lance-le d'abord sur ton ordinateur

Pas besoin de compte, de base de données ni de fichier .env :

  1. Récupère le codeClone https://github.com/plhery/peek-delivery-tracker.git. Il te faut nvm et la version de Node.js indiquée dans le README.
  2. InstalleDans son dossier, lance nvm use, puis npm ci.
  3. DémarreLance npm run dev et ouvre localhost:3000 : Peek répond dans le navigateur avec des colis fictifs. localhost:3000/demo liste des exemples de livraisons qui avancent quand tu actualises la page.

Pour de vrais comptes et un vrai suivi, copie .env.example en .env.local, renseigne un projet Supabase et mets NEXT_PUBLIC_USE_API=true ; docs/AUTHENTICATION.md donne les étapes de la connexion. L'app iPhone se compile dans Xcode pour un simulateur d'iPhone et démarre avec des colis d'exemple, sans compte, serveur ni équipe Apple.

Un transporteur manque : comment le signaler ou l'ajouter ?

Signale-le au scraper, là où vivent les transporteurs. Sur sa page de nouvelle issue, vers laquelle le README de Peek renvoie sous le nom « Tell the scraper », choisis « Add a carrier » (son nom, son pays d'origine et son site de suivi public) ou « A carrier stopped working ». Les nouveaux transporteurs et les corrections arrivent dans le scraper sous forme de pull requests : chaque transporteur a son propre dossier avec des fixtures synthétiques et des tests hors ligne, et npm run carrier:new en crée le squelette.

Peek adopte de lui-même les nouvelles versions du scraper : un transporteur n'a donc besoin d'aucune pull request vers Peek. Et l'app iPhone actualise sa liste de transporteurs depuis le serveur, donc pas besoin non plus d'une nouvelle version de l'app.

Pas de compte GitHub ? Dis-le à Peek depuis la page du colis, sur le web, sur iPhone ou sur Android, avec ou sans compte Peek :

  1. Réponds à la questionQuand Peek ne trouve aucun transporteur pour un colis, sa page demande « Le site du transporteur l’affiche ? ». Choisis « Oui ».
  2. Nomme le transporteurDans « Qui le transporte ? », indique-le sous « Transporteur ou boutique », ou colle son lien de suivi sous « Sa page de suivi, si tu as le lien ». L'un des deux suffit.
  3. EnvoieChoisis « Envoyer ». Ta réponse part avec le numéro du colis, et rien sur toi.

Une personne lit ces réponses, mais personne ne peut te répondre : pour avoir une réponse, écris à hello@peektracker.com, l'adresse indiquée sur la page d'aide de Peek. La façon dont Peek identifie un transporteur à partir de ce que tu colles est expliquée dans Suivre un colis sans connaître le transporteur.

Sources