Erpnext Versand

ERPNext-App: Versandetiketten direkt über die DHL Parcel DE Shipping API v2 (Architektur für DPD & Deutsche Post/Portokasse)

Install Erpnext Versand

bench get-app https://github.com/DrdotHouse2106/ERPNext-Versand

Tags

  • dhl
  • erpnext
  • frappe
  • frappe-app
  • shipping
  • shipping-labels

Add the Frappe Gems badge to your README

Maintain Erpnext Versand? Paste this into your README:

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=DrdotHouse2106%2FERPNext-Versand)](https://frappegems.com/gems/apps/DrdotHouse2106/ERPNext-Versand)

About Erpnext Versand

ERPNext Versand Integration

Spendier mir einen Kaffee

English version

Frappe-/ERPNext-App zur Erzeugung von Versandetiketten direkt über die Carrier-APIs – ohne Drittanbieter-Middleware.

Carrier API Stand
DHL Parcel DE Shipping v2 (REST, OAuth2/Basic) + Retoure (services.dhlRetoure) + Paket DE Abholen v3 (Abholauftrag) ✅ Etikett erstellen + stornieren live verifiziert; Retoure + Abholauftrag implementiert, noch nicht live getestet
DPD DE WebConnect (SOAP: LoginService V2.0 + ShipmentService V4.5, via zeep) Login + Sendung erstellen live verifiziert; Abholtag-Steuerung (shippingDate) implementiert
Deutsche Post Internetmarke – neue REST-API „Post DE Internetmarke" (DHL Developer Portal, kein Partnervertrag mehr) ✅ Marken-Erstellung (Vorschau/Produktiv) live verifiziert; Portokasse-Aufladung + optionale DATEV-Journalbuchungen implementiert, noch nicht live getestet

Geschrieben und getestet für Frappe / ERPNext v16 (v15-Kompatibilität nicht geprüft). Python-Abhängigkeit: zeep (SOAP, für DPD).

> Repo heißt ERPNext_Versand_Integration, die Frappe-App heißt > versand_integration (Python-Modulname). Frappe Cloud / bench lesen den > App-Namen aus pyproject.toml – der Repo-Name muss nicht übereinstimmen.


Status: Testphase (Stand 21.09.2026)

Alle drei Carrier hängen in der aktuellen Testinstanz des Maintainers an Test-/Sandbox-Zugängen (DHL Parcel DE Shipping Sandbox, DPD WebConnect Stage, eine Deutsche-Post-Portokasse der „Entwickler"-Klasse mit fiktivem Guthaben) – es sind nirgends echte Kundendaten oder echtes Geld im Spiel, Live-Tests gegen alle drei APIs sind also gefahrlos möglich. Getestet wurde bisher per API mit freistehenden, danach wieder gelöschten Test-Versandsendungen (kein Kunde/Lieferschein nötig, keine Spuren im System). Das sind die Testzugänge des Maintainers zum Entwickeln/Testen dieser App – jeder andere Nutzer trägt in den jeweiligen Settings seine eigenen, echten Zugangsdaten ein (Sandbox oder Produktiv, siehe „Konfiguration" unten).

✅ Live gegen Sandbox/Testzugänge verifiziert - DHL: „Verbindung testen" (OAuth2), Etikett erstellen (echte Sendungsnummer, gültiges PDF-Label per API heruntergeladen und geprüft) und Stornieren (DELETE /orders, „1 von 1 Sendung erfolgreich storniert.") – alles Ende-zu-Ende erfolgreich - DPD: SOAP-Login (LoginService.getAuth, zeep-Header-Matching funktioniert) und storeOrders liefern eine echte Sendungsnummer + Tracking-Link. Das Label-PDF fehlte in zwei aufeinanderfolgenden Läufen – zwei Ursachen gefunden und gefixt (splitByParcel, dann output ist eine Liste statt eines Einzelobjekts; Commits b38fc55/b8aed2e) - bench migrate-Grundlagen: Custom Fields, Abrechnungsnummern-Tabelle, DocTypes korrekt angelegt - Deutsche Post / Internetmarke: Auth (POST /user) und Marken-Erstellung (Vorschau + Produktiv, POST /app/shoppingcart/pdf) live verifiziert - Sicherheitsreview (Rechteprüfungen, Race-Condition-Schutz bei create_label(), HTML-Escaping von Carrier-Antworten, SSRF-Schutz) umgesetzt und deployed – der dabei zunächst übersehene Absturz bei neuen/ungespeicherten Versandsendungen wurde gefunden und gefixt (Commit 6e0d9c8), Fix vom User am Produktivsystem bestätigt - Manuelle Versandsendung: Empfänger aus dem Kundenstamm (Kunde → Adresse) statt Handeingabe übernehmbar

🔧 Zweite Review-Runde (statisch geprüft, noch nicht durchgeklickt): Limit + Carrier-Prüfung für die Wochenbuchung, Sperre gegen doppelte Sendungen je Lieferschein, Schreibrechtsprüfung für die Settings-Aktionen, Base64-Etiketten raus aus dem API-Protokoll, Storno-Status wird jetzt wirklich gespeichert (db_set), umgebungs-/zugangsdatenabhängiger DHL-Token-Cache mit 401-Retry, WSDL-Cache für DPD, deutlich mehr Unit-Tests und eine CI (Ruff + JSON-Prüfung). Details siehe „Sicherheit" und „Qualitätssicherung".

