Table of Content
Terms of use, disclaimer
-
-
-
-
-
-
-
-
-
-
-
-
-
-
1. General Information
1.1 Goal of Document
This document serves as a technical description of the atrify Business Validation Service API, a RESTful Webservice API used to validate GDSN Trade Items against the current set of atrify validation rules
1.2 API Design
The validation service will take any nested CIN hierarchy, validating it against the desired ruleset, and returning a validation status result and a list of error messages. The API follows a synchronous design, i.e. the CIN hierarchy will be sent in one POST request and as a response the validation response will be returned.
1.3 General Workflow
- Call validation service with a POST request, containing a well-formed GDSN. CatalogueItemNotificationMessage as XML payload with one transaction and exactly one nested hierarchy. Retrieve the validation result.
- Analyze the validation result. The qualityLevel should be “OK” when the file is valid.
1.4 Restrictions of the Business Validations Service API
Please note that receiving a valid result from the Business Validations Service API does not guarantee that the validation result from the Data Sync Engine (Data Pool) will be valid as well. Main reason is that the API is not connected to the production database and has no possibility to check against existing items and/or the appropriate hierarchy tree. E.g. deviation checks with regard to the GTIN allocation rules (measures and weights), changes of core hierarchy related data (Case to Base GTIN swap) and TPD is not supported. Further the optional scope parameter “FMCG” is allowed for target market Germany (Code: 276) only.
2. Authentication
2.1 OAuth2
Authentication is done using pre-shared clientid and client secret. With these credentials a OAuth2 access token can be retrieved and must be placed in every subsequent request in the Authorization as bearer token. For more information please refer to the documentation on the internet page:
https://eu.api.atrify.com/v1/api-reference/
Without a valid access token, access to the service will not be allowed (HTTP 401). They do expire.
3. Validation Request
3.1 List validation scopes (GET)
Returns a list of possible validation scopes.
3.1.1 Request
| Method |
URL |
| GET |
v1/businessvalidations |
| Type |
Params |
Values |
| Header |
Authorization |
Bearer <TOKEN> |
Authorization (TOKEN)
The mandatory OAuth2 access token.
Example curl --request GET \
--url https://eu.api.atrify.com/v1/businessvalidations \
--header 'Authorization: Bearer <token>'
3.1.2 Response
| Status |
Response |
| 200 |
Response will be a list of scopes.
An example response is:
[
{ "id": "GDSN" },
{ "id": "FMCG" }
] |
| 401 |
No response body |
3.2 Create a validation request (POST)
Create a new validation request by uploading a nested CIN message.
3.2.1 Request
| Method |
URL |
| POST |
v1/businessvalidations/.<scope>?itemType=Type?<itemtype> |
| Type |
Params |
Values |
| Header |
Authorization |
Bearer <TOKEN> |
| Request |
scope |
String (see 3.1.1 Request) |
| POST |
payload |
applications/xml |
Authorization (TOKEN)
The mandatory OAuth2 access token.
itemtype
The input type of the provided file. Default is “CIN”.
scope
Defines the set of validation rules to be executed against the provided item hierarchy. Possible values
are “GDSN” and “FMCG”:
- “GDSN” refers to the standard GDSN set of validation rules as agreed by the LEH community in Germany.
- An alternative ruleset is “FMCG”, which includes community validations for fast moving consumer goods on top of the “GDSN” rules, i.e. “FMCG” includes “GDSN”. The “FMCG” ruleset implements rules as agreed by the LEH community in Germany.. Please note that FMCG will be supported with items having target market Germany (Code: 276) only. If you post a message with FMCG scope having any other target market the service will throw an error.
payload
The payload must contain a well-formed GDSN CatalogueItemNotificationMessage containing one single transaction, with one single, nested hierarchy.
Example
curl --request POST \
--url https://eu.api.atrify.com/v1/businessvalidations/FMCG \
--header 'Authorization: Bearer <token>'
--header 'Content-Type: application/xml' \
-data '<data>'
3.2.2 Response
| Status |
Response |
| 200 |
Response will be an object containing the scope, quality, and findings.
An example response is:
{
"scope": "FMCG",
"quality": "Error",
"findings": [
{
"severity": "Error",
"attribute": "GDSN_IsTradeItemAConsumerUnit",
"code": "31702",
"description":
"56468417893148/2427893114207/276: Please populate \"Is Trade Item A Consumer Unit\". This indication is mandatory (GDSN Rule 1008)."
},
]
} |
| 401 |
Not Authorized |
| 403 |
Forbidden |
| 500 |
Internal server error |
scope
The validation that was used
quality
Overall quality Level. Might be “OK”,”Error” or “Warning”
findings
The information data structure will contain the validation rules that were not ok. If the overall qualityLevel is “OK”, the information list will be empty.
findings.[i]severity
One of the following:
- Fatal - indicates a problem on the level of the XML, such as a missing tag etc.
- Error - indicates a validation error that needs to be fixed
- Warning - indicates a potential problem that however does not prevent processing
findings.[i]attribute
The attribute name where a validation issue was detected.
findings.[i]code
This error code field is an internal value that is associated with a given validation rule.
findings.[i]description
The validation finding itself usually contains all necessary information to track down the issue with an item. It will contain item key information, as well as the attribute names involved and a description of what was expected, and why the error occurred.
History of Changes
| No. |
Date |
Editor |
Changes |
| 1.0 |
2022 |
Eric Schneider |
Initial version |
Contact Us
If you need assistance, please contact us at [email protected].
