Intégration Home Assistant (HACS) qui suit automatiquement tes colis chez les transporteurs courants en Belgique — bpost, PostNL, DHL, UPS, FedEx, DPD, GLS, Amazon — à partir des emails que tu transfères vers une boîte mail dédiée (et/ou ajoutés à la main).
Pour chaque colis tu obtiens :
- le statut normalisé (
in_transit,out_for_delivery,delivered, …) ET le texte brut renvoyé par le transporteur ; - la date de livraison estimée quand elle est disponible ;
- le dernier événement (date, lieu, description) ;
- des capteurs de synthèse : colis attendus aujourd'hui, demain, en cours de livraison, à retirer, en cours.
┌────────────────────┐ imap_content ┌──────────────────────────────┐
│ Gmail dédié │ ───── event ──────▶ │ TrackIt (custom_component) │
│ (tu transfères │ │ │
│ tes mails ici) │ │ 1. parse mail → n° + carrier│
└────────────────────┘ │ 2. route vers le backend │
│ 3. capteurs + ETA │
service trackit.add_parcel ───────────────▶ └───────────────┬──────────────┘
│
┌──────────────────────────────┬──────────┴───────────┐
▼ ▼ ▼
DHL / UPS / FedEx 17TRACK Statut issu
(API directe gratuite) (universel : bpost, de l'email
PostNL, DPD, GLS…) (zéro config)
Stratégie de fiabilité en couches (configurable) :
| Transporteur | Source utilisée (par défaut) |
|---|---|
| DHL, UPS, FedEx | API directe gratuite du transporteur si configurée (sinon 17TRACK) |
| bpost, PostNL, DPD, GLS, Amazon… | 17TRACK (agrégateur universel) |
| (aucun backend configuré pour ce transporteur) | statut lu dans l'email transféré |
Pourquoi ce choix ? bpost, PostNL, DPD et GLS ne proposent aucune API gratuite pour un destinataire (réservé aux comptes expéditeurs business). 17TRACK est le seul moyen gratuit et fiable de les suivre par programme. DHL a une API gratuite excellente, et UPS/FedEx aussi (moyennant un compte) — on les utilise en priorité pour leurs propres colis pour ne pas consommer le quota 17TRACK.
- HACS → menu ⋮ → Custom repositories.
- Ajoute l'URL de ce dépôt, catégorie Integration.
- Cherche TrackIt — Parcel Tracker, installe, redémarre Home Assistant.
Copie le dossier custom_components/trackit/ dans le dossier config/custom_components/
de ton Home Assistant, puis redémarre.
- Crée (ou réutilise) une adresse Gmail dédiée, p.ex.
mes-colis@gmail.com. - Active la validation en 2 étapes sur ce compte.
- Génère un mot de passe d'application : https://myaccount.google.com/apppasswords (16 caractères). C'est lui que HA utilisera (pas ton vrai mot de passe).
- Paramètres → Appareils & services → Ajouter une intégration → IMAP.
- Serveur
imap.gmail.com, port993, utilisateur = ton adresse, mot de passe = le mot de passe d'application. ⚠️ Important : dans les options de l'intégration IMAP, coche l'inclusion du corps du message (« Message data to include in event » → text). Sans ça, l'événement ne contient pas le texte et TrackIt ne pourra lire que le sujet. (Le corps est tronqué à ~2048 octets : mets le n° de tracking dans le sujet ou en début de mail si possible.)- (Optionnel) restreins la recherche IMAP, p.ex. au dossier où tu ranges les mails de colis.
TrackIt écoute l'événement imap_content : tout mail qui arrive dans cette
boîte est analysé. Le plus simple : crée un filtre Gmail qui transfère tes
mails de transporteurs vers cette adresse (utilise « transférer », pas
« rediriger comme nouveau », pour préserver l'expéditeur d'origine).
| Service | Où | Gratuit ? |
|---|---|---|
| 17TRACK (recommandé, universel) | https://api.17track.net → crée un compte → clé 17token |
200 colis offerts (one-shot), puis ~0,024 $/colis. Le re-suivi d'un colis déjà enregistré ne reconsomme rien. |
| DHL (recommandé) | https://developer.dhl.com → crée une App → abonne-la à Shipment Tracking - Unified → copie la clé | Gratuit, 250 appels/jour |
| UPS (optionnel) | https://developer.ups.com → compte UPS + n° de compte → App → Client ID/Secret | Gratuit (compte UPS requis) |
| FedEx (optionnel) | https://developer.fedex.com → projet → Client ID/Secret | Gratuit (compte FedEx requis pour la prod) |
Tu peux démarrer avec uniquement 17TRACK (couvre tout) + DHL. C'est le meilleur rapport couverture/effort.
Paramètres → Appareils & services → Ajouter une intégration → TrackIt, puis colle les clés que tu as. Tu peux tout laisser vide pour commencer (mode « statut depuis l'email » uniquement) et ajouter les clés plus tard via les options.
Capteurs de synthèse (toujours présents) :
| Entité | Description |
|---|---|
sensor.colis_en_cours |
Nombre de colis encore en route |
sensor.colis_attendus_aujourd_hui |
Colis dont la livraison est estimée aujourd'hui |
sensor.colis_attendus_demain |
… estimée demain |
sensor.colis_en_cours_de_livraison |
Colis « out for delivery » |
sensor.colis_a_retirer |
Colis disponibles en point relais |
Chaque capteur expose la liste détaillée des colis concernés dans son attribut parcels.
Un capteur par colis (optionnel, activé par défaut) : état = statut normalisé, avec en attributs le transporteur, l'ETA, le dernier événement, etc.
| Service | Description |
|---|---|
trackit.add_parcel |
Ajoute/maj un colis (tracking_number requis ; carrier, name, recipient optionnels) |
trackit.remove_parcel |
Arrête le suivi d'un colis |
trackit.refresh |
Force une mise à jour immédiate |
trackit.cleanup |
Supprime les colis livrés trop anciens et les colis non livrés trop vieux (selon les options) |
Exemple :
service: trackit.add_parcel
data:
tracking_number: "JJD000390007777777777"
carrier: dhl # optionnel — détecté automatiquement sinon
name: "Casque audio"Si l'expéditeur ne permet pas de déduire le transporteur, tu peux l'indiquer
entre parenthèses dans le sujet du mail transféré, p.ex.
Mon colis (dhl) — TrackIt le prendra en compte.
type: entities
title: 📦 Mes colis
entities:
- entity: sensor.colis_attendus_aujourd_hui
- entity: sensor.colis_attendus_demain
- entity: sensor.colis_en_cours_de_livraison
- entity: sensor.colis_en_coursDeux règles (réglables dans les options) évitent que le tableau se remplisse :
- Colis livrés/retournés → supprimés 7 jours après la fin (
keep_delivered_days). - Colis non livrés trop vieux → supprimés 90 jours après l'ajout
(
stale_active_days, mettre0pour désactiver).
Le service trackit.cleanup applique ces règles à la demande ; elles tournent
aussi à chaque rafraîchissement.
💡 Important sur le quota 17TRACK : supprimer un colis ne rend pas le crédit (les 200 numéros se consomment à l'enregistrement, une fois pour toutes). Le nettoyage sert à garder l'interface propre et à arrêter de poller les colis terminés (TrackIt envoie en plus un
stoptrackpoli à 17TRACK). Le vrai levier d'économie, c'est de ne pas ré-enregistrer — déjà géré automatiquement.
- 17TRACK : depuis le 07/01/2026, les nouveaux comptes reçoivent 200 numéros offerts à vie (plus de recharge mensuelle gratuite). Suffisant longtemps pour un foyer (le re-suivi ne reconsomme pas de quota), puis ~0,024 $/colis. Vérifie les conditions à l'inscription.
- DHL Parcel Benelux (numéros domestiques
JVGL…) : la couverture par l'API gratuite « Unified » n'est pas garantie ; 17TRACK prend le relais. - GLS / bpost domestique : pas toujours auto-détectables par le numéro seul ; on s'appuie alors sur le domaine de l'expéditeur ou l'indice carrier.
- Faux positifs : un email peut contenir un numéro de commande ressemblant à
un tracking. TrackIt privilégie les liens de suivi et les numéros validés
(clé de contrôle) pour limiter ça, mais tu peux toujours retirer un colis
parasite avec
trackit.remove_parcel. - Sécurité : un domaine d'expéditeur peut être usurpé (phishing). Cet outil ne lit que ta boîte ; ne le considère pas comme une preuve d'authenticité.
La logique pure (détection transporteur, parsing email, modèle) est testable sans Home Assistant :
pip install pytest tracking-numbers
pytest tests/MIT — voir LICENSE.