> 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/codeunit-referenz/72242952-soudhl-api-management.md).

# 72242952 SOUDHL API Management

## Verantwortung

Zentrale Transport- und Label-Codeunit für Parcel DE und MyDHL Express. Sie kapselt Authentifizierung, Request-Aufbau, HTTP, Response-Parsing, Persistenz, Labeldownload und PDF-Vorschau.

**Wichtig:** Technisch öffentliche Hilfsmethoden sind nicht automatisch unterstützte Partner-APIs. Externe Apps sollen die High-Level-Methoden und Events verwenden.

## Unterstützte High-Level-API

### `IsExpress(): Boolean`

Liest den ersten Konfigurationsdatensatz und liefert, ob Express aktiv ist. Keine Schreibwirkung.

### `GenerateLabel(PackageHeader: Record "SOUDHL Package Header"; var ExtraMessage: Text): Boolean`

Hauptentry für beide Services. Prüft Service, erzeugt und speichert das Label, committet den Labelerfolg und stößt danach optional die Kartonbestandsbuchung an. `ExtraMessage` enthält fachliche Fehler oder Inventurwarnungen.

### `GetRate(ReceiverCountry: Code[10]; ReceiverPostalCode: Text; ReceiverCity: Text; WeightKg: Decimal; LengthCm: Decimal; WidthCm: Decimal; HeightCm: Decimal; ProductCode: Code[5]; var Price: Decimal; var Currency: Text; var ExtraMessage: Text): Boolean`

Live-Preisabfrage für Express. Keine Tabellenwrites. Für Parcel DE wird `false` geliefert.

### `DownloadLabel(PackageHeader: Record "SOUDHL Package Header")`

Lädt das gespeicherte Label im `Print Format` herunter. Meldung statt Fehler, wenn kein Blob vorhanden ist.

### `DownloadCustomsDoc(PackageHeader: Record "SOUDHL Package Header")`

Lädt das gespeicherte CN23-/Customs-Dokument herunter.

### Integration Event

```al
[IntegrationEvent(false, false)]
procedure OnBeforeSendShipmentRequest(
    var RequestJson: JsonObject;
    PackageHeader: Record "SOUDHL Package Header";
    SalesHeader: Record "Sales Header")
```

Wird ausschließlich im Express-Labelpfad nach vollständigem Payload-Aufbau und vor der Serialisierung ausgelöst.

## Technisch öffentlich, aber kein stabiler Partnervertrag

### `BaseUrl(): Text`

Ermittelt Express-Live- oder Test-URL. Endpunktdetails bleiben Implementierung der App.

### `GenerateToken(var Token: Text): Boolean`

Gemeinsamer Authentifizierungstest. Wird vom Setup verwendet. Consumer-Apps sollen weder Token beziehen noch speichern.

### `CallPostAPI(ApiUrl: Text; RequestJson: Text; var ResponseText: Text; var ExtraMessage: Text): Boolean`

Low-Level-HTTP-POST. Umgeht fachliche Invarianten und kann sich mit DHL-Versionen ändern.

### `GetErrorDetail(APIResponseText: Text; var ErrorMessage: Text)`

Dispatcht auf Parcel- oder Express-Fehlerparser.

### `TryGetByProduct(Product: Enum SOUDHLProducts; var Map: Record "SOU DHL Billing Map"): Boolean`

Sucht die erste gültige Billing-Map-Zeile des Produkts.

### `ConvertPdfLabelToJpgAndStore(var PackageHeader: Record "SOUDHL Package Header"; var ExtraMessage: Text): Boolean`

Sendet ein PDF an den konfigurierten Konvertierungsdienst und speichert die Media-Vorschau. Wird intern und vom Labels Report genutzt.

## Lokale Parcel-DE-Methoden

* `GenerateTokenParcelDE`: OAuth-Zugriffstoken
* `CallPostAPIParcelDE`: Bearer-POST
* `GenerateLabelParcelDE`: Request, Call und Persistenz
* `GetErrorDetailParcelDE`: `validationMessages`
* `ParcelClientId` / `ParcelClientSecret`: Secret-Auflösung
* `ResolveParcelCountryCode`: Alpha-3-Land
* `ResolveParcelBillingNumber`: EKP + Produkt + Service

## Lokale Express-Methoden

* `GenerateTokenExpress`: Basic-Auth-Material
* `CallPostAPIExpress`: Headers und HTTP
* `GenerateLabelExpress`: Shipment-Orchestrierung
* `ParseShipmentResponse`: Tracking und Label
* `BuildShipperObject`, `BuildReceiverObject`, `BuildPackageObject`: Payload-Teile
* `BuildExportDeclaration`: Exportpositionen aus Package Lines
* `AddAccount`, `AddNotification`: Arrays
* `WeightInKg`, `NetWeightKg`, `DimensionInCm`: Normalisierung
* `IncotermOrDefault`, `PlannedShippingDateTime`, `NewMessageReference`: Defaults
* `ParseRateResponse`, `BuildRateAddress`, `GetErrorDetailExpress`: Rate und Fehler

## Gemeinsame interne Methoden

`ResolveAzureUrl` und `ResolveAzureKey` lösen den PDF-Konvertierungsdienst auf. Konkrete Secret-Werte sind kein Dokumentationsbestandteil.

## Abhängigkeiten

Configuration, Box, Package Header/Line, Billing Number/Map, Sales Header/Line, Country/Region; Secret Mgt, Recipient Mgt, Customs Mgt, Packing Mgt, Express Helper, Box Inventory Mgt und Installation.

## Seiteneffekte

* Empfänger-Snapshot
* Tracking auf Quellaufträgen
* Label-/Customs-Blobs und Media
* Uploadstatus und Datum
* expliziter Commit nach Labelerfolg
* optionale Inventurbuchung in separater Transaktion

## Fehler und Grenzen

* `FindFirst()` erwartet einen Setupdatensatz.
* Parcel kann bei fehlendem Land oder Billing hart abbrechen.
* Express-Rate nimmt den ersten Produktpreis.
* Das Request-Event existiert nur für Express.
* Labeldaten enthalten personenbezogene Informationen und dürfen nicht unkontrolliert geloggt 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.solutioo.de/entwicklerdokumentationen-business-central-dhl-connector/dhl-connector-entwicklerdokumentation/codeunit-referenz/72242952-soudhl-api-management.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.