Externe REST-API aus Business Central mit AL HttpClient aufrufen

Grundlagen-Tutorial / Entwicklerjournal

Schritt für Schritt von der HTTP-Anfrage bis zur JSON-Verarbeitung: AL HttpClient, Header, Statuscodes, Fehlerbehandlung und sichere Integration.

1. Was macht HttpClient in Business Central?

Mit dem AL-Datentyp HttpClient kann eine Business-Central-Erweiterung einen Webdienst aufrufen. Der Webdienst erhält eine HTTP-Anfrage und liefert eine Antwort mit Statuscode und optionalem JSON zurück. Das ist nützlich für Versanddienste, Dokumentenmanagement oder eigene .NET-APIs. Ein HTTP-Request ersetzt keine fachliche Buchungslogik.

2. Voraussetzungen

Du benötigst eine Business-Central-Sandbox, eine AL-Extension und einen erreichbaren HTTPS-Test-Endpunkt. Aktiviere in den Erweiterungseinstellungen bei der betreffenden Extension die Option Allow HttpClient Requests. Prüfe Firewall, DNS und Zielserver; die Test-URL muss für die Serverumgebung erreichbar sein.

3. Ersten GET-Aufruf schreiben

Der folgende AL-Code zeigt einen Leseaufruf mit HttpClient, HttpResponseMessage und JSON. Die Beispieladresse ist ein Platzhalter und muss durch eine echte Test-API ersetzt werden. Prüfe zuerst den Rückgabewert des HTTP-Aufrufs, anschließend den Statuscode.

codeunit 50130 "External API Demo"
{
    procedure GetProductName(): Text
    var
        Client: HttpClient;
        Response: HttpResponseMessage;
        Body: Text;
        Root: JsonObject;
        NameToken: JsonToken;
    begin
        if not Client.Get('https://example.com/api/products/1', Response) then
            Error('The HTTP request could not be sent.');
        if not Response.IsSuccessStatusCode() then
            Error('API returned HTTP %1.', Response.HttpStatusCode());
        Response.Content().ReadAs(Body);
        if not Root.ReadFrom(Body) then
            Error('Invalid JSON response.');
        if not Root.Get('name', NameToken) then
            Error('Name is missing.');
        exit(NameToken.AsValue().AsText());
    end;
}

4. HTTP-Statuscodes sinnvoll auswerten

200 bedeutet typischerweise, dass die Antwort erfolgreich war. 400/422 weist auf fehlerhafte Eingabedaten hin, 401 auf ungültige Authentifizierung, 403 auf fehlende Rechte, 404 auf eine nicht gefundene Ressource und 429 auf Drosselung. Ein 500- oder 503-Fehler kann vorübergehend sein. Ein Timeout bedeutet nicht sicher, dass das Zielsystem nichts verarbeitet hat.

5. JSON korrekt lesen

Verwende JsonObject und JsonToken statt JSON als Zeichenfolge mit Suchmustern zu zerlegen. Prüfe, ob die erwartete Eigenschaft existiert und den richtigen Typ hat. Ein Feld kann fehlen, null sein oder als String statt Zahl geliefert werden. Ein erfolgreiches HTTP-Ergebnis garantiert kein passendes JSON-Schema.

6. POST und Content-Type

Zum Anlegen oder Übergeben von Daten benötigt ein POST gewöhnlich einen JSON-Body mit Content-Type application/json. Erzeuge den Inhalt über JsonObject und HttpContent. Achte auf den konkreten API-Vertrag, mögliche Idempotenzschlüssel und eine eindeutige fachliche Vorgangs-ID.

7. Authentifizierung

Produktive Endpunkte benötigen häufig OAuth2 über Microsoft Entra ID. Das Access Token muss für die richtige Ziel-API ausgestellt sein. Zugangsdaten gehören nicht als Konstante in AL-Code oder in Logs. Verwende geeignete sichere Speicherung und Tokenverwaltung gemäß der eingesetzten BC-Version.

8. Was passiert bei Fehlern?

Ein Hintergrundprozess sollte Transportfehler und fachliche Ablehnungen getrennt protokollieren. Verwende Correlation IDs, begrenzte Retries und eine Statusverwaltung. Bei 429 respektiere Retry-After, sofern vorhanden; bei 400 muss häufig die Eingabe korrigiert werden. Wiederholte POST-Anfragen dürfen nicht versehentlich doppelte Geschäftsobjekte erzeugen.

9. Testmatrix

Teste gültiges JSON, fehlende Eigenschaften, ungültige Zugangsdaten, 404, 429, Timeout, leere Antwort und einen API-Ausfall. Wiederhole denselben fachlichen Vorgang und überprüfe, ob keine Duplikate entstehen. Verwende Testdaten ohne Kundeninformationen.

10. Lernpfad

Der nächste Schritt ist eine sichere Azure Function als API-Ziel, danach die asynchrone Verarbeitung über eine Queue. Bei einer Business-Central-Standard-API ist zusätzlich zu prüfen, ob eine eigene Schnittstelle überhaupt nötig ist.

Official documentation / Dokumentation

• Business Central HttpClient
• AL JsonObject