06. Freigaben und Versionshinweise

API-Umfang und Freigabestufen

Die Freigabematrix unterscheidet drei Gruppen. Sie legt fest, welche Schnittstellen zum Standardumfang gehören, welche nur nach Projektprüfung hinzukommen und welche intern bleiben. Die technische Bezeichnung „Partner“ in Routen und Feldern wie PartnerId bezeichnet dabei den jeweiligen X-ERP-Geschäftspartner, beispielsweise einen Kunden. Sie ist nicht gleichbedeutend mit dem Fachhändler, der die Integration umsetzt.

Standardumfang

Zum Standardumfang gehören die in diesem Artikel beschriebenen Funktionen für Anmeldung und Sitzungen, Artikelkatalog, Warenkorb und Bestellung sowie Helpdesk. Die Matrix führt diese Gruppe technisch als FH-safe. Im Artikel verwenden wir dafür den Begriff Standardumfang.

Auch innerhalb dieser Gruppe gelten fachliche Bedingungen: Kundenprofil- und Adressdaten dürfen nur im vereinbarten Umfang ausgegeben werden. Helpdesk-Protokolle werden nur eingebunden, wenn das Projekt sie benötigt. PUT /api/Helpdesk setzt die ausdrückliche Erlaubnis zur direkten Ticketbearbeitung voraus. Jeder schreibende Endpunkt wird vor Vergabe der Rechte ausdrücklich freigegeben.

Erweiterungen nach Projektfreigabe

Zusätzliche Schnittstellen können erforderlich sein, wenn die Integration über den Standardumfang hinausgeht. Die Matrix führt sie als FH-safe with restrictions. Vor ihrer Freigabe werden Anwendungsfall, Berechtigungen und offengelegte Daten geprüft. Sie gehören nicht zum standardmäßig veröffentlichten Swagger-Dokument fh.

• Kundenlisten und Geschäftspartnerdaten: GET /api/Partner/GetCustomers sowie die Geschäftspartner-Seitenabfragen kommen nur infrage, wenn die Integration auch Daten außerhalb der aktuell angemeldeten Identität sehen darf.
• Rechnungs- und Lieferadressen: Die Leseabfragen unter /api/PartnerBillingAddress und /api/PartnerDeliveryAddress werden nur für benötigte und freigegebene Adressdatensätze eingesetzt.
• Ansprechpartner: Die Abfragen unter /api/PartnerContactPerson können personenbezogene Kontaktdaten und umfassende Listen liefern. Der zulässige Datenumfang muss feststehen.
• Katalognummern: Abfragen unter /api/PartnerCatalogNumber unterstützen die Zuordnung kundenspezifischer Artikelnummern. Auch artikelbezogene Querverweise auf andere Geschäftspartner müssen fachlich freigegeben sein.
• Bankverbindungen: Die Leseabfrage unter /api/PartnerBankAccount betrifft sensible finanzielle Stammdaten und verlangt eine ausdrückliche Freigabe.
• Kategorien und Gruppen: Geschäftspartner-Kategorien, Kategorienamen und Gruppenhierarchien können interne Klassifikationen offenlegen und werden nur bei konkretem Bedarf eingebunden.
• Einkaufspreishistorie: Der Zugriff auf kaufmännische Historien wird gesondert fachlich freigegeben.
• Passkeys: Funktionen unter /api/PartnerPasskey setzen einen abgestimmten WebAuthn-/Passkey-Vertrag für das jeweilige Projekt voraus.

Die genauen Routen und Bedingungen dieser Erweiterungen stehen in FH-Allowlist-Matrix.md. Eine vorhandene Route oder ein sichtbarer Controller stellt noch keine Freigabe für eine externe Anwendung dar.

Interne Schnittstellen

Administrative Aktionen, interne Tokenpflege, Wartung, Einladungsverwaltung, interne Helpdesk-Ansichten sowie spezielle ERP-Ausgabe- und Verwaltungsfunktionen gehören nicht zum regulären externen API-Umfang. Ebenso ausgeschlossen sind veraltete doppelte Schnittstellen und Verfahren zur Passwortänderung über URL-Parameter. Diese Gruppe ist in der Matrix als Internal only gekennzeichnet und bleibt außerhalb des externen Swagger-Dokuments.

Die Matrix ist eine Freigabeempfehlung, keine Sicherheitsgarantie. Entscheidend bleiben eine korrekte Anmeldung, auf den Bedarf begrenzte WebApi-Rechte, ein zulässiger Datenumfang und der ausdrücklich vorgesehene Geschäftsprozess.

