Skip to main content
Release: CX-Saturn (Preview)

CX-0074 Business Partner Gate API v4.1.1

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.

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 and use cases. It is based on a central data pool of business partners, which is operated under data space governance and underlies interoperability through standardization. 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 data space participant to share own business partner data as well as business partner data of its suppliers and customers with the data space 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, as it enables the data space participants to leverage accurate, complete, and consistent business partner data for data space 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) use case described on the BPDM 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 3.0.0.

Not in scope is the overall Business Partner Data Pool with all Golden Records within the data space and the way of how the Golden Records can be retrieved. There is a separate standard for this: CX-0012 Business Partner Data Pool API 5.1.0.

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 Requirements Standard 1.5.0.

You can find the other standards in the standard library.

1.2 CONTEXT AND ARCHITECTURE FIT

This section is non-normative

The Gate API is a crucial core component for the data space, the Golden Record Service as Core Service B and the BPDM use case because it contributes to the following functions:

  1. 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.
  2. Data Sovereignty: The Gate API allows to upload and download business partner data in a data sovereign way, because each Sharing Member has its own area of business partner data in BPDM, where private data (like customer / supplier relationships) is only visible to the data owner.
  3. 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.
  4. 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 Business Partner Gate API (7.1.x) 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 BPDM setup refer to the Eclipse Tractus-X BPDM GitHub repository (7.1.x).

For an architecture overview refer to the BPDM ARC42 documentation (7.1.x).

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-0010 Business Partner Number 3.0.0
  • CX-0012 Business Partner Data Pool API 5.1.0
  • CX-0018 Dataspace Connectivity 4.1.0

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

The following examples show business partners which are potentially shared using this API.

1.4.1 EXAMPLE 1

A business partner having assigned a legal entity and its legal address.

Dr. Ing. h.c. F. Porsche Aktiengesellschaft, Porscheplatz 1, 70435 Stuttgart, Deutschland

Legal Address

1.4.2 EXAMPLE 2

A business partner having assigned a legal entity and one of its additional addresses.

Dr. Ing. h.c. F. Porsche Aktiengesellschaft, Schwieberdinger Str. 130, 70435 Stuttgart, Deutschland

Additional Address without Site

1.4.3 EXAMPLE 3

A business partner having assigned a legal entity, a site and its main address1, which is not the legal address.

Dr. Ing. h.c. F. Porsche Aktiengesellschaft, Porsche Zuffenhausen, Werk 2, Hauptpforte, Porschestraße 42, 70435 Stuttgart, Deutschland

Site Main Address

1.4.4 EXAMPLE 4

A business partner having assigned a legal entity, a site and its main address1, which is also the legal address.

Schaeffler Group USA Inc. Fort Mill 1, 308 Springhill Farm Rd, Fort Mill, SC 29715, USA

Legal and Site Main Address

1.4.5 EXAMPLE 5

A business partner having assigned a legal entity, a site and one of its addresses, which is neither the legal address nor the main address1 of that site.

Dr. Ing. h.c. F. Porsche Aktiengesellschaft, Porsche Zuffenhausen, Werk 2, Pforte (Lieferanten), Schwieberdinger Str. 130, 70435 Stuttgart, Deutschland

Additional Address with Site

1.5 TERMINOLOGY

This section is non-normative

1.5.1 GENERAL

Golden Record: A Golden Record is 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 the BPDM standards. The Golden Record status is a prerequisite for each business partner data record to receive a valid business partner number.

Sharing Member: A Sharing Member is a data space participant who shares the business partner data of his own business environment or in the role of a Managing Legal Entity the business partner data of the business environments of its Managed Legal Entities2.

Managing Legal Entity: The legal entity responsible for managing legal entity, site, and address data on behalf of other legal entities (Managed Legal Entities) within the data space.

Managed Legal Entity: A legal entity on whose behalf legal entity, site, and address data are managed by the Managing Legal Entity.

Company Data: Company Data are business partner data that represent the own organizational structures of the Sharing Member or if the Sharing Member is in the role of a Managing Legal Entity the organizational structures of its Managed Legal Entities.

1.5.2 DATA MODEL

This chapter explains the data model3 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

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 data spaces, a business partner is an organization (such as an enterprise or company, university, association, etc., and not a natural person) or one of its organization parts that acts as unique partner within the 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 entity combinations from the Business Partner Data Pool. 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 and the site is known to BPDM / has been shared by the owner. Note that for the assignment of the entities the respective BPNL, BPNS or BPNA (from the Business Partner Data Pool) are used.

