Skip to main content
Release: 24.03 (deprecated)

CX-0081 Country Risk API v1.1.0

ABSTRACT

The Country Risk Application is a Value-Added Service (VAS) to the Catena-X ecosystem and is meant to assess country specific risks. To accomplish this, the application collects data from ratings, which create country specific scores ranging from 0–100. Which ratings and sources are used is the responsibility of the respective service provider submitting said datasets. These ratings are then mapped to business partners which are collected from sharing member specific sources, namely the Business Partner GATE, to ensure not to mix data between sharing members. A sharing member can display and download its mapped information in a dashboard or receive the information via API calls to use the information in its own systems.

The user can create and upload their own ratings as well and assign country specific values depending on their own research. The country is then classified depending on the user's uploaded rating data. The scope of this document is to describe the dedicated API for this application, for collecting the necessary data from sharing members, as well as how to share the mapped data with them.

This document is to be read in context with the other relevant Catena-X standards. In addition, it assumes that the relevant entities have followed and met all the other dependent onboarding processes and requirements.

You can find the other standards in the standard library of Catena-X: https://catena-x.net/de/standard-library

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 the compliance process of this API.

COMPARISON WITH THE PREVIOUS VERSION OF THE STANDARD

VersionDescriptionDateAuthor
V1.0.0Initial release06.10.2023Enzio Lincke, Fábio Mota, Alexander Keppler, Korbinian Hutter
V1.1.0Update regarding generic endpoint of the Gate and the EDC. Affected chapters are 1.2.1.4 The Gneric Endpoint & 2.2.3 EDC DATA ASSET STRUCTURE22.03.2024Fábio Mota, Alexander Keppler

1 INTRODUCTION

1.1 AUDIENCE & SCOPE

This section is non-normative.

The purpose of this standard is to improve interoperability and provide a standardized solution for the Catena-X network. This standard is relevant for Catena-X certified Operational Companies acting as Business Application Providers. This document focuses on the Country Risk application and its respective API. The API is the base framework for the Country Risk Dashboard, as the front-end dashboard uses API calls to receive relevant data. Country Risk is a VAS of Catena-X and is part of the “Know Your Business Partner”-approach and the business partner Golden Record process.

This standard is relevant for the following roles.

  • Data Provider / Consumer
  • Business Application Provider

The API as currently implemented consists of two distinct sections, which are listed and referred to as the dashboard and sharing controllers. The dashboard controller implementation is OPTIONAL and not in the scope of this standard. The sharing controller is REQUIRED, and therefore is part of the scope of this standard. The standard is only relevant when a Business Application Provider wishes to obtain certification by Catena-X to offer a Catena-X certified Country Risk application.

1.2 CONTEXT AND ARCHITECTURE FIT

This section is non-normative.

Geopolitical risks are becoming increasingly relevant in today's VUCA (Volatile, Uncertain, Complex, Ambiguous) environment, and businesses require effective solutions to meet their needs. VUCA times are characterized by rapid changes, such as wars, shortages, and political instabilities to name a few.

The key business challenge is to maintain timely awareness of a business partner's status, whether during ongoing business or during the initial stages of partnership development. Businesses need to know who they are dealing with, particularly when engaging in international partnerships.

The country risk score gives insights into country-specific information related to corruption, political stability, economic risk, and social and structural factors.

There are several challenges that exist when it comes to conducting risk assessments.

  • Data is not updated frequently, which means that risk assessments are usually conducted only once a year, leaving assessments dependent on outdated or incorrect information.
  • Most risk assessments are still being conducted manually or with semi-automated processes, leading to a greater likelihood of errors.
  • Risk assessments are often derived from only a few sources and, as a result, the coverage can be incomplete and not as comprehensive as needed. Not all business partners are considered due to limitations in the amount of time and resources required.
  • Extraordinary events are analysed reactively and manually, requiring considerable time and effort.
  • With a large system landscape, it is often not possible to perform a direct check of all business partners, and manual data consolidation must take place.
  • Finally, manual reconciliation can be error-prone, resulting in potential inaccuracies in the overall risk assessment results.

