Praxis-Tutorial · Schritt für Schritt
UPS-Versandlabels mit Azure Functions und C# erstellen
1. Was geschieht beim Erstellen eines Versandlabels?
Ein Versandlabel ist das Ergebnis einer Versandbuchung beim Transportdienstleister. Ein ERP übermittelt Absender, Empfänger, Pakete und ausgewählten Versandservice an eine API. Eine erfolgreiche Antwort liefert meist eine Trackingkennung und die Labeldaten. Wichtig: Dieser Aufruf kann eine kostenpflichtige oder bindende Sendung erzeugen und darf nicht beliebig wiederholt werden.
2. Die Komponenten der Integration
Business Central erzeugt die Versandanforderung. Eine geschützte .NET-Azure-Function validiert den Auftrag, holt die nötige UPS-Autorisierung serverseitig und ruft die offizielle UPS Shipping API auf. Das Antwortformat wird geprüft; Trackingnummer und ZPL- oder Bildlabel gelangen an das ERP zurück. Ein technisches Journal hält den Status fest.
3. Voraussetzungen
Du benötigst ein freigeschaltetes UPS-Entwicklerkonto, die aktuell gültige UPS-API-Dokumentation und geeignete Testzugänge. Prüfe Serviceverfügbarkeit, Länder, Paketarten, Gewichtseinheiten und Label-Format. Bereite eine Azure Function mit .NET-Isolated-Worker, sichere Konfiguration und einen Testclient vor.
4. Warum Tokens nicht im Request-Body stehen sollten
Ein Aufrufer sollte keinen fremden UPS-Zugriffstoken im allgemeinen API-JSON mitschicken. Die Function verwaltet OAuth-Zugangsdaten geschützt und bezieht selbst das erforderliche Token. Dazu kommen Authentifizierung des ERP gegenüber der eigenen Function und klare Berechtigungen. Secrets gehören nicht in Quellcode, URLs, HTTP-Protokolle oder Anwendungslogs.
5. Ein klares Eingabeschema
Das folgende JSON illustriert nur den fachlichen Vertrag. Die konkrete UPS-Payload wird entsprechend der aktuellen API-Spezifikation daraus erzeugt.
{
"shipmentId": "SHIP-10042",
"service": "STANDARD",
"shipTo": {
"name": "Sample Recipient",
"country": "DE",
"postalCode": "10115"
},
"package": { "weightKg": 2.5 }
}6. Validierung vor dem UPS-Aufruf
Prüfe Pflichtdaten, Postleitzahl, Länderkennzeichen, Gewicht größer null, Maße und die zulässige Servicewahl. Weise ungültige Eingaben als 400 oder fachlichen Validierungsfehler zurück. Das schützt vor unnötigen API-Anfragen und unvollständigen Versandbuchungen.
7. Den Versandservice nicht heimlich wechseln
Ein Expressversand kann andere Kosten und Laufzeiten haben als Standard. Wenn UPS meldet, dass ein bestimmter Service nicht verfügbar ist, darf die Anwendung nicht stillschweigend auf einen teureren Service umstellen. Liefere vielmehr erlaubte Alternativen zur Auswahl zurück oder nutze eine vorher ausdrücklich vereinbarte Fallback-Regel. Eine Fehlermeldung anhand des Wortes „unavailable“ im Antworttext zu erkennen ist nicht robust; werte strukturierte Fehlercodes aus.
8. API-Antwort und ZPL verstehen
ZPL ist eine Druckersprache für kompatible Thermodrucker. Prüfe, ob die UPS-Antwort tatsächlich ZPL enthält oder beispielsweise ein Base64-kodiertes Bild/PDF. Dekodiere nur erwartete Formate, speichere Trackingnummer und Labelbezug und teste den Ausdruck auf dem vorgesehenen Druckermodell. Nicht jeder Drucker verarbeitet ZPL.
9. Idempotenz bei kostenpflichtigen Aktionen
Ein Timeout bedeutet nicht, dass UPS die Sendung nicht angelegt hat. Halte eine eindeutige interne Versandvorgangs-ID dauerhaft fest. Bevor ein fehlgeschlagener Aufruf erneut startet, kläre, ob bereits eine Sendung existiert; nutze vorhandene UPS-Referenz- und Statusmechanismen, soweit sie der API-Vertrag unterstützt. Ein identischer eigener Request garantiert keine automatische Deduplizierung beim Transportdienstleister.
10. Monitoring und Fehlerklassen
Dokumentiere Vorgangs-ID, UPS-Referenz, Status, Trackingnummer und sichere technische Fehlermeldungen. Unterscheide fehlerhafte Adressen, fehlende Berechtigungen, unbekannte Servicecodes, 429-Drosselung und 5xx-Störungen. Gib Fehler nicht als HTTP 200 mit einem Feld error zurück; nutze fachlich passende Statuscodes.
11. Testfälle vor dem Produktivbetrieb
Teste nationale und internationale Anschriften, Paketgrenzen, mehrere Servicearten, ungültige Empfänger, unterbrochene Requests und doppelte Anforderungen. Nutze für Tests die dokumentierte Testumgebung, nicht versehentlich das produktive UPS-Konto. Prüfe, wann eine Stornierung oder Rückabwicklung erforderlich ist.
12. Zusammenfassung
Eine sichere Labelintegration trennt die ERP-Fachlogik, UPS-Autorisierung, Versandbuchung und Druckausgabe. Die Beispiele dienen zum Verständnis; produktive Payloads und Servicecodes müssen mit der aktuellen UPS-Dokumentation abgeglichen werden.
Kommentare (0)
Noch keine Kommentare. Schreibe den ersten Beitrag zur Diskussion.