The business partner address type and the BPN assignment determine the entity combinations, on which the business partner entity provides a merged view. The combinations are visualized in the following table. All other combinations are invalid as output of the sharing process and will result in a sharing error:

DescriptionAddress TypeBPNLBPNSBPNAShared byExample
A business partner having assigned a legal entity and its legal address.Legal Addresshas a-has aAnyone1.4.1 EXAMPLE 1
A business partner having assigned a legal entity and one of its additional addresses.Additional Addresshas a-has aAnyone1.4.2 EXAMPLE 2
A business partner having assigned a legal entity, a site and its main address1, which is not the legal address.Site Main Address1has ahas ahas aOwner only1.4.3 EXAMPLE 4
A business partner having assigned a legal entity, a site and its main address1, which is also the legal address.Legal and Site Main Address1has ahas ahas aOwner only1.4.4 EXAMPLE 4
A business partner having assigned a legal entity, a site and one of its addresses, which is neither the legal address nor the main address1 of that site.Additional Addresshas ahas ahas aOwner only1.4.5 EXAMPLE 5

These are the attributes of the business partner:

AttributeDescription(Data) Type / Code List / Enumeration
External IDThe identifier which uniquely identifies (in the internal system landscape of the Sharing Member) the business partner.String
Name PartsThe list of name parts of the business partner to accommodate the different number of name fields in different systems.List of String
IdentifiersThe list of identifiers of the business partner.List of Business Partner Identifier
RolesOne or more of the roles, the business partner assumes with respect to the Sharing Member / Managed Legal Entity.List of Enum
Is Own Company DataIndicates whether the Sharing Member claims (in the initial upload) the business partner to belong to its Company Data.4Boolean
Created AtThe date and time when the business partner data record has been created.Date / Time
Updated AtThe date and time when the business partner data record has been last updated.Date / Time
Legal EntityThe legal entity, on which the business partner provides a view.Legal Entity Representation
SiteThe site, on which the business partner provides a view.Site Representation
AddressThe address, on which the business partner provides a view.Address Representation

A business partner can assume one or more of the business partner roles:

  1. supplier (value=SUPPLIER): The business partner is a supplier of the Sharing Member / Managed Legal Entity, meaning that the Sharing Member / Managed Legal Entity buys goods or services from the business partner.
  2. customer (value=CUSTOMER): The business partner is a customer of the Sharing Member / Managed Legal Entity, meaning that the Sharing Member / Managed Legal Entity sells goods or services to the business partner.
1.5.2.1.1 BUSINESS PARTNER IDENTIFIER

A business partner identifier (uniquely) identifies the business partner, such as the German Handelsregisternummer, a VAT registration / taxpayer identification number, etc.

AttributeDescription(Data) Type / Code List / Enumeration
ValueThe value of the identifier like “DE123465789”String
TypeThe type of the identifier.Identifier Type
Issuing BodyThe 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

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.

AttributeDescription(Data) Type / Code List / Enumeration
Legal Entity BPNThe BPNL of the legal entity, on which the business partner provides a view.String
Legal NameThe name of the legal entity, on which the business partner provides a view, according to official registers.String
Short NameThe abbreviated name of the legal entity, on which the business partner provides a view.String
StatesThe list of (temporary) states of the legal entity.List of Legal Entity State
Legal FormThe legal form of the legal entity, on which the business partner provides a view.Legal Form

A legal entity state indicates if the legal entity is active or inactive5. This does not describe the relation between a data space participant and a business partner and whether they have active business, but it describes whether the legal entity is still operating.

AttributeDescription(Data) Type / Code List / Enumeration
Valid FromThe date and time from which the state is valid.Date / Time
Valid ToThe date and time until the state is valid.Date / Time
TypeOne of the state types.Enum

A legal entity state can be classified into one of the legal entity state types:

  1. active (value=ACTIVE): Legal entity is operating and is registered in the official registers under its legal address.
  2. inactive (value=INACTIVE): Legal entity is not operating, may be marked as out of business (or similar) or may not even be registered in the official registers under its legal address anymore. It still exists in the BPDM Pool for historical reasons, such as for auditing purposes.
1.5.2.3 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.

AttributeDescription(Data) Type / Code List / Enumeration
Site BPNThe BPNS of the site, on which the business partner provides a view.String
NameThe 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
StatesThe list of the (temporary) states of the site.List of Site State
1.5.2.3.1 SITE STATE

