Developer Interface

This page is for AL developers who want to create DHL labels without the Create Label Dialog or extend the connector through events. It is not required for normal use of the app.

Every entry point described here takes the same route as the dialog: licence check, shipping rules, contract resolution, tracking entry and the hub events all apply.

Object	Purpose
`ALN MCDHL Label API` (codeunit 73334792)	Create a label for a sales order or a posted sales shipment
`ALN MCDHL Label Services` (codeunit 73334782)	Service codes of the additional services and helpers for the service selection
`ALN MCDHL Evt Publisher` (codeunit 73334798)	Public events of the request builder and the shipping rules
`ALN MC Shipment Mgmt.` (hub, codeunit 73334603)	Carrier-neutral hub entry point: the route of the "Create Label (1-Click)" action, also used internally by the Label API

Which route fits?

Goal	Route
Label on release or posting, without intervention	Automatic labels, no code at all
Exactly what "Create Label (1-Click)" does, from your own process	1-click label from code
Label with specific DHL services, weight or product	Creating a label through the Label API

Without code: automatic labels

If the label should be created when the sales order is released or the shipment is posted, no programming is needed. On the shipment provider card, in the Automation section, set the field Auto Create Label to On Release or On Post.

Release and posting then only create an entry. The job queue creates the label every five minutes by the same route as the 1-click action, each order in a transaction of its own. A carrier problem is recorded on the entry and blocks neither release nor posting. See Automatic Labels for details.

1-click label from code

The Create Label (1-Click) action on the sales order calls exactly two public hub procedures. Your own code gets the same result with the same calls:

var
    ShipmentMgmt: Codeunit "ALN MC Shipment Mgmt.";
    ShipmentLabel: Record "ALN MC Shipment Label";
    ProviderCode: Code[20];
    EntryNo: Integer;
begin
    ProviderCode := ShipmentMgmt.ResolveDefaultProvider('SO-2026-01187');
    if ProviderCode = '' then
        Error(NoProviderErr);  // no unambiguous shipment provider

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

    ShipmentLabel.Get(EntryNo);
    case ShipmentLabel.Status of
        ShipmentLabel.Status::Created:
            ;  // ShipmentLabel."Tracking No." is filled
        ShipmentLabel.Status::Error:
            ;  // ShipmentLabel."Error Message" holds the DHL message
    end;
end;

Parameters

Procedure	Parameters	Returns
`ResolveDefaultProvider`	`SalesOrderNo: Code[20]`: number of the sales order	`Code[20]`: shipment provider code, empty when none is unambiguous
`CreateLabel`	`ProviderCode: Code[20]`, `SalesOrderNo: Code[20]`	`Integer`: `Entry No.` of the `ALN MC Shipment Label`
`CreateLabelFromShipment`	`ProviderCode: Code[20]`, `SalesShipmentNo: Code[20]`: number of the posted shipment	same as `CreateLabel`

For a posted shipment, resolve the provider with ResolveDefaultProvider and the shipment's order number (Order No.).

What the call decides

Shipment provider. In this order: the provider for the order's Shipping Agent Code, then the default shipment provider of the merchantCENTRAL setup, then the only enabled provider. The item category does not choose the provider.
Lines. The item category decides which lines travel. Lines whose category is bound to a different shipping agent are left out of weight, package contents, customs positions and shipping rules. If all shippable lines are bound elsewhere, CreateLabel stops with an error. See Lines That Do Not Travel With This Label.
Weight and product. The weight comes from the order, the DHL product from the default contract line. A default packaging material is applied if one is set up. Customs data of international shipments is filled from the order.
Services. The DHL setup defaults the dialog preselects as well: GoGreen Plus, insurance, bulky goods, include return label, preferred neighbour, preferred location, no neighbour delivery, visual check of age, named person only and signed for by recipient. Incompatible combinations are resolved as in the dialog. The shipping rules add to them afterwards. Not applied are the insurance suggestion by order value (it stays a recommendation in the dialog) and the default endorsement. Older versions of the DHL connector (up to 1.22) apply the shipping rules only. Different services per call: Label API.

Errors and result

No order, no licence, disabled provider or no travelling line: Error(), no label is created.
A failed DHL call does not raise an error. The label then has Status = Error and the DHL message is stored in Error Message. OnCreateShipmentLabelError is raised as well.
On success, OnAfterCreateShipmentLabel is raised with the tracking number. That is the hook for follow-up steps such as printing or reporting back to another system.

Do not call it from release or posting

CreateLabel calls DHL over HTTP. In a subscriber on release or posting that holds the locks for the network round trip, and if posting fails later, DHL has a shipment for a document that does not exist. Use automatic labels or a job queue entry of your own instead. In your own run, process each order in a transaction of its own so that one failure does not roll back the others:

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

My Label Runner is a codeunit of your own with TableNo = "Sales Header" whose OnRun contains the call above.

Creating a label

Additional services are passed as a temporary ALN MCDHL Shipment VAS record. Every field of that record is honoured, including the ones the dialog does not offer: cash on delivery, ident check, Packstation, endorsement, return address.

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('SO-2026-01187', TempVAS);
end;

