Erpnext Versand
ERPNext-App: Versandetiketten direkt über die DHL Parcel DE Shipping API v2 (Architektur für DPD & Deutsche Post/Portokasse)
- Author: DrdotHouse2106
- Repository: https://github.com/DrdotHouse2106/ERPNext-Versand
- GitHub stars: 0
- Forks: 0
- License: MIT
- Category: Integrations
- Maintenance: Actively Maintained
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:
[](https://frappegems.com/gems/apps/DrdotHouse2106/ERPNext-Versand)
About Erpnext Versand
ERPNext Versand Integration
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 mehrgesetzt 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
shippingDategesetzt, 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