Entwicklerschnittstelle

Diese Seite richtet sich an AL-Entwickler, die DHL-Labels ohne den Dialog „Label erstellen" erzeugen oder den Connector über Events erweitern möchten. Für die normale Nutzung der App ist sie nicht erforderlich.

Alle hier beschriebenen Einstiege laufen über denselben Weg wie der Dialog: Lizenzprüfung, Versandregeln, Vertragsauflösung, Tracking-Eintrag und die Hub-Events greifen in jedem Fall.

Objekt	Zweck
`ALN MCDHL Label API` (Codeunit 73334792)	Label für einen Verkaufsauftrag oder eine gebuchte Lieferung erzeugen
`ALN MCDHL Label Services` (Codeunit 73334782)	Service-Codes der Zusatzleistungen und Helfer für die Service-Auswahl
`ALN MCDHL Evt Publisher` (Codeunit 73334798)	Öffentliche Events des Request Builders und der Versandregeln
`ALN MC Shipment Mgmt.` (Hub, Codeunit 73334603)	Carrier-neutraler Einstieg des Hubs: Weg der Aktion „Label erstellen (1-Klick)", intern auch von der Label API verwendet

Welcher Weg passt?

Ziel	Weg
Label bei Freigabe oder Buchung, ohne Eingriff	Automatische Labels, ganz ohne eigenen Code
Genau das, was „Label erstellen (1-Klick)" tut, aus einem eigenen Prozess	1-Klick-Label per Code
Label mit bestimmten DHL-Zusatzleistungen, Gewicht oder Produkt	Label erzeugen über die Label API

Ohne eigenen Code: automatische Labels

Soll das Label bei der Freigabe des Verkaufsauftrags oder bei der Buchung der Lieferung entstehen, braucht es keine Programmierung. Auf der Karte des Versanddienstleisters im Bereich Automatisierung das Feld Etikett automatisch erstellen auf Bei Freigabe oder Bei Buchung setzen.

Freigabe und Buchung legen dann nur einen Posten an. Die Aufgabenwarteschlange erstellt das Label alle fünf Minuten über denselben Weg wie der 1-Klick, jeden Auftrag in einer eigenen Transaktion. Ein Fehler beim Dienstleister landet im Posten und blockiert weder Freigabe noch Buchung. Einzelheiten unter Automatische Labels.

1-Klick-Label per Code

Die Aktion Label erstellen (1-Klick) am Verkaufsauftrag ruft genau zwei öffentliche Prozeduren des Hubs auf. Eigener Code erreicht mit demselben Aufruf dasselbe Ergebnis:

var
    ShipmentMgmt: Codeunit "ALN MC Shipment Mgmt.";
    ShipmentLabel: Record "ALN MC Shipment Label";
    ProviderCode: Code[20];
    EntryNo: Integer;
begin
    ProviderCode := ShipmentMgmt.ResolveDefaultProvider('VA-2026-01187');
    if ProviderCode = '' then
        Error(NoProviderErr);  // kein eindeutiger Versanddienstleister

    EntryNo := ShipmentMgmt.CreateLabel(ProviderCode, 'VA-2026-01187');

    ShipmentLabel.Get(EntryNo);
    case ShipmentLabel.Status of
        ShipmentLabel.Status::Created:
            ;  // ShipmentLabel."Tracking No." ist gefüllt
        ShipmentLabel.Status::Error:
            ;  // ShipmentLabel."Error Message" enthält die DHL-Meldung
    end;
end;

Parameter

Prozedur	Parameter	Rückgabe
`ResolveDefaultProvider`	`SalesOrderNo: Code[20]`: Nummer des Verkaufsauftrags	`Code[20]`: Versanddienstleister-Code, leer wenn keiner eindeutig ist
`CreateLabel`	`ProviderCode: Code[20]`, `SalesOrderNo: Code[20]`	`Integer`: `Entry No.` des `ALN MC Shipment Label`
`CreateLabelFromShipment`	`ProviderCode: Code[20]`, `SalesShipmentNo: Code[20]`: Nummer der gebuchten Lieferung	wie `CreateLabel`