⚠️ Noch nicht live getestet (Code deployt/validiert, aber noch nicht durchgeklickt) - DPD-Abholtag-Steuerung + „Für die ganze Woche buchen" - DHL-Retoure (services.dhlRetoure, Rücksendeetikett) - DHL Abholauftrag (Paket DE Abholen v3) – „Beliebige Adresse" und „Vereinbarter Abholort" - Deutsche Post: Portokasse-Aufladung, DATEV-Journalbuchungen, Saldo-Abgleich, Anfangsguthaben buchen - Mehrmarken-Auflösung (Versandabsender) mit mehr als einer Marke, automatischer Briefkopf - Sendungsverfolgung: Hintergrund-Job, Statusabgleich, Benachrichtigungen, Arbeitsfläche

Noch gar nicht begonnen: Drucker-pro-Dokumenttyp-Auswahl (z. B. eigener Drucker für Versandetiketten vs. Zollinhaltserklärung) inkl. eines lokalen Druck-Agenten/-Servers – Konzept besprochen, Umsetzung wartet auf die Entscheidung, welches Gerät den Agenten hostet.

Siehe „Testvorgehen" unten für die geplante Reihenfolge.


Was die App macht

Objekt Zweck
DHL / DPD / Deutsche Post Settings (je Single) Zugangsdaten, Fallback-Absender, Voreinstellungen, „Verbindung testen"
Versand Integration Settings (Single) Sendungsverfolgung: Job an/aus, Intervall, Abbruch nach Tagen, Benachrichtigung
Versandabsender Marken-/Absenderprofil: Adresse, Retoure, Briefkopf, DHL-Abrechnungsnummern je Produkt
Versandsendung (submittable) Sendung zu einem Lieferschein: Carrier, Absender, Empfänger, Maße, Services, Mehrcolli, Etikett-PDF, Sendungsnummer, Tracking-Status + Verlauf, API-Protokoll
Versandsendung Paket (Child) Einzelne Colli bei Mehrpaketsendungen (DHL/DPD)
DHL Abholauftrag (+ Child DHL Abholauftrag Sendung) Abholung bei DHL beauftragen/stornieren/Status abfragen – unabhängig von einzelnen Versandsendungen
DHL Abholort Stammdaten „vereinbarter Abholort" (Sync via GET /locations)
Button „Versandetikett erstellen" im Lieferschein Carrier wählen → Versandsendung anlegen, API rufen, PDF anhängen & öffnen
Custom Fields am Lieferschein Versandsendung, Sendungsnummer, Sendungsverfolgung

Ablauf: Lieferschein buchen → „Versandetikett erstellen" → Carrier + Absender wählen → PDF öffnet sich, Sendungsnummer & Tracking-Link stehen am Lieferschein und an der Versandsendung.

Manuelle Versandsendung ohne Lieferschein: Kunde ist nur wählbar, wenn kein Lieferschein verknüpft ist (sonst kommt der Kunde von dort). Nach der Kundenwahl wird – falls am Kunden ein customer_primary_address hinterlegt ist – automatisch dessen Kundenadresse vorbelegt; das Feld selbst zeigt nur Adressen des gewählten Kunden zur Auswahl (Standard-Frappe-Adresssuche). Beim Auswählen einer Adresse werden die Empfänger-Felder (Name, Straße, PLZ, Ort, Land, E-Mail, Telefon) damit überschrieben – spart bei wiederkehrenden Kunden das manuelle Abtippen.

Storno der Versandsendung: * DHL – Sendung wird per DELETE /orders gelöscht. * DPD – nicht nötig (nicht manifestierte Sendungen einfach nicht abschließen). * Deutsche Post – Retoure (Erstattung) wird automatisch per POST /app/retoure beantragt, sofern im Produktiv-Modus eine echte Marke gekauft wurde.


Sendungsverfolgung

Nach dem Etikett läuft der Status automatisch nach:

  • Versandsendung → Abschnitt „Sendungsverfolgung": Status (Angekündigt · Abgeholt · In Transport · In Zustellung · Zugestellt · Zustellproblem · Retoure), Carrier-Statustext, „Zugestellt am" und ein Ereignis-Verlauf. Button „Tracking aktualisieren" für sofort.
  • Lieferschein: Status + „Zugestellt am" gespiegelt, als Spalte/Filter in der Liste.
  • Hintergrund-Job (hourly_long) aktualisiert alle offenen, gebuchten Sendungen; stoppt nach Zustellung/Retoure bzw. nach X Tagen (Standard 21).
  • Alte Sendungsnummern: Carrier (DHL z. B. nach ~4 Wochen) liefern für abgelaufene Sendungsnummern irgendwann nur noch „Unbekannt"/404. Ein solches Ergebnis überschreibt nie einen bereits bekannten Status – sonst würden alte, längst zugestellte Sendungen wieder auf „offen" zurückfallen. Stattdessen wird der letzte bekannte Status eingefroren, Carrier liefert keine Trackingdaten mehr gesetzt und die automatische Verfolgung für diese Sendung beendet.
  • Arbeitsfläche „Versand" mit Kennzahlen Sendungen unterwegs / Zustellprobleme und Schnellzugriffen.
  • Benachrichtigung bei Zustellproblem/Retoure an alle Nutzer einer Rolle (Standard Stock Manager), optional zusätzlich per E-Mail.