A site state indicates if the site is active or inactive5.This does not describe the relation between a data space participant and a business partner and whether they have active business, but it describes whether the site is still operating.

AttributeDescription(Data) Type / Code List / Enumeration
Valid FromThe date from which the state is valid.String
Valid ToThe date until the state is valid.String
TypeOne of the state types.Enum

A site state can be classified into one of the site state types:

  1. active (value=ACTIVE): Site is operating at its site main address.
  2. inactive (value=INACTIVE): Site is not operating at its site main address anymore. It still exists in the BPDM Pool for historical reasons, such as for auditing purposes.
1.5.2.4 ADDRESS REPRESENTATION

An address representation adds context information to the address, on which the business partner provides a view. Additionally, it contains most of the information from the assigned address.

AttributeDescription(Data) Type / Code List / Enumeration
Address BPNThe BPNA of the address, on which the business partner provides a view.String
NameThe name of the address, on which the business partner provides a view. This is not according to official registers but according to the name the sharing members agree on, such as the name of a gate or any other additional names that designate the address in common parlance.String
StatesThe list of (temporary) states of the address.List of Address State
TypeOne of the address types.Enum
Physical Postal AddressThe physical postal address of the address, on which the business partner provides a view, such as an office, warehouse, gate, etc.Physical Postal Address
Alternative Postal AddressThe alternative postal address of the address, on which the business partner provides a view, for example if the goods are to be picked up somewhere else.Alternative Postal Address

An address can be classified into one of the address types:

  1. legal address (value=LegalAddress): The legal address of a legal entity, which is used for official correspondence with government and tax authorities, and used in all legal or court documents. It is the address that is registered in the official registers.
  2. site main address6 (value=SiteMainAddress): The main address of a site, where typically the main entrance or the reception is located, or where the mail is delivered to. In case there is an official site register in the country, where the site is located, this is the address that is registered in the official site register, such as in case of the French SIRET.
  3. legal and site main address6 (value=LegalAndSiteMainAddress): The address is a combination of the legal address of a legal entity and the main address of a site.
  4. additional address (value=AdditionalAddress): An additional address of a legal entity or site, such as different gates, which is not the legal address of a legal entity and not the main address of a site. It can be used for delivery of goods or services, but it is not registered in the official registers.
1.5.2.4.1 ADDRESS STATE

An address state indicates if the address is active or inactive5. This does not describe the relation between a data space participant and a business partner and whether they have active business, but it describes whether the business partner is still operating at that address.

AttributeDescription(Data) Type / Code List / Enumeration
Valid FromThe date from which the state is valid.String
Valid ToThe date until the state is valid.String
TypeOne of the state types.Enum

An address state can be classified into one of the address state types:

  1. active (value=ACTIVE): Legal entity or site at the address are still operating and address is still used for operational purposes, such as for delivery of goods or services.
  2. inactive (value=INACTIVE): Legal entity or site at the address are not operating anymore, or address is not used anymore for operational purposes. It still exists in the BPDM Pool for historical reasons, such as for auditing purposes.
1.5.2.5 BUSINESS PARTNER RELATION

Business Partner Relation

A business partner relation is a directed relation between two business partners with a specific type that describes the nature of the relation.

AttributeDescription(Data) Type / Code List / Enumeration
External IDThe identifier which uniquely identifies (in the internal system landscape of the Sharing Member) the business partner relation.String
TypeOne of the business partner relation types.Enum
Business Partner Source External IDThe external ID of the business partner from which the relation emerges.String
Business Partner Target External IDThe external ID of the business partner to which this relation goes.String
Business Partner Source BPNThe BPN of the business partner from which the relation emerges.String
Business Partner Target BPNThe BPN of the business partner to which this relation goes.String
Created AtThe date and time when the business partner relation data record has been created.Date / Time
Updated AtThe date and time when the business partner relation data record has been last updated.Date / Time

A business partner entity relation can be classified into one of the business partner relation types:

  1. is alternative headquarter for (value=IsAlternativeHeadquarterFor): The business partner source is an alternative headquarter for the business partner target (both being legal entities), where both legal addresses are registered in the official registers with equal rights, representing the same real-world legal entity. Multiple business partner sources can be the alternative headquarters for one business partner target, resulting in multiple relations at the business partner target. The business partner target cannot be a business partner source at the same time, so that it cannot be an alternative headquarter for itself and so that only one level of alternative headquarters is possible.
  2. is managed by (value=IsManagedBy): Legal entity, site and address data can be managed by the Managing Legal Entity (business partner target) on behalf of the Managed Legal Entity (business partner source). Multiple business partner sources can be the managed legal entities of one Managing Legal Entity (business partner target), resulting in multiple relations at the business partner target. The business partner target cannot be a business partner source at the same time, so that it cannot be the Managing Legal Entity for itself and so that only one level of managing legal entities is possible.

