CX-0074 Business Partner Data GATE API v2.0.0
FOR WHOM IS THE STANDARD DESIGNED
This document is mainly targeted to technical individuals involved in integrating and developing against this API, as well as business individuals who are involved in compliance process of this API.
COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD
Version | Publishing Date | Author | Description of Change |
---|---|---|---|
1.0.0 | 2023-09-26 | Initial version by Catena-X Association | |
1.1.0 | 2024-01-10 | Small additions to the terminology chapters: added roles “supplier” & “customer”; added ISO 6709 and WGS 84 for geographic coordinates; added generic business partner outlook; moved attribute “sharing process started at” from specific business partner entities to the sharing state entry (API was correct); linked OpenAPI document in release branch instead of main | |
2.0.0 | 2024-03-22 | Added business partner description and removed detailed legal entity, site and address descriptions from terminology chapter; removed business partner type from changelog entry and sharing state entry descriptions; added business partner endpoints and removed legal entity, site and address endpoints; added “house number supplement” attribute; added “is own company data” attribute to claim ownership; switched to the new document structure |
ABSTRACT
The Business Partner Data Management (BPDM) is a distributed service-based system, composed of a set of dedicated services, that simultaneously serve multiple stakeholders. It is based on a central data pool of business partners, which is consistent with the overall design principles of Catena-X. The main target is to create business partner data records (such as customer/supplier) with a high quality and currentness, to provide other processes with these data. This results in less rework and adjustment due to better master data quality which ultimately leads to an overall cost reduction for participating companies. Additionally, Value Added Services shall be offered to enrich those business partner data sets even further and give additional information or warnings about the business partners. Getting a 360° view on your business partners also helps with reducing costs and achieving process excellence because better decisions can be made.
The Business Partner Gate allows any Catena-X member to share own business partner data as well as business partner data of its suppliers and customers with the Catena-X network so that cleansed and enriched business partner data records, so-called Golden Records, can be created and made available. It is a main component of the architecture framework at Catena-X, as it enables the Catena-X members to leverage accurate, complete, and consistent business partner data for Catena-X applications and shared services.
The Business Partner Gate can be accessed via the standardized API described in this standard.
1. INTRODUCTION
1.1 AUDIENCE & SCOPE
This section is non-normative
This standard is relevant for the following audience:
- Core Service Provider
- Onboarding Service Provider
- Data Provider and Consumer
This document focuses on the Business Partner Gate API (short: Gate API) that is part of the Business Partner Data Management (BPDM) described on the BPDM Catena-X Website. It is relevant for core service providers who want to provide services for uploading and downloading business partner master data records with the aim of cleansing and enriching them and thus create a high-quality business partner data record (Golden Record), which is identified by the business partner number (BPN). It is also relevant for onboarding service providers, business application providers as well as data providers and consumers who want to use such services.
Not in scope are the structure and logic of the business partner number itself and the mechanism on how the business partner number is issued. There is a separate standard for this: CX-0010 Business Partner Number.
Not in scope is the overall Business Partner Pool with all Golden Records within Catena-X and the way of how the Golden Records can be retrieved. There is a separate standard for this: CX-0012 Business Partner Pool API.
Not in scope are the requirements of cleansing and enriching the business partner data records with the aim to create a Golden Record. There is a separate standard for this: CX-0076 Golden Record End to End Requirement Standard.
You can find the other standards in the standard library of Catena-X: https://catena-x.net/en/standard-library
1.2 CONTEXT AND ARCHITECTURE FIRE
This section is non-normative
The Gate API is a crucial core component in Catena-X and its platform capability BPDM because it contributes to the following functions:
- Data Consistency: The Gate API allows that data related to business partners can be collected from multiple sources and can be sent through the sharing process to correct, enrich and validate the data. This ultimately enables BPDM to create accurate, complete, and consistent business partner data records (Golden Records). This helps to reduce the risk of errors and inconsistencies in business partner data.
- Data Sovereignty: The Gate API allows to upload and download business partner data in a data sovereign way, because each Catena-X member has its own area of business partner data in BPDM, where private data (like customer / supplier relationships) is only visible to the Catena-X member.
- Data Governance: The Gate API is the basis for a data governance framework and helps to enforce data quality standards, such as data completeness, accuracy, and consistency. It allows to compare the uploaded business partner data records against the corrected and enriched ones and provides the sharing member with a proposal for taking over the changes into the local MDM systems. This helps to ensure that business partner data is of high quality and can be trusted for use in various business processes.
- Interoperability: The Gate API provides an interoperable and standardized way of uploading and downloading business partner data, ensuring both Core Service Provider interchangeability and streamlined data accessibility for all consumers of the API.
There is a reference implementation for the Gate API on GitHub. It is part of a Spring Boot Kotlin open-source software project under the hood of the Eclipse Foundation and follows the Apache 2.0 licenses.
For the complete and up-to-date API setup refer to the following website: https://github.com/eclipse-tractusx/bpdm
For an architecture overview refer to the ARC42 documentation: https://github.com/eclipse-tractusx/bpdm/tree/release/5.0.x/docs/arc42
To use the Gate API in the BPDM use case apart from this standard, the following other standards should be considered by all participants for which this standard is relevant:
- CX - 0018 Eclipse Data Space Connector (EDC)
1.3 CONFORMANCE AND PROOF OF CONFORMITY
This section is non-normative
If sections are marked as non-normative, all authoring guidelines, diagrams, examples, and notes in these sections are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
All participants and their solutions will need to prove, that they are conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs).
When implementing the API defined in this standard, proof of conformity must be provided by the following deliverables:
- An OpenAPI specification defining the relevant resources for this standard
- Examples of data assets
1.4 EXAMPLES
Intentionally left blank.
1.5 TERMINOLOGY
This section is non-normative
1.5.1 GENERAL
Golden Record: Golden Record defines a business partner data record which successfully passed a set of predefined quality rules. These rules qualified the data record into a harmonized, standardized, and semantically unified data structure which is defined by Catena-X. The Golden Record status is a prerequisite for each BP data record to receive a valid BPN.
Sharing Member: A sharing member is a Catena-X member who shares the business partner data of his own business environment.
Company Data: Company data are business partner data that represent the organizational structures of the sharing member.
1.5.2 Data Model
This chapter explains the data model1 from a conceptual / terminology point of view. It does not include technical details of the API data model, such as:
- differences in response and request
- differences in data stages (like input or output)
- attributes for pagination
- singular query parameters, which are not already attributes of the entities
Note that cardinalities always refer to the entity state as required output of the sharing process. In general, cardinalities of relations and attributes are not to be enforced while uploading business partners, except for the external ID.
1.5.2.1 BUSINESS PARTNER
In general, a business partner is any entity (such as a customer, a supplier, an employee, or a service provider) that does business with another entity.
In Catena-X, a business partner is an organization (such as an enterprise or company, university, association, etc., and not a natural person) or one of its substructures that acts as unique partner within the automotive supply chain - either in the role of a direct participant, or a consultant, or a non-production-material (NPM) supplier.
The business partner entity in the Gate API provides a merged view on the following entity combinations, that the BPDM uses to represent an organization or one of its substructures relevant for the automotive supply chain (see detailed definitions).:
- a legal entity and its legal address
- a legal entity and an additional address, which is not its legal address
- a legal entity, one of its sites, and the main address of this site, which is not the legal address
- a legal entity, one of its sites and the legal address of the legal entity, which additionally is the main address of that site
- a legal entity, one of its sites and an additional address of that site, which is neither the legal address of the legal entity nor the main address of that site
In all combinations, a business partner has exactly one legal entity and one address assigned. It may additionally have a site assigned if the assigned address belongs to the site / the site is known to BPDM. Note that for the assignment of the entities the respective BPNL, BPNS or BPNA (from the Business Partner Pool) are used. The BPN assignment and the business partner address type determine the entity combinations, on which the business partner entity provides a merged view.
The combinations can be visualized in the following table (all other combinations are invalid as output of the sharing process):
Entity Combination | Legal Entity assigned (BPNL) | Site assigned(BPNS) | Address assigned(BPNA) | Business Partner Address Type |
---|---|---|---|---|
1. | x | x | Legal Address | |
2. | x | x | Additional Address | |
3. | x | x | x | Site Main Address |
4. | x | x | x | Legal and Site Main Address |
5. | x | x | x | Additional Address |
These are the attributes of the business partner:
Attribute | Description | (Data) Type / Code List / Enumeration |
---|---|---|
External ID | The identifier which uniquely identifies (in the internal system landscape of the sharing member) the business partner. | String |
Name Parts | The list of name parts of the business partner to accommodate the different number of name fields in different systems. | List of String |
States | The list of (temporary) states of the business partner. | List of Business Partner State |
Identifiers | The list of identifiers of the business partner. | List of Business Partner Identifier |
Roles | One or more of the roles, the business partner assumes with respect to the sharing member: Supplier, Customer. | List of Enum |
Is Own Company Data | Indicates whether the sharing member claims (in the initial upload) the business partner to belong to the company data of the sharing member.2 | Boolean |
Created At | The date and time when the business partner data record has been created. | Date / Time |
Updated At | The date and time when the business partner data record has been last updated. | Date / Time |
Legal Entity | The legal entity, on which the business partner provides a view. | Legal Entity Representation |
Site | The site, on which the business partner provides a view. | Site Representation |
Address | The address, on which the business partner provides a view. | Address Representation |
1.5.2.1.1 BUSINESS PARTNER IDENTIFIER
A business partner identifier (uniquely) identifies the business partner, such as the German Handelsregisternummer, a VAT number, etc.
Attribute | Description | (Data) Type / Code List / Enumeration |
---|---|---|
Value | The value of the identifier like “DE123465789” | String |
Type | The type of the identifier. | Identifier Type |
Issuing Body | The name of the official register, where the identifier is registered. For example, a Handelsregisternummer in Germany is only valid with its corresponding Registergericht and Registerart. | String |
1.5.2.1.2 BUSINESS PARTNER STATE
A business partner state indicates if the business partner is active or inactive3. This does not describe the relation between a sharing member and a business partner and whether they have active business, but it describes whether the business partner is still operating.
Attribute | Description | (Data) Type / Code List / Enumeration |
---|---|---|
Valid From | The date and time from which the state is valid. | Date / Time |
Valid To | The date and time until the state is valid. | Date / Time |
Type | One of the state types: active, inactive. | Enum |
1.5.2.1.3 LEGAL ENTITY REPRESENTATION
A legal entity representation adds context information to the legal entity, on which the business partner provides a view. Additionally, it contains some of the information from the assigned legal entity.
Attribute | Description | (Data) Type / Code List / Enumeration |
---|---|---|
Legal Entity BPN | The BPNL of the legal entity, on which the business partner provides a view. | String |
Legal Name | The name of the legal entity, on which the business partner provides a view, according to official registers. | String |
Short Name | The abbreviated name of the legal entity, on which the business partner provides a view. | String |
Legal Form | The legal form of the legal entity, on which the business partner provides a view. | Legal Form |
Classifications | The list of classifications of the business partner, such as a specific industry. | List of Classification |
1.5.2.1.4 SITE REPRESENTATION
A legal entity representation adds context information to the site, on which the business partner provides a view. Additionally, it contains some of the information from the assigned site.
Attribute | Description | (Data) Type / Code List / Enumeration |
---|---|---|
Site BPN | The BPNS of the site, on which the business partner provides a view. | String |
Name | The name of the site, on which the business partner provides a view. This is not according to official registers but according to the name the owner chooses. | String |