Den Versanddienstleister für eine gebuchte Lieferung ermitteln Sie ebenfalls mit ResolveDefaultProvider und der Auftragsnummer der Lieferung (Order No.).

Was der Aufruf entscheidet

Versanddienstleister. Reihenfolge: Dienstleister zum Shipping Agent Code des Auftrags, dann der Standard-Versanddienstleister der merchantCENTRAL-Einrichtung, dann der einzige aktive Dienstleister. Die Artikelkategorie wählt den Dienstleister nicht aus.
Positionen. Die Artikelkategorie entscheidet, welche Zeilen mitreisen. Zeilen, deren Kategorie an einen anderen Versandpartner gebunden ist, fehlen in Gewicht, Packstückinhalt, Zollpositionen und Versandregeln. Sind alle lieferbaren Zeilen anderswo gebunden, bricht CreateLabel mit einem Fehler ab. Siehe Zeilen, die nicht mit diesem Label reisen.
Gewicht und Produkt. Das Gewicht kommt aus dem Auftrag, das DHL-Produkt aus der Standardzeile der Vertragszeilen. Ist ein Standard-Verpackungsmaterial eingerichtet, wird es angewendet. Zolldaten internationaler Sendungen werden aus dem Auftrag befüllt.
Zusatzleistungen. Die Vorgaben der DHL-Einrichtung, die auch der Dialog vorbelegt: GoGreen Plus, Versicherung, Sperrgut, Retourenlabel beilegen, Wunschnachbar, Wunschort, Keine Nachbarschaftszustellung, Alterssichtprüfung, Persönliche Übergabe und Empfängerunterschrift. Unverträgliche Kombinationen werden wie im Dialog aufgelöst. Danach ergänzen die Versandregeln. Nicht übernommen werden der Versicherungsvorschlag nach Warenwert (er bleibt eine Empfehlung im Dialog) und die Standard-Vorausverfügung. Ältere Versionen des DHL-Connectors (bis 1.22) wenden nur die Versandregeln an. Andere Leistungen je Aufruf: Label API.

Fehler und Ergebnis

Kein Auftrag, keine Lizenz, inaktiver Dienstleister oder keine mitreisende Zeile: Error(), es entsteht kein Label.
Ein fehlgeschlagener DHL-Aufruf löst keinen Fehler aus. Das Label hat dann Status = Error und die DHL-Meldung steht in Error Message. Zusätzlich feuert OnCreateShipmentLabelError.
Bei Erfolg feuert OnAfterCreateShipmentLabel mit der Sendungsnummer. Das ist der Einstieg für Folgeschritte wie Druck oder Rückmeldung an ein Fremdsystem.

Nicht aus der Freigabe oder Buchung heraus aufrufen

CreateLabel ruft DHL per HTTP auf. In einem Subscriber auf Freigabe oder Buchung hält das die Sperren über die Netzwerklatenz, und nach einem späteren Abbruch der Buchung existiert bei DHL eine Sendung zu einem Beleg, den es nicht gibt. Verwenden Sie dafür die automatischen Labels oder einen eigenen Job-Queue-Eintrag. Im eigenen Lauf jeden Auftrag in einer eigenen Transaktion ausführen, damit ein Fehler nicht die übrigen zurückrollt:

Commit();
if not Codeunit.Run(Codeunit::"My Label Runner", SalesHeader) then
    LogFailure(SalesHeader."No.", GetLastErrorText());

My Label Runner ist dabei eine eigene Codeunit mit TableNo = "Sales Header", deren OnRun den Aufruf oben enthält.

Label erzeugen

Die Zusatzleistungen werden als temporärer Datensatz ALN MCDHL Shipment VAS übergeben. Jedes Feld dieses Datensatzes wird übernommen, auch die, die der Dialog nicht anbietet: Nachnahme, Identprüfung, Packstation, Vorausverfügung, Rücksendeadresse.