Swagger und OpenAPI richtig auswählen

Die aktualisierte Dokumentation unterscheidet zwei Laufzeit-Swagger-Dokumente:

• `fh`: Der kuratierte Standardumfang für externe Integrationen. Er bildet die standardmäßig ausgewählten APIs ab.
• `v1`: Die breitere interne Entwicklungs-API. Sie enthält zusätzlich interne Funktionen und ist keine pauschale Freigabe für externe Anwendungen.

Für eine Integration verwenden Sie das Dokument fh, soweit es in Ihrer eingesetzten Version und Umgebung bereitgestellt wird. Die konkrete Adresse erhalten Sie vom Betreiber. Die statische Datei openapi.partner-safe.yaml beschreibt laut aktuellem Dokumentationsstand denselben Standardumfang. Erweiterungen mit Einschränkungen stehen in der Matrix und sind bewusst nicht Bestandteil dieses Standardvertrags.

Die Freigabematrix ist die Entscheidungsgrundlage für den zulässigen Umfang; Swagger und OpenAPI liefern die technische Beschreibung. Ein Eintrag in Swagger ersetzt weder die Rechtevergabe noch eine erforderliche Projektfreigabe.

Abgleich mit dem Servercode vom 18.09.2026

Die bereitgestellten Unterlagen wurden mit den lokalen Controllern und der Anmeldekonfiguration verglichen. Dabei sind folgende Unterschiede für Entwickler relevant:

• Technischer Login: WebApiUserController stellt POST /api/WebApiUser/WebApiLogin bereit. Er fehlt in der ursprünglichen fh-Allowlist und statischen OpenAPI-Datei; die vorliegende Hilfe erklärt ihn separat als installationsabhängigen Bootstrap.
• Bestellergebnis: Die Endpoint-Reference beschreibt eine neue Beleg-ID als data. WebshopUserCartController gibt im geprüften Erfolgsfall stattdessen den konstanten Wert 1 zurück. Keinen Folgeaufruf auf einen vermeintlichen Beleg 1 ableiten.
• Warenkorb: Der geprüfte Checkout entfernt seine Positionen bereits serverseitig. Ein zusätzliches ClearCart ist in diesem Ablauf nicht erforderlich.
• Adressen: Der geprüfte Checkout setzt Rechnungs- und Lieferland fest auf DE. Eine Zuweisung des Street-Felds ist im geprüften Methodenabschnitt nicht erkennbar. Die vollständige Adressübernahme darf deshalb nicht ungeprüft vorausgesetzt werden; anhand der Zielversion und erzeugter Testbelege klären.
• Helpdesk-Modell: Der statische Vertrag beschreibt den vollständigen Update-Payload nicht detailliert genug für ein eigenständiges Schreibprojekt. Das zur Zielversion passende Modell ergänzen lassen.
• Swagger-Verfügbarkeit: Program.cs aktiviert Swagger nur in der Entwicklungsumgebung. Dort sind /swagger/fh/swagger.json und /swagger/v1/swagger.json konfiguriert. Die Dokumentations-URL einer Produktionsinstallation muss mit dem Betreiber abgestimmt werden.

Diese Unterschiede sind offene Abnahmepunkte für die jeweilige Serverversion, keine in dieser Arbeit vorgenommenen Änderungen am ERP-Server. Das Downloadpaket kennzeichnet insbesondere das abweichende Bestellergebnis.

Was vor Projektbeginn feststehen muss

Basisadresse, Firmendatenbank, API-Konto, freigegebene Geschäftspartner, Rechte und Serverversion werden vom Betreiber festgelegt. Für produktive Bestellungen sind zusätzlich die sichere Belegzuordnung, vollständige Adressübernahme und Behandlung unklarer Ergebnisse zu bestätigen. Für Helpdesk-Schreibzugriffe muss das konkrete Datenmodell vorliegen.

Versionen und Unterlagen

Die Paketversion v1 ist ein Dokumentationsstand, keine langfristige Kompatibilitätsgarantie. Maßgeblich sind die freigegebene Zielversion, ihre Endpunktverträge und die fachliche Abnahme. Quellen dieser Hilfe sind README.md, FH-Allowlist-Matrix.md, Authentication-and-Conventions.md, Endpoint-Reference.md, openapi.partner-safe.yaml sowie die geprüften Login- und Webshop-Controller.

Die OpenAPI-Datei und Beispielvorlagen gehören zum separat bereitzustellenden Entwicklerpaket.