CreateLabelFromShipment works the same way but expects the number of a posted sales shipment. Both procedures also exist with weight in grams, product code (shipping agent service code), ship-to overrides and a hub service selection:

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

Return value and errors

The return value is the Entry No. of the ALN MC Shipment Label record.
A provider or licence problem raises Error(); no label is created.
A failed DHL call does not raise an error. The label then has Status = Error and the DHL message is stored in Error Message.
Shipping rules run on this route as well. They add services but never overwrite values you passed in.
The DHL setup defaults the dialog preselects (default GoGreen Plus, default insurance and so on) are not applied. Pass them explicitly.
Where the VAS record and the service selection set the same field, the service selection wins.
A service parameter that does not match the format or is too long raises an error. No label is created with a service silently missing.

Service codes

Instead of the VAS record, services can be passed as a hub service selection (ALN MC Label Svc. Selection). This is the route the hub REST API uses as well. The codes are published by ALN MCDHL Label Services; parameters are limited to two fields of 50 characters.

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	Procedure	Service	Parameter 1	Parameter 2
`GOGREEN_PLUS`	`GoGreenPlus()`	GoGreen Plus	–	–
`BULKY_GOODS`	`BulkyGoods()`	Bulky goods	–	–
`RETURN_LABEL`	`ReturnLabel()`	Include return label	–	–
`PREF_NEIGHBOUR`	`PreferredNeighbour()`	Preferred neighbour	Name and address	–
`PREF_LOCATION`	`PreferredLocation()`	Preferred location	Drop-off location	–
`NO_NEIGHBOUR`	`NoNeighbourDelivery()`	No neighbour delivery	–	–
`PREF_DAY`	`PreferredDay()`	Preferred day	Date `yyyy-mm-dd`	–
`AGE_CHECK`	`AgeCheck()`	Visual check of age	`A16` or `A18`	–
`NAMED_PERSON_ONLY`	`NamedPersonOnly()`	Named person only	–	–
`SIGNED_BY_RECIPIENT`	`SignedByRecipient()`	Signed for by recipient	–	–
`INSURANCE`	`Insurance()`	Transport insurance	Amount, point as decimal separator	ISO currency
`IDENT_CHECK`	`IdentCheck()`	Ident check	`First\|Last\|yyyy-mm-dd`	`A16` or `A18`
`LOCKER`	`Locker()`	Packstation	Locker ID	Post number
`POSTFILIALE`	`PostOffice()`	Post office branch	Retail ID	Post number
`ENDORSEMENT`	`Endorsement()`	Endorsement	`RETURN` or `ABANDON`	–
`PDDP`	`PostalDeliveryDutyPaid()`	Postal Delivery Duty Paid	–	–
`PREMIUM`	`Premium()`	Premium (international)	–	–

Parameter helpers: FormatDateParameter, FormatAmountParameter, AgeCheckParameter, BuildIdentCheckParameter. The values are independent of the session language; amounts and dates are written in XML format.

Cash on delivery

Cash on delivery needs account holder, IBAN, BIC and transfer notes and therefore has no service code. It is passed exclusively through the fields Cash on Delivery, COD Amount, COD Currency and COD * of the VAS record.

Events

Hub (ALN MC Shipment Evt Publisher, codeunit 73334602)

Event	When
`OnApplyQuickLabelDefaults`	Quick label (1-click, batch, automatic labels) inserted, before the DHL call; the connector applies its setup defaults here
`OnAfterCreateShipmentLabel`	Label created successfully, tracking entry written
`OnCreateShipmentLabelError`	DHL call failed, label stored with status Error
`OnAfterCancelShipment`	Shipment cancelled
`OnAfterDeliveryStatusChanged`	Delivery status changed by tracking

DHL (ALN MCDHL MC Integration, codeunit 73334775)

Event	When
`OnBeforeCreateDHLLabel`	Before shipping rules and request building, `IsReturn` marks return labels
`OnAfterCreateDHLLabel`	After a successful DHL response

DHL (ALN MCDHL Evt Publisher, codeunit 73334798)

Event	When
`OnAfterBuildShipmentJson`	The JSON of one shipment is complete and can be enriched before sending
`OnBeforeApplyRuleAction`	Before the action of a matching shipping rule, `IsHandled` replaces the default action
`OnAfterApplyRuleAction`	After the action of a matching shipping rule

The events of the same name in ALN MCDHL Request Builder and ALN MCDHL Rules Engine are obsolete. Those codeunits are internal; other apps could never subscribe to them.

Notes

Licence. The Label API checks the DHL licence like the dialog does. Without an active licence or demo no label is created.
Permissions. The calling user needs the permission set ALN MCDHL User or the execute rights on the codeunits it contains.
Services and participation. Services such as bulky goods or insurance need a matching DHL participation in the contract lines, see Profiles & Billing.
Context on abort. If the hub aborts before the label exists, no state is left behind that could affect a later label. The VAS record you pass is bound to the document number.