var
    LabelApi: Codeunit "ALN MCDHL Label API";
    TempVAS: Record "ALN MCDHL Shipment VAS" temporary;
    EntryNo: Integer;
begin
    TempVAS.Init();
    TempVAS."Visual Check of Age" := TempVAS."Visual Check of Age"::A18;
    TempVAS."Additional Insurance" := true;
    TempVAS."Insurance Amount" := 2500;
    TempVAS."Insurance Currency" := 'EUR';

    EntryNo := LabelApi.CreateLabel('VA-2026-01187', TempVAS);
end;

CreateLabelFromShipment arbeitet gleich, erwartet aber die Nummer einer gebuchten Verkaufslieferung. Beide Prozeduren gibt es zusätzlich mit Gewicht in Gramm, Produktcode (Versandart-Servicecode), Ship-to-Overrides und einer Hub-Service-Auswahl:

EntryNo := LabelApi.CreateLabel(
    'VA-2026-01187', 1850, 'PAKET', TempShipToOverrides, TempVAS, TempLabelSvcSelection);

Rückgabe und Fehler

Rückgabe ist die Entry No. des Datensatzes ALN MC Shipment Label.
Ein Fehler beim Provider oder bei der Lizenz löst Error() aus, es entsteht kein Label.
Ein fehlgeschlagener DHL-Aufruf löst keinen Fehler aus. Das Label hat dann Status = Error und die DHL-Meldung steht in Error Message.
Versandregeln laufen auch bei diesem Weg und ergänzen Leistungen, überschreiben aber keine übergebenen Werte.
Die Vorgaben der DHL-Einrichtung, die der Dialog vorbelegt (Standard GoGreen Plus, Standard Versicherung usw.), werden nicht angewendet. Übergeben Sie sie ausdrücklich.
Setzen VAS-Datensatz und Service-Auswahl dasselbe Feld, gewinnt die Service-Auswahl.
Ein Service-Parameter, der nicht ins Format passt oder zu lang ist, löst einen Fehler aus. Es entsteht kein Label mit stillschweigend fehlender Leistung.

Service-Codes

Alternativ zum VAS-Datensatz lassen sich Leistungen als Hub-Service-Auswahl (ALN MC Label Svc. Selection) übergeben. Das ist der Weg, den auch die REST-API des Hubs verwendet. Die Codes stellt ALN MCDHL Label Services bereit; die Parameter sind auf zwei Felder mit je 50 Zeichen begrenzt.

var
    LabelServices: Codeunit "ALN MCDHL Label Services";
    TempLabelSvcSelection: Record "ALN MC Label Svc. Selection" temporary;
begin
    LabelServices.AddService(TempLabelSvcSelection, LabelServices.AgeCheck(), 'A18', '');
    LabelServices.AddService(TempLabelSvcSelection, LabelServices.Insurance(),
        LabelServices.FormatAmountParameter(2500), 'EUR');
    LabelServices.AddService(TempLabelSvcSelection, LabelServices.Locker(), '123', '12345678');
end;

Code	Prozedur	Leistung	Parameter 1	Parameter 2
`GOGREEN_PLUS`	`GoGreenPlus()`	GoGreen Plus	–	–
`BULKY_GOODS`	`BulkyGoods()`	Sperrgut	–	–
`RETURN_LABEL`	`ReturnLabel()`	Retourenlabel beilegen	–	–
`PREF_NEIGHBOUR`	`PreferredNeighbour()`	Wunschnachbar	Name und Adresse	–
`PREF_LOCATION`	`PreferredLocation()`	Wunschort	Ablageort	–
`NO_NEIGHBOUR`	`NoNeighbourDelivery()`	Keine Nachbarschaftszustellung	–	–
`PREF_DAY`	`PreferredDay()`	Wunschtag	Datum `yyyy-mm-dd`	–
`AGE_CHECK`	`AgeCheck()`	Alterssichtprüfung	`A16` oder `A18`	–
`NAMED_PERSON_ONLY`	`NamedPersonOnly()`	Persönliche Übergabe	–	–
`SIGNED_BY_RECIPIENT`	`SignedByRecipient()`	Empfängerunterschrift	–	–
`INSURANCE`	`Insurance()`	Transportversicherung	Betrag, Punkt als Dezimaltrenner	Währung ISO
`IDENT_CHECK`	`IdentCheck()`	Identprüfung	`Vorname\|Nachname\|yyyy-mm-dd`	`A16` oder `A18`
`LOCKER`	`Locker()`	Packstation	Locker-ID	Postnummer
`POSTFILIALE`	`PostOffice()`	Filiale	Retail-ID	Postnummer
`ENDORSEMENT`	`Endorsement()`	Vorausverfügung	`RETURN` oder `ABANDON`	–
`PDDP`	`PostalDeliveryDutyPaid()`	Postal Delivery Duty Paid	–	–
`PREMIUM`	`Premium()`	Premium (international)	–	–