The below diagram outlines the interaction of the components of the Country Risk application, API and other external objects.

StandardisedDataExchange

In the below diagram, the two types of access mediums are shown for front-end and back-end access and application usage.

[access mediums

For more information, please refer to the latest Catena-X Business Partner Gate standard named CX-0074 Business Partner Gate API.

You can find the other standards in the standard library of Catena-X: https://catena-x.net/de/standard-library.

1.2.1 BUSINESS PARTNER NUMBER (BPN) AND RATING MAPPING LOGIC TO OBTAIN RATING DATA

The Country Risk Application needs to comply with the three different business partner types as per the data model, namely these are:

  • Legal Entity
  • Site
  • Address

Based on this statement, the following data needs to be received from the sharing member’s Business Partner Gate.

AttributeDescriptionData Type
BPNLThe identifier of the data set issued by BPDMString
Legal nameThe legal name of the companyString
Street nameThe name of street of the address of this business partnerString
House numberThe number assigned to the property in a streetInteger
Postal CodeThe postal code of an areaString
CityThe name of the city from the address of this business partnerString
CountryThe name of the country from the address of this business partnerString
LongitudeGPS Coordinates in decimal degrees notation.Float
LatitudeGPS Coordinates in decimal degrees notation.Float

1.2.1.2 SITE

AttributeDescriptionData Type
BPNSThe identifier of the data set issued by BPN IssuerString
Legal nameThe legal name of the companyString
Street nameThe name of the street address of the business partnerString
House numberThe number assigned to a property in a streetInteger
Postal CodeThe postal code of an areaString
CityThe name of the city from the address of this business partnerString
CountryThe name of the country from the address of this business partnerString
LongitudeGPS Coordinates in decimal degrees notation.Float
LatitudeGPS Coordinates in decimal degrees notation.Float

1.2.1.3 ADDRESS

AttributeDescriptionData Type
BPNAThe identifier of the data set issued by BPDMString
Legal nameThe legal name of the companyString
Street nameThe name of street of the address of the business partnerString
House numberThe number assigned to the house in a streetInteger
Postal CodeThe postal code of an areaString
CityThe name of the city from the address of this business partnerString
CountryThe name of the country from the address of this business partnerString
LongitudeGPS Coordinates in decimal degrees notation.Float
LatitudeGPS Coordinates in decimal degrees notation.Float

1.2.1.4 The Generic Endpoint

At the heart of our data acquisition is the Generic Endpoint, a feature of the BPDM Golden Record Gate. This endpoint is engineered to provide a comprehensive stream of data, encompassing the various aspects of business partner information that are crucial for our risk assessment procedures.

Key Functions of the Generic Endpoint:

  • Data Aggregation: It compiles information from multiple types, offering a centralized view of business partner data.
  • Real-Time Updates: The endpoint ensures that the information is current, reflecting the latest changes and developments.
  • Accessibility: Designed for ease of use, the Generic Endpoint allows for seamless integration with the existing systems and processes around the golden record process.
  • Comprehensive Data Mapping: The data provided by the Generic Endpoint is meticulously mapped to the fields of the three business partner types discussed earlier: Legal Entity, Site, and Address. This ensures a coherent and comprehensive data integration, reflecting the data across these distinct yet interconnected categories.

Each piece of information sourced from the Generic Endpoint is carefully aligned with the corresponding attributes of Legal Entity, Site, and Address. This alignment facilitates a uniform and accurate representation of data, contributing significantly to the integrity and reliability of risk assessment processes. The data mapping adheres strictly to the structure and requirements laid out in the previous sections, ensuring consistency and precision in our risk evaluation methodologies.

This endpoints role is integral to maintaining the accuracy and reliability of our risk assessments, ensuring that decisions are made based on the most current and complete information available.

1.3 CONFORMANCE AND PROOF OF CONFORMITY

This section is non-normative.

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The keywords 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 will need to prove that their solutions conform with the Catena-X standards. To validate that the standards are applied correctly, Catena-X employs Conformity Assessment Bodies (CABs).

To prove conformity with the standard, verify your implementation aligns with the following sharing controller.

https://github.com/eclipse-tractusx/vas-country-risk-backend/blob/main/docs/swagger/sharing_controller.yml

1.4 EXAMPLES

This section is non-normative.

Intentionally left blank.

1.5 TERMINOLOGY

This section is non-normative.

[Mandatory] The following terms are especially relevant for the understanding of the standard:

  • Business Partner Number (BPN): A BPN is the unique identifier of a business partner within Catena-X. There are 3 types of BPNs.
  • BPNL: A BPNL represents and uniquely identifies a legal entity, which is defined by its legal name (including legal form, if registered), legal address and tax number.
  • BPNS: A BPNS represents and uniquely identifies a site, which is where for example a production plant, a warehouse, or an office building is located.
  • BPNA: A BPNA represents and uniquely identifies an address, which can be the legal address of a legal entity, and/or the main address of a site, or any additional address of a legal entity or site (such as different gates).
  • BPDM Gate: The Gate is the entry point for each sharing member who exchanges BPDM data with a core service provider. For each sharing member an individual gate is set up. Any bi-directional intercommunication between the sharing member and the BPDM services is handled via the gate. The interoperability with the gate is enabled via a set of APIs. The usage of the gate APIs requires the EDC connector functionalities.
  • VAS: Value-Added Service, an additional feature or capability of a core platform.
  • Rating: A score provided by an entity regarding the performance of another entity. In the context of this API standard, it is the performance of a given metric of a Business Partner or Country relating to a certain standard. An example might be 2021 CPI of India being X.Y%.

2 COUNTRY RISK API

This section is normative.

The Country Risk API allows business partners to acquire and represent data records and their respective country risk scores according to the selected ratings. The Country Risk API MUST be implemented based on the OpenAPI 3.0.1 specification.

The API documentation can be found in the following directory and file. It is RECOMMENDED to review the API documentation.

https://github.com/eclipse-tractusx/vas-country-risk-backend/blob/main/docs/swagger/sharing_controller.yml

2.1 PRECONDITIONS AND DEPENDENCIES

This section is non-normative.

To integrate and connect to the API the following documentation should be reviewed.

For the Country Risk API and database:

https://github.com/eclipse-tractusx/vas-country-risk-backend/blob/main/README.md

For the Country Risk Dashboard:

https://github.com/eclipse-tractusx/vas-country-risk/blob/main/README.md

A dependency of this specification is that the user has subscribed to a Golden Record solution of a core service provider, and has an operational gate implemented. The Business Partner Gate standard must be implemented as per the following standard: CX-0074 Business Partner Gate API

2.2 API SPECIFICATION

This section is normative.

The Country Risk API has no rate limit imposed. Users are RECOMMENDED to implement the necessary monitoring on their infrastructure to log performance metrics, and to facilitate the diagnostics of future support issues.

2.2.1 API ENDPOINTS & RESOURCES

The Country Risk API MUST be implemented as defined in the following OpenAPI document:

https://github.com/eclipse-tractusx/vas-country-risk-backend/blob/main/docs/swagger/sharing_controller.yml

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

  • POST MUST be used for create requests.
  • PUT MUST be used for update requests.
  • GET MUST be used for read requests.

POST 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. PUT 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 request method DELETE SHALL NOT be used. Other HTTP request methods SHALL NOT be used, including PATCH.

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

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

2.2.1.1 DASHBOARD CONTROLLER

This section is non-normative.

The Dashboard Controller allows the Country Risk application to represent data on the front-end user dashboard. For the purpose of this standard, the Dashboard Controller calls are optional.

The API calls listed under the Dashboard Controller are more numerous and beyond the scope of M2M automation and integration, hence are not covered in this document. The full global API consisting of the Dashboard and Sharing Controller can be found below.

https://github.com/eclipse-tractusx/vas-country-risk-backend/blob/main/docs/swagger/dashboard_controller.yml

2.2.1.2 SHARING CONTROLLER

The Sharing Controller MUST allow the user to read (search / return) information about the sharing members and their business partners.

It MUST have the following resources:

Sharing Controller ResourcesDescription
GET/api/sharing/getAllRatingsScoresForEachBpnRetrieves Mapped ratings to the Business Partners based on inserted year, Company User, Ratings and BPN.
GET/api/sharing/getAllRatingsForCompanyRetrieves ratings based on inserted year and Company user.
2.2.1.2.1 ESTABLISHING AVAILABLE RATING DATA

To get a list of all available ratings for the desired year, the following endpoint must be called.

GET/api/sharing/getAllRatingsForCompany

Input Data Example:

AttributeDescriptionData Type
yearThe year of the publication of the corresponding rating.Integer

Output Data Example:

AttributeExample OutputDescription
dataSourceNameTest RatingSource name of the rating being referenced.
typeCustomIndicates view permissions as; global; company (company of sharing member) and custom (user only).
yearPublished2021Corresponding year of the rating.
fileNameTest Company RatingReference to the uploaded rating file.
2.2.1.2.2 ESTABLISHING RATINGS FOR BPNS

In order to get a list of ratings for specific BPNs available to the sharing member, the following endpoint has to be called.

GET/api/sharing/getAllRatingsScoresForEachBpn

Input Data Example:

AttributeDescriptionData Type
ratingsA pair of rating name and year, per rating. Can parse multiple rating pairs.string
bpnOne or multiple BPNs, including their respective country.string

The below image is an example which represents multiple BPNs being entered in the mentioned GET call.

Input Data Example

Output Data Example:

AttributeDescriptionData Type
bpnOne or multiple BPNs.string
countryIndicates the country of the listed BPN.string
iso2Indicates the ISO3166-1 alpha-2 code of the country.string
ratingsA pair of rating name and year, per rating. Can parse multiple rating pairs.string
dataSourceNameSource name of the rating being referenced, per rating, if multiple.string
scoreThe score provided by the rating, per rating, if multiple.float
yearPublishedThe year of the rating, per rating, if multiple.float

The below image is an example which represents multiple ratings being returned per BPN.

Output Data Example

2.2.2 AVAILABLE DATA TYPES

The API MUST use JSON as the payload format transported via HTTP. Other formats can be added. These are then, however, OPTIONAL.

2.2.3 EDC DATA ASSET STRUCTURE

For each read resource in the Sharing Country Risk API there MUST be a dedicated EDC data asset definition.

2.2.4 ERROR HANDLING

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

https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml

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

CodeDescription
200OK
400Bad Request
401Unauthorised
403Forbidden
404Not Found
500Internal Server Error

3 REFERENCES

This section is non-normative.

  • ISO3166-1: The international standard for country codes and codes for their subdivisions.

3.1 NORMATIVE REFERENCES

Intentionally left blank.

3.2 NON-NORMATIVE REFERENCES

This section is non-normative.

The below link includes further information on the API and is optional.

https://github.com/eclipse-tractusx/vas-country-risk-backend/blob/main/docs/swagger/sharing_controller.yml

The below link includes background information on BPDM and the Value-Added Service Ecosystem.

https://catena-x.net/en/offers-standards/bpdm

The following link is regarding the BPDM Gate API.

Business Partner Gate API

3.3 REFERENCE IMPLEMENTATIONS

This section is non-normative.

There is a reference implementation for Country Risk APIs on GitHub. It is part of a Java Spring Boot open-source software project under the hood of the Eclipse Foundation and is distributed under the Apache 2.0 license.

The complete and up-to-date setup guide to implement the standard can be found below.

For API and database:

https://github.com/eclipse-tractusx/vas-country-risk-backend

For front-end Dashboard:

https://github.com/eclipse-tractusx/vas-country-risk

The below link references the source code of the back end of the application.

https://github.com/eclipse-tractusx/vas-country-risk-backend/tree/main/src/main/java/org/eclipse/tractusx/valueaddedservice/web/rest

The below link references the source code of the front-end (dashboard) of the application.

https://github.com/eclipse-tractusx/vas-country-risk/tree/main/src/components

ANNEXES

Reserved for future use.

FIGURES

This section is non-normative.

Reserved for future use.

TABLES

This section is non-normative.

Reserved for future use.

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