Konfiguration: Versand Integration Settings. Quellen: DHL = „Parcel DE Tracking"-API (nur API-Key), DPD = öffentlicher tracking.dpd.de-Endpunkt (best effort). Deutsche Post: manche Produkte (Briefe/Warensendungen mit „Basistracking") liefern eine Track-ID (Voucher.trackId aus der Checkout-Antwort), die wir bereits in tracking_number übernehmen – eine automatische Statusabfrage dafür gibt es aber noch nicht (keine verifizierte API-Referenz für diese IDs). Der Hintergrund-Job fragt ohnehin nur carrier in [DHL, DPD] ab; zusätzlich wird bei Deutsche-Post-Sendungen „Automatisch weiter verfolgen" direkt beim Erstellen deaktiviert (statt es für immer aktiv, aber wirkungslos stehen zu lassen) – über BaseCarrier.supports_tracking (False bei DeutschePostCarrier). Ist eine Track-ID vorhanden, steht das im Statustext, Status lässt sich vorerst nur manuell bei der Post-/DHL-Sendungsverfolgung prüfen.


Abholung (DPD/DHL) & DHL-Retoure

DPD – Abholtag steuern

DPD hat keine eigene Abhol-API – der Abholtag wird direkt im ShipmentService-Aufruf über `gesetzt (carriers/dpd/pickup.py:resolveshippingdate`). An der Versandsendung (Carrier DPD) steht dazu das Feld „Abholtag":

  • (leer) – kein shippingDate gesetzt, DPD nimmt den nächsten Werktag.
  • Morgen / Übermorgen – auf Sonntag automatisch auf Montag verschoben.
  • Wunschtag – konkretes Datum im Feld „Abholtag (Datum)".

Button „Für die ganze Woche buchen" (nur DPD, gespeicherter Entwurf) erzeugt über versand_integration.api.create_week_shipments fünf Kopien der aktuellen Versandsendung, je eine pro Werktag der laufenden/nächsten Woche (Wunschtag + berechnetes Datum), und bucht optional direkt das Etikett für jede. Schlägt ein einzelner Tag fehl, wird das protokolliert, die übrigen Tage laufen trotzdem durch.

Der Endpunkt ist auf maximal 10 Tage pro Aufruf begrenzt und lehnt Sendungen ab, deren Carrier nicht DPD ist (api.MAX_WEEK_SHIPMENTS) – jeder Tag löst einen echten, kostenpflichtigen Versandauftrag aus, und whitelisted Endpunkte sind auch ohne den Button direkt aufrufbar.

DHL – Retoure

Checkbox „DHL-Retoure" an der Versandsendung (nur DHL) fügt dem /orders-Aufruf den Service dhlRetoure hinzu; DHL liefert dann neben dem normalen Label ein zweites Retourenlabel zurück, das an return_label_file abgelegt wird (Button „Retourenlabel öffnen"). Die Abrechnungsnummer fürs Retourenverfahren (Verfahren 08) kommt – wie bei den anderen DHL-Produkten – über die Absender-Auflösungskette: Versandabsender-Override → DHL Settings.billing_number_return als Fallback.

DHL – Abholauftrag

Eigenständiges DocType DHL Abholauftrag (Paket DE Abholen v3, gleicher OAuth2-Client wie die Shipping-API) für die Beauftragung einer Abholung, unabhängig von einzelnen Versandsendungen:

  • Abholart „Beliebige Adresse" – Adresse frei eintragen (oder aus dem Versandabsender übernehmen); DHL kann dafür laut Spezifikation auch dann Kosten berechnen, wenn die Abholung nicht klappt.
  • Abholart „Vereinbarter Abholort" – Auswahl aus DHL Abholort (Stammdaten via GET /locations, Button „Abholorte aktualisieren" in den DHL Settings).
  • Sendungen (Child-Tabelle) mit optionaler Größe (S/M/L)

Related Integrations apps for Frappe & ERPNext

  • Insights — Open Source Business Intelligence Tool
  • Raven — Simple, open source team messaging platform
  • Frappe Whatsapp — WhatsApp cloud integration for frappe
  • Frappe Assistant Core — Infrastructure that connects LLMs to ERPNext. Frappe Assistant Core works with the Model Context Protocol (MCP) to expose ERPNext functionality to any compatible Language Model
  • Biometric Attendance Sync Tool — A simple tool for syncing Biometric Attendance data with your ERPNext server
  • Frappe React Sdk — React hooks for Frappe
  • Frappe Js Sdk — TypeScript/JavaScript library for Frappe REST API
  • Mcp — Frappe MCP allows Frappe apps to function as MCP servers