Helfer für die Parameter: FormatDateParameter, FormatAmountParameter, AgeCheckParameter, BuildIdentCheckParameter. Die Werte sind unabhängig von der Sitzungssprache, Betrag und Datum werden im XML-Format geschrieben.

Nachnahme

Nachnahme braucht Kontoinhaber, IBAN, BIC und Verwendungszwecke und hat deshalb keinen Service-Code. Sie wird ausschließlich über die Felder Cash on Delivery, COD Amount, COD Currency und COD * des VAS-Datensatzes übergeben.

Events

Hub (ALN MC Shipment Evt Publisher, Codeunit 73334602)

Event	Zeitpunkt
`OnApplyQuickLabelDefaults`	Schnell-Label (1-Klick, Batch, automatische Labels) angelegt, vor dem DHL-Aufruf; hier setzt der Connector die Einrichtungsvorgaben
`OnAfterCreateShipmentLabel`	Label erfolgreich erzeugt, Tracking-Eintrag angelegt
`OnCreateShipmentLabelError`	DHL-Aufruf fehlgeschlagen, Label mit Status Error gespeichert
`OnAfterCancelShipment`	Sendung storniert
`OnAfterDeliveryStatusChanged`	Zustellstatus aus der Sendungsverfolgung geändert

DHL (ALN MCDHL MC Integration, Codeunit 73334775)

Event	Zeitpunkt
`OnBeforeCreateDHLLabel`	Vor Versandregeln und Request-Aufbau, `IsReturn` unterscheidet Retoure
`OnAfterCreateDHLLabel`	Nach erfolgreicher Antwort von DHL

DHL (ALN MCDHL Evt Publisher, Codeunit 73334798)

Event	Zeitpunkt
`OnAfterBuildShipmentJson`	JSON einer Sendung ist fertig und kann vor dem Senden ergänzt werden
`OnBeforeApplyRuleAction`	Vor der Aktion einer passenden Versandregel, `IsHandled` ersetzt die Standardaktion
`OnAfterApplyRuleAction`	Nach der Aktion einer passenden Versandregel

Die gleichnamigen Events in ALN MCDHL Request Builder und ALN MCDHL Rules Engine sind veraltet. Diese Codeunits sind intern, Fremd-Apps konnten sie nie abonnieren.

Hinweise

Lizenz. Die Label API prüft die DHL-Lizenz wie der Dialog. Ohne aktive Lizenz oder Demo entsteht kein Label.
Berechtigungen. Der aufrufende Benutzer braucht den Berechtigungssatz ALN MCDHL User oder die darin enthaltenen Rechte auf die Codeunits.
Zusatzleistungen und Teilnahme. Leistungen wie Sperrgut oder Versicherung brauchen eine passende DHL-Teilnahme in den Vertragszeilen, siehe Profile & Abrechnung.
Kontext bei Abbruch. Bricht der Hub vor dem Anlegen des Labels ab, bleibt kein Zustand zurück, der ein späteres Label beeinflussen könnte. Der übergebene VAS-Datensatz ist an die Belegnummer gebunden.