Legal Form

A legal form is a mandatory corporate legal framework by which companies can conduct business, charitable or other permissible activities.

AttributeDescription(Data) Type / Code List / Enumeration
Technical KeyThe technical identifier of the legal form according to ISO 20275:2017.String
NameThe name of legal form according to ISO 20275:2017.String
AbbreviationsA list of abbreviated names for the legal form according to ISO 20275:2017, such as AG for German Aktiengesellschaft.String
Transliterated NameThe transliterated name of legal form according to ISO 20275:2017.String
Transliterated AbbreviationsA list of transliterated abbreviated names for the legal form according to ISO 20275:2017, such as AG for German Aktiengesellschaft.String
LanguageThe two-letter language code according to ISO 639:2023 of the language, for that the name of the legal form has been given.String
CountryThe two-letter country code according to ISO 3166-1:2020 of the country in which the legal form is valid.String
Administrative Area Level 1The administrative area in which the legal form is valid, such as a region within a country.Administrative Area (Level 1)
Is ActiveIndicates whether the legal form is actively used or is inactive and should not be used to register new organizations.Boolean
1.5.2.7 PHYSICAL POSTAL ADDRESS

A physical postal address describes the physical location of an office, warehouse, gate, etc.

AttributeDescription(Data) Type / Code List / Enumeration
Geographic CoordinatesThe exact location of the physical postal address in latitude, longitude, and altitude.Geographic Coordinate
CountryThe two-letter country code of the physical postal address according to ISO 3166-1:2020.String
Administrative Area Level 1The administrative area of the physical postal address, such as a region within a country.Administrative Area (Level 1)
Administrative Area Level 2The name of the locally regulated secondary country subdivision of the physical postal address, such as county within a country.String
Administrative Area Level 3The name of the locally regulated tertiary country subdivision of the physical address, such as townships within a country.String
Postal CodeThe alphanumeric identifier (sometimes including spaces or punctuation) of the physical postal address for the purpose of sorting mail, synonyms: postcode, post code, PIN or ZIP code.String
CityThe name of the city of the physical postal address, synonyms: town, village, municipality.String
DistrictThe name of the district of the physical postal address which divides the city in several smaller areas.String
StreetThe street of the physical postal address, synonyms: road, avenue, lane, boulevard, highwayStreet
Company Postal CodeThe company postal code of the physical postal address, which is sometimes required for large companies.String
Tax Jurisdiction CodeThe identifier of the particular geographic or governmental area to which the physical mailing address belongs and which is responsible for administering tax laws and collecting taxes from individuals and businesses.String
Industrial ZoneThe industrial zone of the physical postal address, designating an area for industrial development, synonym: industrial area.String
BuildingThe alphanumeric identifier of the building addressed by the physical postal address.String
FloorThe number of a floor in the building addressed by the physical postal address, synonym: level.String
DoorThe number of a door in the building on the respective floor addressed by the physical postal address, synonyms: room, suite.String
1.5.2.7.1 STREET

A street is a public road in a city, town, or village, typically with houses and buildings on one or both sides, synonyms: road, avenue, lane, boulevard, highway.

AttributeDescription(Data) Type / Code List / Enumeration
Name PrefixThe street related information, which is usually printed before the official street name on an address label.String
Additional Name PrefixThe additional street related information, which is usually printed before the official street name on an address label.String
NameThe name of the street.String
Name SuffixThe street related information, which is usually printed after the official street name on an address label.String
Additional Name SuffixThe additional street related information, which is usually printed after the official street name on an address label.String
House NumberThe alphanumeric identifier representing the exact location of a building within the street.String
House Number SupplementThe alphanumeric identifier representing the exact location of a business partner in a building. Note this information might be further detailed out semantically in the building, floor, and door attributes. However, this attribute is the only relevant for addressing the business partner.String
MilestoneThe alphanumeric identifier representing the exact location of an addressed object within a street without house numbers, such as within long roads.String
DirectionThe cardinal direction describing where the exit to the location of the addressed object on large highways / motorways is located, such as Highway 101 South.String
1.5.2.8 ALTERNATIVE POSTAL ADDRESS

