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, den die Label API intern verwendet

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
`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.