06. Releases and release notes

API scope and release levels

The release matrix distinguishes between three groups. It determines which interfaces are part of the standard scope, which are only added after project review and which remain internal. The technical term “Partner” in routes and fields such as PartnerId refers to the respective X-ERP business partner, for example a customer. It is not synonymous with the reseller who implements the integration.

Standard scope

Standard features include the login and sessions, item catalog, shopping cart and ordering, and help desk features described in this item. The Matrix technically lists this group as FH-safe. In the item we use the term standard scope.

Technical conditions also apply within this group: customer profile and address data may only be issued to the agreed extent. Helpdesk protocols are only included when the project needs them. PUT /api/Helpdesk requires express permission to process tickets directly. Every writing endpoint is explicitly released before the rights are granted.

Extensions after project release

Additional interfaces may be required if the integration goes beyond the standard scope. The matrix lists it as FH-safe with restrictions. Before they are released, the use case, permissions and disclosed data are checked. They are not part of the standard published Swagger document fh.

• Customer lists and business partner data: GET /api/Partner/GetCustomers and business partner page queries are only possible if the integration is also allowed to see data outside of the currently logged in identity.
• Billing and delivery addresses: The reading queries under /api/PartnerBillingAddress and /api/PartnerDeliveryAddress are only used for required and released address data sets.
• Contact person: The queries under /api/PartnerContactPerson can provide personal contact information and comprehensive lists. The permissible scope of data must be determined.
• Catalog numbers: Queries under /api/PartnerCatalogNumber support the assignment of customer-specific item numbers. Item-related cross-references to other business partners must also be technically approved.
• Bank details: The reading query under /api/PartnerBankAccount concerns sensitive financial master data and requires explicit release.
• Categories and groups: Business partner categories, category names and group hierarchies can reveal internal classifications and are only included when specifically needed.
• Purchase price history: Access to commercial histories is approved separately for technical purposes.
• Passkeys: functions below /api/PartnerPasskey require a coordinated WebAuthn/Passkey contract for the respective project.

The exact routes and conditions of these extensions can be found in FH-Allowlist-Matrix.md. An existing route or a visible controller does not yet represent a release for an external application.

Internal interfaces

Administrative actions, internal token maintenance, maintenance, invitation management, internal helpdesk views, and special ERP output and management functions are not part of the regular external API scope. Also excluded are outdated duplicate interfaces and procedures for changing passwords via URL parameters. This group is marked as Internal only in the matrix and remains outside of the external Swagger document.

The matrix is a release recommendation, not a security guarantee. What remains crucial is correct authentication, WebApi rights limited to requirements, a permissible amount of data and the expressly intended business process.

Choosing Swagger and OpenAPI correctly

The updated documentation distinguishes two runtime swagger documents:

• `fh`: The curated standard scope for external integrations. It maps the APIs selected by default.
• `v1`: The broader internal development API. It also contains internal functions and is not a blanket release for external applications.

For integration, use the document fh, as long as it is provided in the version and environment you are using. You will receive the specific address from the operator. According to the current documentation, the static file openapi.partner-safe.yaml describes the same standard scope. Extensions with restrictions are in the matrix and are deliberately not part of this standard contract.

The release matrix is the basis for deciding on the permissible scope; Swagger and OpenAPI provide the technical description. An entry in Swagger does not replace the granting of rights or the required project approval.

Comparison with the server code from September 18, 2026

The documentation provided was compared to the local controllers and login configuration. The following differences are relevant for developers:

• Technical login: WebApiUserController provides POST /api/WebApiUser/WebApiLogin. It is missing from the original fh allowlist and static OpenAPI file; This help explains it separately as an installation-dependent bootstrap.
• Order result: The endpoint reference describes a new document ID as data. In the checked success case, WebshopUserCartController returns the constant value 1 instead. Do not derive a follow-up call to a supposed document 1.
• Shopping cart: The checked checkout already removes its positions on the server side. An additional ClearCart is not required in this process.
• Addresses: The verified checkout sets the billing and delivery country to DE. An assignment of the street field is not visible in the tested method section. The complete transfer of the address must therefore not be assumed without checking; based on the target version and generated test documents.
• Helpdesk model: The static contract does not describe the full update payload in enough detail for a standalone writing project. Have the model that matches the target version added.
• Swagger availability: Program.cs only activates Swagger in the development environment. /swagger/fh/swagger.json and /swagger/v1/swagger.json are configured there. The documentation URL of a production installation must be coordinated with the operator.

These differences are open acceptance points for the respective server version, not changes made to the ERP server in this work. The download package particularly indicates the different order results.

What needs to be determined before the project begins

Base address, company database, API account, approved business partners, rights and server version are determined by the operator. For productive orders, secure document allocation, complete address transfer and handling of unclear results must also be confirmed. The specific data model must be available for helpdesk write access.

Versions and documents

Package version v1 is a documentation status, not a long-term compatibility guarantee. The decisive factors are the released target version, its endpoint contracts and the technical acceptance. Sources of this help are README.md, FH-Allowlist-Matrix.md, Authentication-and-Conventions.md, Endpoint-Reference.md, openapi.partner-safe.yaml as well as the tested login and web shop controllers.

The OpenAPI file and sample templates are part of the developer package to be provided separately.