Parcel tracking (17TRACK, DHL) Smart-Home-Integration, kostenlos und Open Source
Verfolge Sendungen aller Zusteller weltweit mit 17TRACK und der offiziellen DHL-API.
Veröffentlicht von guim31
- Geräte
- Version 1.0.1
- Erfordert Gladys >=5.1.0
- ★ 0
Verfolge in Gladys deine Sendungen aller Zusteller, im Inland wie im Ausland: DHL, Deutsche Post, Hermes, GLS, DPD, UPS, FedEx, die Post in Österreich und der Schweiz, die Postdienste der ganzen Welt, Sendungen aus China (Cainiao, YunExpress…) und mehr als 3.000 weitere, so wie die Apps zur Sendungsverfolgung.
Ohne 17TRACK- oder DHL-Konto entwickelt: Rückmeldungen sind im Gladys-Forum willkommen. Die Antworten beider APIs wurden anhand ihrer Dokumentation simuliert.
Für Sendungen von La Poste, Colissimo und Chronopost nimm lieber die Integration
La Poste (guim31/gladys-laposte), die die offizielle API von La Poste
liest.
Diese Integration steht in keiner Verbindung zu den Zustellern oder zu 17TRACK.
Was die Integration macht
- Du fügst eine Sendung mit ihrer Sendungsnummer hinzu, auf Wunsch mit einem Namen („Laufschuhe“), in der Konfiguration oder in einer Szene. Der Zusteller wird an der Nummer erkannt.
- Zwei Quellen, jede mit ihrem kostenlosen Schlüssel aktiviert:
- DHL über die offizielle API, für Sendungsnummern von DHL und Deutscher Post;
- 17TRACK für alles andere: Es erkennt den Zusteller und fasst die Schritte aller Zusteller unterwegs (zum Beispiel China Post, dann DHL) in einem einzigen Verlauf zusammen.
- Jede Sendung wird ein Gerät in Gladys: Status, letzter Schritt, Ort, Datum, Zusteller und voraussichtliches Zustelldatum.
- Der Status ist für alle Zusteller gleich: angekündigt, unterwegs, in Zustellung, abholbereit, Problem, zugestellt. Der Originaltext des Zustellers (oft Englisch oder Deutsch) bleibt als Detail sichtbar.
- Das Widget „Meine Sendungen“ listet deine Sendungen, die wartenden zuerst.
- Drei Szenen-Auslöser (in Zustellung, zugestellt, eine Sendung braucht dich) und drei Szenen-Aktionen (Sendung verfolgen, Sendung nicht mehr verfolgen, meine Sendungen lesen).
- Eine zugestellte Sendung wird nach 7 Tagen (einstellbar) von selbst archiviert.
Voraussetzungen
- Gladys 5.1.0 oder neuer, mit Internetzugang.
- Mindestens einer der beiden Schlüssel, beide kostenlos:
- 17TRACK (alle Zusteller): Lege ein Konto auf api.17track.net an und kopiere den Schlüssel unter Settings → Security → Access key. Wenn du die IP-Whitelist einschaltest, trage dort die öffentliche Adresse deines Routers ein, sonst lehnt 17TRACK den Schlüssel ab.
- DHL (Sendungen von DHL und Deutscher Post): Lege ein Konto auf developer.dhl.com an, erstelle eine App mit der API Shipment Tracking - Unified und kopiere ihren API Key (nicht das Secret).
- Beide zusammen bringen das beste Ergebnis: DHL liest seine eigenen Sendungen, 17TRACK den Rest.
Konfiguration
Installiere die Integration über Integrationen → Von GitHub installieren mit der Adresse
https://github.com/guim31/gladys-colis und öffne dann ihre Konfiguration.
| Einstellung | Standard | Zweck |
|---|---|---|
| 17TRACK-API-Schlüssel | (leer) | Dein 17TRACK-Schlüssel. Er erscheint nie in den Logs. |
| DHL-API-Schlüssel | (leer) | Der API Key deiner DHL-App. Er erscheint nie in den Logs. |
| Zugestellte Sendungen behalten | 7 Tage | Eine zugestellte Sendung wird nach dieser Zeit archiviert (1 bis 30 Tage). |
| Sprache | Französisch | Sprache der Status, der Funktionsnamen neuer Geräte und der Meldungen. |
Die Aktionen der Konfiguration:
- Sendung verfolgen: die Sendungsnummer (Leerzeichen, Punkte und Bindestriche sind erlaubt) und ein optionaler Name. Die Sendung wird sofort gelesen. Dieselbe Nummer mit einem anderen Namen benennt die Sendung um. Lege danach ihr Gerät im Tab Entdecken an.
- Sendung nicht mehr verfolgen: nach Name oder Nummer. Das Gerät bleibt in Gladys: Lösche es auf der Geräteseite.
- Sendungen jetzt lesen: liest sofort jede Sendung unterwegs, prüft die Schlüssel und zeigt das verbleibende 17TRACK-Kontingent und die heute verbrauchten DHL-Abfragen.
Kontingente und Lesetakt
Die Integration liest jede Sendung in einem Takt, der ihrem Status folgt, und bleibt immer in den kostenlosen Angeboten:
| Status | Abfrage |
|---|---|
| In Zustellung | alle 15 Minuten |
| Unterwegs, Problem | jede Stunde |
| Abholbereit, noch unbekannt | alle 2 Stunden |
| Angekündigt | alle 3 Stunden |
| Zugestellt | nie mehr |
- DHL: Das kostenlose Angebot erlaubt 250 Abfragen pro Tag und eine alle 5 Sekunden. Die Integration hört bei 240 pro Tag auf, wartet 5 Sekunden zwischen zwei Abfragen und wird langsamer, wenn sich viele DHL-Sendungen den Tag teilen (20 DHL-Sendungen unterwegs: etwas mehr als 2 Stunden zwischen zwei Abfragen). Sind die 240 Abfragen verbraucht, warten die DHL-Sendungen bis zum nächsten Tag (Mitternacht UTC).
- 17TRACK: Nur die Registrierung einer neuen Nummer verbraucht Kontingent, einmal pro Sendung; die Abfragen danach sind kostenlos und gebündelt (40 Nummern pro Anfrage, höchstens 3 Anfragen pro Sekunde). Das kostenlose Angebot enthält eine begrenzte Zahl an Registrierungen: laut Hilfecenter von 17TRACK einmalig 200 Nummern für Konten, die seit Januar 2026 eröffnet wurden (100 pro Monat bei älteren Konten). Sieh in deinem 17TRACK-Dashboard nach: Die Aktion „Sendungen jetzt lesen“ zeigt den Rest. Eine archivierte und erneut verfolgte Sendung verbraucht nichts.
- 17TRACK fragt die Zusteller selbst ab: Direkt nach der Registrierung können die ersten Schritte ein paar Minuten dauern.
Die Geräte
Ein Gerät pro Sendung, nach der Sendung benannt („Laufschuhe (00340434292135100186)“), im Tab Entdecken anzulegen. Seine Funktionen, alle nur lesend:
| Funktion | Inhalt |
|---|---|
| Status | Nicht gelesen, Noch unbekannt, Angekündigt, Unterwegs, In Zustellung, Abholbereit, Problem, Zugestellt |
| Letzter Schritt | Der Text des Zustellers, wie er ihn sendet |
| Ort | Der Ort des letzten Schritts |
| Datum des Schritts | Datum und Uhrzeit des letzten Schritts |
| Zusteller | DHL Paket, Deutsche Post, UPS, Cainiao… |
| Voraussichtliche Zustellung | Das vom Zusteller angekündigte Datum, falls vorhanden |
Ein Strich (—) steht für eine Angabe, die der Zusteller nicht macht. Die Funktionsnamen nehmen die Sprache an, die beim Anlegen des Geräts eingestellt ist.
Wird die Sendung archiviert, verlässt sie den Tab „Entdecken“, aber ihr Gerät bleibt mit seinen letzten Werten in Gladys: Lösche es, wenn du es nicht mehr brauchst (Gladys lässt eine Integration kein Gerät löschen).
Das Widget
Füge das Widget Meine Sendungen zu deinem Dashboard hinzu. Es listet bis zu 8 Sendungen: zuerst die in Zustellung, abholbereiten oder mit Problem, dann die anderen. Jede Zeile zeigt den Namen, den letzten Schritt mit Datum und ein farbiges Status-Abzeichen. Ein Tippen öffnet die Details: Zusteller, Nummer, voraussichtliches Zustelldatum, Verlauf der Schritte und ein Link zur Verfolgungsseite. Eine Zeile unten meldet einen abgelehnten Schlüssel, ein erreichtes Kontingent oder einen Dienst, der nicht antwortet.
Szenen-Auslöser
| Auslöser | Wann |
|---|---|
| Eine Sendung ist in Zustellung | Der Fahrer hat die Sendung für die heutige Tour. |
| Eine Sendung ist zugestellt | Der Zusteller meldet die Sendung als zugestellt (nicht bei einer beim Hinzufügen schon zugestellten). |
| Eine Sendung braucht dich | Die Sendung wartet an einer Abholstelle oder Packstation oder hat ein Problem (Zustellung gescheitert, Zoll, Verspätung, Rücksendung). |
Jeder Auslöser lässt sich auf eine Sendung beschränken (leer: alle Sendungen). „Eine Sendung braucht dich“ lässt sich auch auf einen Grund beschränken: „Abholbereit“ oder „Problem“. Die an die Szenen-Aktionen übergebenen Angaben: Name der Sendung, Nummer, Zusteller, Status, letzter Schritt, Ort und Verfolgungsseite (und der Grund).
Ein Auslöser feuert einmal pro Statuswechsel: Ein Neustart von Gladys oder der Integration löst ihn nicht erneut aus.
Szenen-Aktionen
- Sendung verfolgen: fügt eine Sendung hinzu. Das Nummernfeld nimmt auch einen ganzen Text, etwa den Betreff einer Versandbestätigung: Die erste Sendungsnummer darin wird verwendet. Ergebnisse: Nummer, Name, Status, Zusteller und „Neue Sendung“ (1 oder 0).
- Sendung nicht mehr verfolgen: nach Name oder Nummer. Ergebnis „Entfernt“: 1, oder 0, wenn keine Sendung passt.
- Meine Sendungen lesen: ein Satz wie „Du hast 2 Sendungen unterwegs: Schuhe, heute in Zustellung; Buch, abholbereit.“ und die Zahl der Sendungen unterwegs, in Zustellung, abholbereit und mit Problem.
Szenenbeispiele
- Der Fahrer kommt: Auslöser „Eine Sendung ist in Zustellung“, Aktion „Nachricht senden“: „Die Sendung {Name der Sendung} kommt heute ({Zusteller})“. Füge eine Anwesenheitsbedingung hinzu, um nur zu warnen, wenn niemand zu Hause ist.
- An die Packstation denken: Auslöser „Eine Sendung braucht dich“, Grund „Abholbereit“, dann eine Nachricht „{Name der Sendung} wartet auf dich: {letzter Schritt}“.
- Überblick am Morgen: Zeitauslöser um 8 Uhr, Aktion „Meine Sendungen lesen“, dann „Nur fortfahren, wenn“ Sendungen unterwegs > 0, und eine Sprachansage des Satzes.
- Automatische Verfolgung aus deinen Mails: Gib mit einer Mail-Integration den Betreff der Versandmail an die Aktion „Sendung verfolgen“ weiter.
Fehlerbehebung
- „17TRACK lehnt den API-Schlüssel ab“: Prüfe den Schlüssel (Settings → Security). Ist bei 17TRACK die IP-Whitelist eingeschaltet, trage die öffentliche Adresse deines Routers ein oder schalte sie aus.
- „DHL lehnt den API-Schlüssel ab“: Kopiere den API Key der App (nicht das „API Secret“) und prüfe, ob die App die API „Shipment Tracking - Unified“ hat.
- Eine Sendung bleibt „Noch unbekannt“: Der Absender hat das Etikett erstellt, die Sendung aber noch nicht übergeben, oder 17TRACK erkennt den Zusteller nicht. Die Integration versucht es weiter und archiviert die Nummer nach 30 Tagen.
- „17TRACK-Kontingent erreicht“: Auf deinem Konto ist keine kostenlose Registrierung mehr übrig; schon verfolgte Sendungen werden weiter gelesen. Entferne Sendungen, die du nicht mehr brauchst.
- „DHL-Abfragen für heute aufgebraucht“: Die 240 Abfragen des Tages sind verbraucht; die DHL-Sendungen gehen um Mitternacht UTC weiter.
- Das Gerät zeigt nichts: Lege es im Tab „Entdecken“ an und warte auf die nächste Abfrage oder nutze „Sendungen jetzt lesen“.
- Für mehr Details stelle die Log-Stufe auf
debug(VariableLOG_LEVEL=debug): Jede Abfrage wird dort beschrieben, nie mit den Schlüsseln.
Grenzen
- Ohne 17TRACK- oder DHL-Konto entwickelt: Die Antworten wurden anhand der Dokumentation beider APIs simuliert. Die ersten echten Rückmeldungen stehen aus.
- Die DHL-Status „In Zustellung“ und „Abholbereit“ werden aus dem Text des Schritts (Englisch oder Deutsch) abgeleitet: Eine neue Formulierung kann als „Unterwegs“ eingeordnet bleiben.
- Die Texte der Schritte bleiben in der Sprache des Zustellers.
- Die Auslöser folgen dem Lesetakt: „In Zustellung“ kann bis zu einer Stunde nach der Übernahme durch den Fahrer kommen.
- Höchstens 40 verfolgte Sendungen.
- UPS, FedEx und USPS haben auch offizielle APIs, verlangen aber ein Geschäftskonto und eine OAuth-Anmeldung: Diese Zusteller laufen über 17TRACK.
- Zusteller, die zur Verfolgung eine Postleitzahl oder Telefonnummer verlangen, werden nicht unterstützt.
Konfigurationseinstellungen
Diese Einstellungen fragt Parcel tracking (17TRACK, DHL) in seinem Konfigurationsbildschirm in Gladys ab.
| Einstellung | Typ | Pflichtfeld | Beschreibung |
|---|---|---|---|
| Deine kostenlosen API-Schlüssel | section | Nein | Gib einen 17TRACK-Schlüssel (alle Zusteller, an der Nummer erkannt), einen DHL-Schlüssel oder beide ein. Nutze dann „Sendung verfolgen“ und lege die Geräte im Tab „Entdecken“ an. Für La Poste nimm die La-Poste-Integration. Keine Verbindung zu den Zustellern oder 17TRACK. |
| 17TRACK-API-Schlüssel | secret | Nein | Settings → Security → Access key deines kostenlosen Kontos auf api.17track.net. Alle Zusteller. |
| DHL-API-Schlüssel | secret | Nein | Der API Key einer App „Shipment Tracking - Unified“ auf developer.dhl.com (kostenlos, 250 Abfragen pro Tag). |
| Zugestellte Sendungen behalten | select | Nein | Eine zugestellte Sendung wird nach dieser Zeit archiviert und verlässt die Liste, das Widget und den Tab „Entdecken“. |
| Sprache | select | Nein | Sprache der Status, der Funktionsnamen neuer Geräte und der Meldungen. Die Texte der Zusteller bleiben, wie sie sie senden. |
So installierst du Parcel tracking (17TRACK, DHL) in Gladys
- Öffne in Gladys Integrationen: Parcel tracking (17TRACK, DHL) erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
- Klicke auf Installieren. Gladys lädt das Docker-Image (
ghcr.io/guim31/gladys-colis:1.0.1) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration). - Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
- Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/guim31/gladys-colis.
Parcel tracking (17TRACK, DHL) benötigt Gladys >=5.1.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.
Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.
Über externe Integrationen
Parcel tracking (17TRACK, DHL) ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von guim31 veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.
- Alle Integrationen durchsuchen, native und aus der Community
- Deine eigene externe Integration bauen und veröffentlichen
- Quellcode auf GitHub — Quelle dieser Dokumentation