> For the complete documentation index, see [llms.txt](https://docs.solutioo.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.solutioo.de/entwicklerdokumentationen-business-central-dhl-connector/dhl-connector-entwicklerdokumentation/integrationsbeispiele.md).

# Integrationsbeispiele

Die folgenden Beispiele verwenden Objekt-IDs aus einem fiktiven Consumer-Bereich. Sie müssen an den eigenen Bereich und die eigenen Präfixe angepasst werden.

## Pakete automatisch erzeugen

```al
codeunit 50130 "My DHL Packing"
{
    procedure CreateSuggestedPackages(OrderNo: Code[20]; BoxCode: Code[20])
    var
        SalesHeader: Record "Sales Header";
        DhlPackingMgt: Codeunit "SOUDHL Packing Mgt";
    begin
        SalesHeader.Get(SalesHeader."Document Type"::Order, OrderNo);

        // 0 = Paketanzahl automatisch bestimmen.
        DhlPackingMgt.CreatePackages(SalesHeader, 0, BoxCode);
    end;
}
```

Für einen expliziten Modus:

```al
DhlPackingMgt.CreatePackagesWithPackingMode(
    SalesHeader,
    0,
    BoxCode,
    Enum::"SOUDHL Packing Mode"::"Smart Distribute");
```

Die Methode kann bei unvollständigen Stammdaten oder nicht passenden Artikeln einen AL-Fehler auslösen. Für unbeaufsichtigte Prozesse sollte der Aufrufer eine klar definierte Fehlerbehandlung verwenden.

## Packing-Eingaben über Event ändern

```al
[EventSubscriber(
    ObjectType::Codeunit,
    Codeunit::"SOUDHL Packing Mgt",
    'OnBeforeCreatePackages',
    '', false, false)]
local procedure ForceStandardBox(
    var SalesHeader: Record "Sales Header";
    var FixedPackageCount: Integer;
    var BoxCode: Code[20];
    var PackingMode: Enum "SOUDHL Packing Mode")
begin
    if BoxCode = '' then
        BoxCode := 'STD';
end;
```

Das Event läuft nach der Standardauflösung und vor Validierung. Ein Fehler bricht ab, bevor Pending-Pakete gelöscht werden.

## Empfänger vor dem Persistieren normalisieren

```al
[EventSubscriber(
    ObjectType::Codeunit,
    Codeunit::"SOUDHL Package Recipient Mgt",
    'OnAfterSnapshotFromSalesHeader',
    '', false, false)]
local procedure TrimRecipientName(
    var PackageHeader: Record "SOUDHL Package Header";
    SalesHeader: Record "Sales Header")
begin
    PackageHeader."Recipient Name" := DelChr(PackageHeader."Recipient Name", '<>', ' ');
end;
```

Der geänderte Header wird anschließend vom Connector gespeichert. Name, Adresse, E-Mail und Telefon nicht protokollieren.

## Label für ein vorhandenes Paket erzeugen

```al
codeunit 50131 "My DHL Labels"
{
    procedure CreateLabel(PackageId: BigInteger; DocumentNo: Code[20])
    var
        PackageHeader: Record "SOUDHL Package Header";
        DhlApi: Codeunit "SOUDHL API Management";
        ExtraMessage: Text;
    begin
        PackageHeader.Get(PackageId, DocumentNo);

        if PackageHeader.Uploaded then
            exit;

        if not DhlApi.GenerateLabel(PackageHeader, ExtraMessage) then
            Error('DHL label could not be created: %1', ExtraMessage);

        // GenerateLabel aktualisiert und committet den Datenbankdatensatz.
        PackageHeader.Get(PackageId, DocumentNo);

        if ExtraMessage <> '' then
            Message('The label was created with a warning: %1', ExtraMessage);
    end;
}
```

Für Hintergrundprozesse sollte die Warnung protokolliert oder an den aufrufenden Prozess zurückgegeben werden, statt `Message` zu verwenden.

## Labelergebnis ohne Failure-Event auswerten

```al
[EventSubscriber(
    ObjectType::Codeunit,
    Codeunit::"SOUDHL API Management",
    'OnAfterGenerateLabel',
    '', false, false)]
local procedure AfterLabel(
    PackageHeader: Record "SOUDHL Package Header";
    Success: Boolean;
    ExtraMessage: Text)
begin
    if Success then
        exit;
    // Success = false deckt fachliche und technische Fehler ab.
end;
```

Bei Erfolg läuft das Event nach dem `Commit()`. Ein Subscriber-Fehler rollt das Label nicht zurück.

## Express-Produktcode bestimmen

```al
local procedure ResolveExpressProductCode(
    Product: Enum "SOUDHL Express Product"): Code[5]
var
    ExpressHelper: Codeunit "SOUDHL Express Helper";
begin
    exit(ExpressHelper.MapProductCode(Product));
end;
```

## Live-Express-Preis abrufen

```al
local procedure GetExpressRate(
    SalesHeader: Record "Sales Header";
    Product: Enum "SOUDHL Express Product";
    WeightKg: Decimal;
    LengthCm: Decimal;
    WidthCm: Decimal;
    HeightCm: Decimal;
    var Price: Decimal;
    var Currency: Text)
var
    DhlApi: Codeunit "SOUDHL API Management";
    ExpressHelper: Codeunit "SOUDHL Express Helper";
    ProductCode: Code[5];
    ExtraMessage: Text;
begin
    if not DhlApi.IsExpress() then
        Error('The DHL Connector is not configured for DHL Express.');

    ProductCode := ExpressHelper.MapProductCode(Product);

    if not DhlApi.GetRate(
        SalesHeader."Ship-to Country/Region Code",
        SalesHeader."Ship-to Post Code",
        SalesHeader."Ship-to City",
        WeightKg,
        LengthCm,
        WidthCm,
        HeightCm,
        ProductCode,
        Price,
        Currency,
        ExtraMessage)
    then
        Error('DHL rate could not be retrieved: %1', ExtraMessage);
end;
```

`OnBeforeGetRate` kann Destination, Maße oder Produktcode ändern. `OnAfterGetRate` läuft auch dann, wenn Express nicht konfiguriert ist.

## Express-Request über Event ergänzen

```al
codeunit 50132 "My DHL Subscribers"
{
    [EventSubscriber(
        ObjectType::Codeunit,
        Codeunit::"SOUDHL API Management",
        'OnBeforeSendShipmentRequest',
        '', false, false)]
    local procedure SetExpressProduct(
        var RequestJson: JsonObject;
        PackageHeader: Record "SOUDHL Package Header";
        SalesHeader: Record "Sales Header")
    var
        ExpressHelper: Codeunit "SOUDHL Express Helper";
        ProductCode: Code[5];
    begin
        ProductCode := ExpressHelper.MapProductCode(
            Enum::"SOUDHL Express Product"::ExpressWorldwide);

        if RequestJson.Contains('productCode') then
            RequestJson.Replace('productCode', ProductCode);
    end;
}
```

Dieser Subscriber läuft nur für Express. Das JSON darf nicht protokolliert werden.

## Parcel-DE-Request ergänzen

```al
[EventSubscriber(
    ObjectType::Codeunit,
    Codeunit::"SOUDHL API Management",
    'OnBeforeSendParcelDEShipmentRequest',
    '', false, false)]
local procedure BeforeParcelRequest(
    var RequestJson: JsonObject;
    PackageHeader: Record "SOUDHL Package Header";
    SalesHeader: Record "Sales Header")
begin
    if not RequestJson.Contains('profile') then
        exit;
end;
```

Pflichtknoten nicht entfernen und keine Credentials verwalten. Fachliche Header-Änderungen gehören bevorzugt nach `OnBeforeGenerateLabel`.

## Eigene Versandoberfläche verwenden

```al
[EventSubscriber(
    ObjectType::Codeunit,
    Codeunit::"SOUDHL Sales UI",
    'OnBeforeSetPackageSubpageVisible',
    '', false, false)]
local procedure HideStandardPackagePart(
    SalesHeader: Record "Sales Header";
    var IsVisible: Boolean)
begin
    IsVisible := false;
end;

[EventSubscriber(
    ObjectType::Codeunit,
    Codeunit::"SOUDHL Sales UI",
    'OnBeforeSetListActionsVisible',
    '', false, false)]
local procedure HideStandardDhlActions(var IsVisible: Boolean)
begin
    IsVisible := false;
end;
```

Produktiv sollte das Ausblenden von einer eigenen Setup-Option abhängen, damit Administratoren das Standard-DHL-UI bei Bedarf wieder aktivieren können.

## Lookup auf DHL-Boxen

```al
tableextension 50133 "My Sales Header DHL" extends "Sales Header"
{
    fields
    {
        field(50133; "My DHL Box Code"; Code[20])
        {
            Caption = 'DHL Box Code';
            TableRelation = "SOUDHL Box".Code;
        }
    }
}
```

Lookups sind zulässig. Direkte Änderungen an DHL-Boxen aus der Consumer-App sollten vermieden werden.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.solutioo.de/entwicklerdokumentationen-business-central-dhl-connector/dhl-connector-entwicklerdokumentation/integrationsbeispiele.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.