An alternative postal address describes an alternative way of delivery for example if the goods are to be picked up somewhere else.

AttributeDescription(Data) Type / Code List / Enumeration
Geographic CoordinatesThe exact location of the alternative postal address in latitude, longitude, and altitude.Geographic Coordinate
CountryThe two-letter country code of the postal address according to ISO 3166-1:2020.String
Administrative Area Level 1The administrative area of the alternative postal address, such as a region within a country.Administrative Area (Level 1)
Postal CodeThe alphanumeric identifier (sometimes including spaces or punctuation) of the physical postal address for the purpose of sorting mail, synonyms: postcode, post code, PIN or ZIP code.String
CityThe name of the city of the physical postal address, synonyms: town, village, municipality.String
CityThe name of the city of the alternative postal address, synonyms: town, village, municipality.String
Delivery Service TypeOne of the alternative postal address types.Enum
Delivery Service QualifierThe qualifier uniquely identifying the delivery service endpoint of the alternative postal address in conjunction with the delivery service number. In some countries for example, entering a P.O. box number, postal code and city is not sufficient to uniquely identify a P.O. box, because the same P.O. box number is assigned multiple times in some cities.String
Delivery Service NumberThe number indicating the delivery service endpoint of the alternative postal address to which the delivery is to be delivered, such as a P.O. box number or a private bag number.String

An alternative postal address can be classified into one of the delivery service types:

  1. P.O. box (value=PO_BOX): A delivery service type for a numbered box at a post office, where mail can be delivered and picked up by the recipient.
  2. private bag (value=PRIVATE_BAG): A delivery service type, where mail is dispatched to the holder directly, if there are no street delivery services (like in countries of Africa).
  3. boîte postale (value=BOITE_POSTALE): The French or Canadian version of a P.O. box.
1.5.2.9 ADMINISTRATIVE AREA (Level 1)

An administrative area (level 1) is the country subdivision according to ISO 3166-2:2020, such as regions within a country.

AttributeDescription(Data) Type / Code List / Enumeration
NameThe name of the country subdivision according to ISO 3166-2:2020.String
CodeThe six-character alphanumeric code according to ISO 3166-2:2020, consisting of the two-letter ISO 3166-1:2020 country code and a three-character alphanumeric code for the subdivision in that country, separated by a hyphen.String
1.5.2.10 GEOGRAPHIC COORDINATES

Geographic coordinates describe an exact location in latitude, longitude, and altitude, according to ISO 6709:2022 with WGS 84 (NGA STND 0036 1.0.0) as the currently only supported coordinate reference system.

AttributeDescription(Data) Type / Code List / Enumeration
LongitudeThe geographic coordinate of a place indicating the distance to the west or east of the line passing through Greenwich, in decimal degrees.Float
LatitudeThe geographic coordinate of a place indicating its distance to the north or south of the equator, in decimal degrees.Float
AltitudeThe geographic coordinate of a place indicating its height above mean sea level, in meters.Float
1.5.2.11 IDENTIFIER TYPE

Identifier Type

An identifier type defines the name or category of an identifier, such as the German Handelsregisternummer, a VAT registration / taxpayer identification number, etc. The identifier type is valid for a business partner type and used in a specific country.

AttributeDescription(Data) Type / Code List / Enumeration
Technical KeyThe technical identifier of the identifier type.String
NameThe local name of the identifier type.String
Business Partner TypeOne of the types of business partners for which the identifier type is valid.Enum
Identifier Type CategoryOne of the categories of identifier types.Enum
AbbreviationThe local abbreviated name of the identifier type.String
Transliterated NameThe transliterated local name of the identifier type.String
Transliterated AbbreviationThe transliterated local abbreviated name of the identifier type.String
FormatThe regular expression for the identifier type formatString

An identifier type can be valid for one of the following business partner types:

  1. legal entity (value=LEGAL_ENTITY): see Legal Entity.
  2. address (value=ADDRESS): see Address.

