> 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/hermes/entwicklerreferenz.md). # Entwicklerreferenz Technische Referenz zum **Solutioo Hermes API Connector**, Kandidatenversion **1.1.8.5**, Stand 29. Oktober 2026. Stimmen Sie externe Integrationen und den produktiven API-Einsatz vorab mit solutioo ab. ### Erweiterungsmodell und unterstützter Umfang Die App erweitert Business Central um Einrichtung, Sendungen, API-Protokoll und Verkaufsauftragsfunktionen. Dieser Stand bietet keine veröffentlichten AL-Event-Publisher und keine allgemeine Versand-REST-API. Öffentlich sichtbare AL-Prozeduren sind ohne gesonderte Vereinbarung keine stabile Erweiterungsschnittstelle. Die nachfolgende administrative Setup-API dient der kontrollierten Einrichtung. Eine über Versionen garantierte externe Vertragsstabilität wird nicht zugesagt. Hermes-Endpunkte für Labels sind Drittdienste und keine von der BC-Erweiterung angebotenen API-Ressourcen. ### Entwicklungsumgebung, Abhängigkeiten und Versionen | Merkmal | Wert | | ------------------------------ | -------------------------------------- | | App | Solutioo Hermes API Connector | | Publisher | Solutioo | | App-ID | `5a3b9f5e-d2c6-49be-b6a9-1851c5771c8f` | | Kandidatenversion | `1.1.8.5` | | Application / Runtime | `28.0.0.0` / `14.0` | | Target | `Cloud` | | Zusätzliche App-Abhängigkeiten | Keine im Manifest | | Objektbereich | `72243891`–`72243921` | Der Build benötigt keine Hermes-Zugangsdaten. Die Paketkonfiguration erlaubt weder Debugging noch den Download von Quellen oder deren Einbettung in Symbole. Stimmen Sie Zugriff auf Entwicklungsquellen gesondert ab. ### Authentifizierung, Berechtigungen und Datenkontext Die BC-API erfordert einen für den jeweiligen Tenant und die Umgebung gültigen Entra-Bearer-Token sowie administrative Rechte für die Einrichtung. Verwenden Sie ausschließlich den für Ihre Organisation vereinbarten Anmeldeweg. Der App-Berechtigungssatz heißt `SOU Hermes Admin`; Standard- und API-Zugriffsrechte müssen für den konkreten Aufrufer ergänzt werden. Der Mandant wird durch `companies({companyId})` bestimmt. Verwenden Sie explizite Zielparameter. Die Geheimnisspeicherung ist je BC-Mandant und Hermes-Umgebung getrennt; sie verwendet verschlüsselten Isolated Storage mit `DataScope::Company`. Geheimnis-Eingaben sind ausschließlich schreibbar, die Statusfelder melden nur deren Vorhandensein. Die Versandrolle `SOU Hermes User` liest die Einrichtung und Protokolle und bearbeitet Sendungen. Protokolleinträge entstehen über den API-Client mit indirektem Einfügerecht. Diese Rolle verwaltet keine Zugangsdaten. Hermes-OAuth verwendet `/authorization-facade/oauth2/access_token`. Auth-URL, API-URL und Client-ID sind umgebungsabhängig vorgegeben. Aktivieren Sie ausgehende HTTP-Anfragen über die Erweiterungskonfiguration, siehe [Installation und Berechtigungen](/hermes/installation-und-berechtigungen.md). ### Referenz der Events, APIs und Erweiterungspunkte #### Administrative Setup-API | Merkmal | Wert | | --------------------------- | ----------------------------------------------------- | | AL-Page | `72243918 "SOU Hermes Setup API"` | | Publisher / Group / Version | `solutioo` / `hermes` / `v1.0` | | Entity / EntitySet | `setup` / `setups` | | OData-Schlüssel | `SystemId` | | Operationen | GET und PATCH; Einfügen und Löschen sind deaktiviert. | Collection-URL mit ausschließlich exemplarischen Parametern: ``` https://api.businesscentral.dynamics.com/v2.0/{tenantId}/{environment}/api/solutioo/hermes/v1.0/companies({companyId})/setups ``` Einzelressource für PATCH: `setups({setupId})`. Verwenden Sie den von Business Central gelieferten ETag für `If-Match` und prüfen Sie Änderungen vor dem Schreiben. Ein fehlender Singleton wird nur im autorisierten Einrichtungspfad initialisiert; legen Sie keine zusätzlichen Einrichtungen per POST an. | Feld | Verhalten | | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `id` | Schreibgeschützt; System-ID der Einrichtung. | | `environment`, `customerSegment` | Lesbar und änderbar; Hermes-Umgebung und Kundensegment. Verwenden Sie die vom Zielsystem gelieferten Enum-Werte. | | `username`, `grantType`, `userAgent` | Lesbar und änderbar; Kundenbenutzer, vereinbarter Grant und User-Agent. | | `authBaseUrl`, `apiBaseUrl`, `clientId` | Schreibgeschützt; werden zur Umgebung vorgegeben. | | `hasClientSecret`, `hasPassword` | Schreibgeschützt; boolesche Vorhandenseinsanzeigen. | | `clientSecret`, `password` | Ausschließlich schreibbare Eingaben bis je 250 Zeichen; GET- und PATCH-Antworten enthalten `""`. | Eine ausgelassene Geheimnis-Eigenschaft erhält den gespeicherten Wert. Ein ausdrücklich übergebenes `""` löscht ihn. Geheimnis-Eingaben werden nach der Validierung aller Felder für die endgültig gewählte Umgebung gespeichert; ihre Reihenfolge im JSON darf nicht zur Auswahl einer anderen Umgebung führen. Ein Umgebungswechsel passt URLs an und invalidiert den Token-Cache. Die API stellt keinen Token-Test oder Labelaufruf als gebundene Aktion bereit. Nutzen Sie für die Bedienprüfung die dokumentierten UI-Aktionen. ### Vollständige Beispiele Das folgende Minimalbeispiel liest ausschließlich die Setup-ID. Voraussetzungen: Python 3, eingerichtete App, gültiger BC-Token über Ihren vereinbarten Anmeldeweg und ausreichende Einrichtungsrechte. Setzen Sie `BC_TENANT_ID`, `BC_ENVIRONMENT`, `BC_COMPANY_ID` und `BC_ACCESS_TOKEN` über Ihren sicheren lokalen Prozess. Geben Sie Token oder vollständige Antworten nicht in Protokollen aus. ```python import json import os import urllib.parse import urllib.request from uuid import UUID tenant = str(UUID(os.environ['BC_TENANT_ID'])) company = str(UUID(os.environ['BC_COMPANY_ID'])) environment = urllib.parse.quote(os.environ['BC_ENVIRONMENT'], safe='') url = ( f'https://api.businesscentral.dynamics.com/v2.0/{tenant}/{environment}' f'/api/solutioo/hermes/v1.0/companies({company})/setups?$select=id' ) request = urllib.request.Request( url, headers={'Authorization': 'Bearer ' + os.environ['BC_ACCESS_TOKEN']}, ) try: with urllib.request.urlopen(request, timeout=30) as response: rows = json.load(response).get('value', []) except Exception: raise SystemExit('Setup-Abfrage fehlgeschlagen; Zugang und Ziel prüfen.') from None if len(rows) != 1: raise SystemExit('Keine eindeutige Einrichtung gefunden.') print('Einrichtung eindeutig vorhanden') ``` Erwartetes Ergebnis bei erreichbarer App und passenden Rechten: `Einrichtung eindeutig vorhanden`. Das Beispiel ist eine Diagnosevorlage; es ersetzt keinen Integrations- oder Berechtigungsnachweis für Ihre Umgebung. ### Transaktionen, Wiederholungen und Fehlerverhalten Label- und Retourenanforderungen verwenden POST. Bei einer fehlgeschlagenen Labelantwort mit `e058` erfolgen bis zu drei Wiederholungen mit jeweils drei Sekunden Abstand, insgesamt höchstens vier Versuche. Andere Fehler werden über diesen Mechanismus nicht wiederholt. Es besteht keine allgemeine Idempotenzgarantie. Ein nachfolgender AL-Fehler kann lokale Sendungs- und Protokolländerungen zurückrollen. Die externe Hermes-Anfrage kann trotzdem erfolgt sein. Ein fehlender lokaler Datensatz beweist daher nicht, dass kein externer Auftrag angelegt wurde. Klären Sie ungewisse Ergebnisse vor einer Wiederholung anhand vorhandener Referenzen. Retourenantworten aktualisieren denselben Sendungsdatensatz und können dessen gespeichertes Label ersetzen. Bei KA14 setzt der Auftragspfad ein fehlendes Abholdatum auf zwei Tage nach dem aktuellen Tag. Die angezeigte „Pickup Order ID“ wird aus der Retouren-ID oder als Rückfall aus der Shipment-ID befüllt; prüfen Sie die Hermes-Antwort zur fachlichen Zuordnung. ### Zoll- und Routenvalidierung Ab **1.1.8.5** erzeugt die App kein `customsAndTaxes`-Objekt. Der frühere Builder mit Beispielwaren und Ersatz-ZAZ ist entfernt. Zollkennzeichen und nicht unterstützte Länder werden lokal abgewiesen; bekannte Sondergebiete sowie unklare PLZ-Formate in den betroffenen Ländern werden geprüft. Diese Anwendungssperre ist keine vollständige territoriale Zollklassifikation. Die Prüfung gilt vor Versandlabel, Retourenlabel und Shipment-Event. Bei Verkaufsaufträgen erfolgt sie vor dem Sendungsinsert, bei Retourenabholung vor Änderungen am Auftrag. Eine in einer Standalone-Retoure tatsächlich verwendete Setup-Adresse wird entsprechend dem Serializer normalisiert und mitgeprüft. Referenzbasierte Retouren verwenden diese Setup-Adresse nicht. Es gibt keine unterstützte Schnittstelle, um die Zollprüfung zu umgehen. ### Testen und Debuggen Verwenden Sie eine ausdrücklich bestätigte BC-Testumgebung, einen reservierten Testmandanten und **Hermes-Umgebung = Integration**. Die BC-Sandbox allein erzwingt kein Hermes-Testziel. Prüfen Sie mindestens: Einrichtung mit Administratorrolle, lesenden API-Zugriff, Verhalten ausgelassener Geheimnisfelder, Statusanzeigen, Tokenabruf, Standardlabel und die vereinbarten Retourenabläufe. Verwenden Sie für die Versandprüfung eine normale Versandrolle mit den erforderlichen Standardrechten. Behandeln Sie Rechte- und Integrationsergebnisse immer als auf den geprüften Aufrufer und Zielkontext begrenzt. Für Fehlerdiagnosen verwenden Sie bereinigte Meldungstexte, Zeitpunkte, HTTP-Status und erforderliche Referenzen. Debugging des bereitgestellten Pakets ist deaktiviert. Zugangsdaten, Token und rohe Authentifizierungsantworten gehören nicht in Anhänge. ### Kompatibilität, Änderungen und Abkündigungen Die Setup-API trägt die Versionskennung `v1.0`. Stimmen Sie Automatisierungen vor dem Einsatz und bei Versionswechseln mit solutioo ab. **1.1.8.0** migriert bisherige Tabellengeheimnisse, entfernt Altwerte und verwirft Token-Caches. Frühere gemeinsam gespeicherte Vermittler-Secrets müssen je BC-Mandant und Hermes-Umgebung neu provisioniert werden. **1.1.8.5** umfasst die Korrekturen für die erste Anmeldung ohne vorhandenes Token, die OAuth-Headerbehandlung und die unmittelbare Anzeige der Tokenablaufzeit. Der Versandpfad überschreibt keine Auftragsadresse mit Beispieldaten; bei leerer Auftragsklasse wird die konfigurierte Standardklasse verwendet. Weitere Kundenaktionen finden Sie unter [Updates und Änderungen](/hermes/updates-und-anderungen.md). ### Technische FAQ und Support **Ist die Setup-API eine allgemeine Hermes-Versand-API?** Nein. Sie verwaltet die administrative Einrichtung. Eine externe Versand-API ist in diesem Stand nicht als unterstützte Schnittstelle dokumentiert. **Warum lesen sich Geheimnisfelder leer zurück?** Sie sind absichtlich ausschließlich schreibbar. Prüfen Sie `hasClientSecret` und `hasPassword`; protokollieren Sie keine Geheimniswerte. **Warum fehlt ein Protokoll nach einem Fehler?** Lokale Validierung oder Authentifizierung können vor der Protokollierung abbrechen. Außerdem kann ein AL-Fehler lokale Änderungen zurückrollen. Erfassen Sie die sichtbare Fehlermeldung und den Zeitpunkt. Nutzen Sie die [Supportwege](/hermes/support.md). Nennen Sie App- und BC-Version, betroffene API/Objekte, Aufruferrolle, Zeitpunkt und einen bereinigten Fehlerbeleg. --- # 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/hermes/entwicklerreferenz.md?ask=&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.