An identifier type can be classified into one or more of the following identifier type categories:

  1. value-added tax registration (value=VAT): category for value-added tax identification numbers (VAT IDs or VATINs), e.g. EU VAT ID, UID MWST/TVA/IPA, identifying the business partner usually related to tax, such as for invoicing and reporting of value-added tax (VAT) to the tax authorities.
  2. taxpayer identification (value=TIN): category for taxpayer identification numbers (TINs), e.g. SIREN, NIF, identifying the business partner usually related to tax, such as for income tax, corporate tax, or other tax obligations.
  3. national business registration (value=NBR): category for national business registration numbers (e.g. HRB-Nummer, Firmenbuchnummer), identifying the business partner for different purposes (e.g. commercial register, trade register), which are not related to tax.
  4. international business registration (value=IBR): category for international business registration numbers (e.g. LEI, EORI), identifying the business partner for different purposes (e.g. regulatory reporting, risk management at financial regulatory bodies), which are not related to tax.
  5. other (value=OTH): category for other identifiers (e.g. D&B D-U-N-S, GS1 GLN), which are not legally secure.
1.5.2.11.1 IDENTIFIER TYPE DETAILS

The identifier type details describe for which countries an identifier is valid and mandatory

AttributeDescription(Data) Type / Code List / Enumeration
CountryThe two-letter country code according to ISO 3166-1:2020 of the country in which the identifier type is valid. Can be empty if identifier type is valid in all countries.String
MandatoryIndicates whether the identifier type is mandatory in the country.Boolean
1.5.2.12 SHARING STATE ENTRY

Sharing State Entry

A sharing state entry shows the progress in the sharing process and is updated each time the progress for a business partner (relation) changes. The business partner (relation) is identified by the external ID.

AttributeDescription(Data) Type / Code List / Enumeration
External IDThe external ID of the business partner for which the sharing state entry was created.String
Sharing State TypeOne of the sharing state types of the current sharing state.Enum
Sharing Error CodeOne of the sharing error codes in case the current sharing state type is error.Enum
Sharing Process Started AtThe date and time when the processing of the business partner data record started.Date / Time

A sharing state entry can be classified into one of the following sharing state types:

  1. pending (value=Pending): The business partner data record is currently being processed.
  2. success (value=Success): The business partner data record has been successfully processed and the BPNL, BPNS and BPNA have been assigned.
  3. error (value=Error): The business partner data record could not be processed because of an error.

In case the sharing state type is error, the sharing error code is one of the following:

  1. sharing process error (value=SharingProcessError): An error occurred during the sharing process, such as a technical error.
  2. sharing timeout (value=SharingTimeout): The sharing process took too long and timed out.
  3. BPN not in pool (value=BpnNotInPool): The provided business partner number (BPN) is not in the BPDM Pool, so that the sharing process cannot be completed.
1.5.2.13 CHANGELOG ENTRY

Changelog Entry

An entry of the changelog, which is created each time a business partner (relation) is modified and contains data about the change. The actual new state of the business partner (relation) is not included.

AttributeDescription(Data) Type / Code List / Enumeration
External IDThe external ID of the business partner for which the changelog entry was created.String
Changelog TypeOne of the changelog types.Enum
TimestampThe date and time when the changelog entry was created.Date / Time

A changelog entry can be classified into one of the following changelog types:

  1. create (value=CREATE): changelog for the action that the business partner was created.
  2. update (value=UPDATE): changelog for the action that the business partner was updated.

2 BUSINESS PARTNER GATE API [NORMATIVE]

The Business Partner Gate API allows to upload and download business partner data records to improve their quality and enrich them with additional information. The Gate API MUST be implemented based on the OpenAPI specification (3.1.0).

2.1 PRECONDITIONS AND DEPENDENCIES

To run the API, the technical components described in the Eclipse Tractus-X BPDM GitHub repository (7.1.x) SHOULD be set up.

2.2 API SPECIFICATION

2.2.1 API ENDPOINT & RESOURCES

The Gate API MUST be implemented as defined in the Business Partner Gate OpenAPI specification (7.1.x)

The resources MUST use the well-known HTTP request methods for CRU(D) operations:

  • POST method MUST be used for create requests
  • PUT6 method MUST be used for update requests
  • GET method MUST be used for read requests

The POST method MAY also be used for read requests, if input is not given by parameters but rather by an HTTP body to bypass maximum URL length. The PUT method MAY also be used for upsert requests (create or update) if this is required. A state (active / inactive) at each entity MUST be used for a soft delete, so that the DELETE method SHOULD NOT be used. Other HTTP request methods SHOULD NOT be used, including PATCH.

To facilitate the compliance assessment, this chapter additionally lists and describes the API resources of the Gate API per API controller.

The following API controllers of the OpenAPI document MUST be implemented:

  • Business Partner controller
  • Sharing state controller
  • Changelog controller

Uploading and downloading data to/from the Gate API MUST follow a staging concept with two stages, so that consumers of the Gate API can compare what they have uploaded (input stage) against what has been corrected and/or enriched by BPDM (output stage). The following controllers MUST distinguish between an input and an output stage:

  • Business Partner controller
  • Changelog controller

Note that all resources of the OpenAPI document described in the following are MANDATORY. Conversely, all resources not described in the following are OPTIONAL.

2.2.1.1 BUSINESS PARTNER CONTROLLER

The business partner controller MUST allow to create, update, or read business partners in the input and read from the output stage. It MUST have the following resources:

Business Partner Controller ResourcesDescription
PUT/input/business-partnersCreates business partners or updates existing business partners in the input stage.
POST/input/business-partners/searchReturns business partners by an array of external IDs from the input stage.
POST/output/business-partners/searchReturns business partners by an array of external IDs from the output stage.

2.2.1.2 BUSINESS PARTNER RELATION CONTROLLER

Business Partner Relation Controller ResourcesDescription
PUT/input/relationsCreates business partner relations or updates existing business partners relations in the input stage.
POST/input/relations/searchReturns business partner relations by an array of external IDs from the input stage.
POST/output/relations/searchReturns business partner relations by an array of external IDs from the output stage.

2.2.1.3 SHARING STATE CONTROLLER

The sharing state controller MUST allow to read sharing state entries of business partners and business partner relations. A sharing state of type "Success" SHOULD include the assigned BPNL, BPNS and BPNA. The sharing state controller MUST have the following resources:

Sharing State Controller ResourcesDescription
GET/business-partners/sharing-stateReturns sharing states of business partners, optionally filtered by an array of external IDs.
GET/relations/sharing-stateReturns sharing states of business partners relations, optionally filtered by an array of external IDs.

2.2.1.4 CHANGELOG CONTROLLER

The changelog controller MUST allow to read business partner change log entries. It MUST have the following resources:

Changelog Controller ResourcesDescription
POST/input/business-partners/changelog/searchReturns change log entries as of a specified timestamp from the input stage, optionally filtered by an array of external IDs.
POST/output/business-partners/changelog/searchReturns change log entries as of a specified timestamp from the output stage, optionally filtered by an array of external IDs.

2.2.1.5 RELATION CHANGELOG CONTROLLER

The changelog controller MUST allow to read business partner relation change log entries. It MUST have the following resources:

Changelog Controller ResourcesDescription
POST/input/relations/changelog/searchReturns change log entries as of a specified timestamp from the input stage, optionally filtered by an array of external IDs.
POST/output/relations/changelog/searchReturns change log entries as of a specified timestamp from the output stage, optionally filtered by an array of external IDs.

2.2.2 AVAILABLE DATA TYPES

The API MUST use JSON as the payload format transported via HTTP. Other formats are OPTIONAL.

2.2.3 DATA ASSET STRUCTURE

The following data assets MUST be registered at the Core Service Provider so that the Sharing Member can negotiate an API usage contract based on the mentioned usage purpose with the Core Service Provider and access its dedicated BPDM Gate (hosted by the Core Service Provider) through these data assets2:

TypeSubjectVersionDescriptionUsage Purpose
cx-taxo:BPDMGatecx-taxo:FullAccessGateInputForSharingMember7Grants the Sharing Member full access to the input persistence. This can be used to read business partner (relation) data in the input persistence, and create / update business partner (relation) data in the input persistence from data sources of the Sharing Member. To that end, it also grants read access to the input (relation) changelog entries.cx.bpdm.gate.upload:1
cx-taxo:BPDMGatecx-taxo:ReadAccessGateInputForSharingMember7Grants the Sharing Member read access to the input persistence. This can be used explicitly for value-added services to read business partner (relation) data from the input persistence. To that end, it also grants read access to the input (relation) changelog entries.cx.bpdm.vas.*:1
cx-taxo:BPDMGatecx-taxo:ReadAccessGateOutputForSharingMember7Grants the Sharing Member read access to the output persistence. This can be used to read business partner (relation) data from the output persistence so that the data sources of the Sharing Member can be updated. Furthermore, it can be used to update data sources in value-added services. To that end, it also grants read access to the output (relation) changelog and sharing state entries.cx.bpdm.gate.download:1

The data asset MUST contain the following properties with the corresponding values from the table above:

An example payload for the asset:

{
"@context": {
"dct": "http://purl.org/dc/terms/",
"cx-taxo": "https://w3id.org/catenax/taxonomy#",
"cx-common": "https://w3id.org/catenax/ontology/common#",
},
"@type": "Asset",
"@id": "a8f15946-2347-47a8-a67f-846e7303fd94",
"properties": {
"dct:type": {
"@id": "cx-taxo:BPDMGate"
},
"dct:subject": {
"@id": "cx-taxo:FullAccessGateInputForSharingMember"
},
"dct:description": "Grants the Sharing Member full access to the input persistence. This can be used to read business partner (relation) data in the input persistence, and create / update business partner (relation) data in the input persistence from data sources of the Sharing Member. To that end, it also grants read access to the input (relation) changelog entries.",
"cx-common:version": "7"
},
"dataAddress": {
"@type": "DataAddress",
"type": "HttpData",
"baseUrl": "https://<host>/companies/<company>/api/v7/",
"oauth2:tokenUrl": "https://<host>/auth/realms/<realm>/protocol/openid-connect/token",
"oauth2:clientId": "<technical user>",
"oauth2:clientSecretKey": "<key to the secret of the technical user in the vault>",
"proxyMethod": true,
"proxyPath": true,
"proxyQueryParams": true,
"proxyBody": true
}
}

There MUST be measures in place, that prevent direct access to the Gate API from outside the internal environment of the operating company. Access from outside of the internal environment of the operating company to the Gate API MUST only be possible via the Data Space Connector. The OAuth2 client permissions MUST be configured to solely allow access to the API resources defined in the corresponding asset, checking HTTP method (read vs. full access), path (e.g. for input / output / sharing state), query parameters and body of the HTTP request sent to the data plane public API of the Data Space Agent, which acts as a proxy for the Gate API7

2.2.4 ERROR HANDLING

The following http response codes MUST be defined for all resources:

  • 200 - OK
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 500 - Internal Server Error

The IANA HTTP Status Code Registry MUST be adhered to for the decision on when to use which error code.

2.2.5 POLICY CONSTRAINTS FOR DATA EXCHANGE

In alignment with our commitment to data sovereignty, a specific framework governing the utilization of data within the Catena-X use cases has been outlined. As part of this data sovereignty framework, conventions for access policies, for usage policies and for the constraints contained in the policies have been specified in standard 'CX-0152 Policy Constraints for Data Exchange'. This standard document CX-0152 MUST be followed when providing services or apps for data sharing/consuming and when sharing or consuming data in the Catena-X ecosystem. What conventions are relevant for what roles named in 1.1 AUDIENCE & SCOPE is specified in the CX-0152 standard document as well. CX-0152 can be found in the standard library.

3 REFERENCES

3.1 NORMATIVE REFERENCES

3.2 NON-NORMATIVE REFERENCES

This section is non-normative

3.3 REFERENCE IMPLEMENTATION

This section is non-normative

ANNEXES

FIGURES

This section is non-normative

TABLES

This section is non-normative

Intentionally left blank.

Copyright © 2025 Catena-X Automotive Network e.V. All rights reserved. For more information, please visit here.

Footnotes

  1. Note that there is currently a debate as to whether a site is only a consolidation of addresses (BPNA), with all addresses being equally ranked, since a "main" address can't always be defined at this point in time. This may lead to changes in the next update of this standard. 2 3 4 5 6 7 8

  2. Note that the Sharing Member assumes the roles Data Provider on upload and Data Consumer on download of business partner data, while the Core Service Provider assumes the roles Data Consumer on upload and Data Provider on download of business partner data. 2

  3. Note that PlantUml is used for the conceptual UML diagrams in this document (A = abstract class; green E = entity; C = class; red E = enumeration). An abstract class has no actual representation in the OpenAPI implementation. An entity is usually implemented by an own OpenAPI controller with resources and usually is the root in a payload, while a class is a sub node in the payload. An enumeration is a set of predefined values.

  4. Note that each data record in the MDM business partner data of the Sharing Member does not explicitly have to be flagged as "is own company data". However, it is important that the Sharing Member flags business partners as "is own company data" in the initial upload of own Company Data, such as by introducing a constant in the used middleware.

  5. Note that this a currently a soft-delete approach and not a business state. However, this can be adapted in the next version of this standard. 2 3

  6. Note that in case of a PUT the corresponding resources expect to receive the full updated record, including values that did not change. 2 3

  7. Note that the definition of the data assets depends on the current implementation state of the reference implementation (Tractus-X Eclipse Dataspace Connector). Therefore the data assets represent permissions on APIs, whereas they should actually only represent APIs.