Branchekataloget API Gateway 1.4 documentation
Introduction
The purpose of the document is to define communication rules for retrieving product information from Branchekataloget product database. External companies should develop their own API client to access the resources provided. The API client should work according to the rules described below. The documentation describes all implemented functionalities and assumes the full range of available product information. However, the availability of particular requests or product information may be limited depending on the access level assigned to the user.
Communication
In order to use the API Gateway, the client sends an HTTPS request to the server. The server parses the request and sends a response. The response code and its structure for each resource are described in the detailed specification below. The format of the answer is JSON. The API Gateway provides GET requests (read data from the server).
The application uses the 24-hour Central European Time (CET). All queries in the API Gateway should be given in the CET time.
URL format
https://branchekataloget.dk/api-gateway/Branchekataloget/resource?parameters
- api-gateway - the beginning of the address pointing to the API Gateway resource
- Branchekataloget - identifier of the API Gateway
- resource - the resource the request refers to
- parameters - query string parameters
Example:
https://branchekataloget.dk/api-gateway/Branchekataloget/products?supplier=sup1&date-from=2022-01-30&lang=en
Authentication
Each request requires authentication, which is performed using the HTTP basic authentication method. The header contains the authentication data in the form "Basic username:password" where the phrase "username:password" is Base64 encoded. Username and password are set individually for each external system.
HTTP response status codes
The API Gateway responds with the following HTTP status codes:
- 200 OK - indicates that the request was successful
- 400 Bad Request - indicates that the request failed to complete due to errors. The user should correct the errors indicated in the response (the "errors" key in the JSON response) before resubmitting the request
- 404 Not Found - indicates that the server could not find the requested resource
Example of curl response with status "200 OK":
< HTTP/1.1 200 OK
< Date: Tue, 07 Dec 2021 12:37:13 GMT
< Server: Apache
< Vary: Accept-Encoding
< Content-Length: 194
< Content-Type: text/html; charset=UTF-8
<
...
Example of curl response with status "400 Bad Request":
< HTTP/1.1 400 Bad Request
< Date: Tue, 07 Dec 2021 11:15:16 GMT
< Server: Apache
< Content-Length: 134
< Connection: close
< Content-Type: text/html; charset=UTF-8
<
{"errors":[...]}
Example of curl response with status "404 Not Found":
< HTTP/1.1 404 Not Found
< Date: Tue, 07 Dec 2021 12:54:44 GMT
< Server: Apache
< Content-Length: 0
< Content-Type: text/html; charset=UTF-8
Get all suppliers
https://branchekataloget.dk/api-gateway/Branchekataloget/suppliers?with-keys={false/true}
Method: GET
The request is sent by an external system. API Gateway responds by sending data of all suppliers.
Query string parameters:
- with-keys (default is "false") - specifies whether to add the "suppliers" key in the response ("false"/"true")
Example of a request (curl):
curl -X GET "https://branchekataloget.dk/api-gateway/Branchekataloget/suppliers?with-keys=true" -u username:passwordExample of a response (JSON):
{
"suppliers":[
{
"identifier":"sup1",
"name":"Supplier1 Name",
"vatId":"PL5211111111",
"gln":"1234567000004",
"duns":"130692711"
},
...
],
"parameters":{
"with-keys":"true"
}
}
Main keys description:
- suppliers - array with supplier data
- parameters - correct/default query string parameters
Example of a request in a deprecated version (curl):
curl -X GET "https://branchekataloget.dk/api-gateway/Branchekataloget/suppliers?with-keys=false" -u username:passwordExample of a response in a deprecated version (JSON):
[
{
"identifier":"sup1",
"name":"Supplier1 Name",
"vatId":"PL5211111111",
"gln":"1234567000004",
"duns":"130692711"
},
...
]
Get all products of specified supplier
https://branchekataloget.dk/api-gateway/Branchekataloget/products?supplier={identifier}&lang={code}&na-values={false/true}&limit={integer}&page={integer}
Method: GET
The request is sent by an external system. API Gateway responds by sending all data of supplier products (according to the access level purchased).
Query string parameters:
- supplier (mandatory) - identifier of the supplier
- lang (mandatory) - language code acc. to ISO 639-1 (2 letter language code) in which the values of multilingual product description fields are returned
- na-values (default is "false") - specifies whether "not applicable" values (other than ETIM values) are to be included in the response ("false"/"true")
- limit (default is "100") - maximum number of products on one page (integer from 1 to 200)
- page (default is "1") - number of page with products (positive integer)
Example of a request (curl):
curl -X GET "https://branchekataloget.dk/api-gateway/Branchekataloget/products?supplier=sup1&lang=en&na-values=true" -u username:passwordExample of a response (JSON):
{
"products":[
{
"productId":"XYZ123",
"lastModifiedDate":"2018-01-02 10:17:23",
"creationDate":"2017-03-01 09:34:24",
"overallInformation":{
"gtin":"1111111111111",
"altPid":"123ABC",
"upc":"-",
"descriptionShort":"XYZ name123",
"descriptionLong":"XYZ detailed description 123",
"descriptionVeryShort":"XYZn123",
"tenderText":"XYZ nazwa123 - probably the best product on the market",
"keyword":[
"keyword 1",
"keyword 2",
"keyword 3",
...
],
"remark":[
"remark1",
"remark2",
...
],
"productStatus":[
{
"type":"core_product",
"value":"Core product"
},
{
"type":"new",
"value":"Brand new"
},
...
],
"supplier":"AAA",
"supplierPid":"ZWZ652986",
"supplierDescriptionShort":"AAA name123",
"supplierAltPid":"CCC73545",
"manufacturerName":"AA",
"manufacturerPid":"12",
"manufacturerTypeDesc":"en123",
"manufacturerAcronym":"BB",
"manufacturerAltPid":"AA12",
"brandName":"XYZ",
"productSeries":"serie 1",
"productVariation":"type 12",
"predecessorPid":[
"XYZ12",
"XY123",
...
],
"shelfLifePeriod":"99",
"batteryContained":"false",
"rohsIndicator":"false",
"ceMarking":"false",
"regionOfOrigin":"PL-LD",
"countryOfOrigin":"PL",
"productToStock":"true",
"validFrom":"2016-01-01",
"expirationDate":"2020-01-01",
"deliveryTime":"5",
"productType":"physical",
"netVolume":"0.03",
"netWeight":"12",
"netLength":"1",
"netWidth":"0.3",
"netDepth":"0.1",
"netDiameter":"1",
"discountGroupManufacturer":"KL",
"discountGroupSupplier":"KK",
"bonusGroupSupplier":"K1",
"specialTreatmentClass":[
{
"type":"MSDS",
"value":"true"
},
{
"type":"ECCN",
"value":"3A001"
},
...
],
"unNumber":"2902",
"netWeightOfHazardousSubstance":"0.001",
"volumeOfHazardousSubstances":"0.0005",
"shippingName":"UN 2902 PESTICIDE",
"packingGroup":"II",
"transportCategory":"0",
"multiplicationFactor":"254",
"limitedQuantities":"true",
"exceptedQuantities":"false",
"aggregationState":"L",
"specialProvisionId":[
"2.1",
"2.2",
...
],
"hazardClass":[
"1",
"3",
...
],
"classificationCode":"34",
"hazardLabel":[
"7A",
"7B",
...
],
"environmentalHazards":"true",
"tunnelCode":"A",
"ghsLabelCode":[
"GHS03",
"GHS05",
...
],
"ghsSignalWord":"D",
"hazardStatement":[
"H241",
"H244",
...
],
"precautionaryStatement":[
"P667",
"P754",
...
],
"liIonTested":"true",
"lithiumAmount":"1",
"batteryEnergy":"30",
"nos274":"true",
"hazardTrigger":[
"34",
"35",
...
],
"reverseChargeInfo":"false",
"pkwiu":"11.22.11.0",
"additionalPriceFactor":"0.95",
"additionalFactorInfo":"season discount",
"surchargePriceAmount":"0.01",
"warrantyBusiness":"12",
"warrantyConsumer":"24",
"reachInfo":"true",
"reachListDate":"2015-01-01",
"scipNumber":"e991v422-239c-4b49-8a42-3f4730aa51a0",
"ufiCode":"N1QV-R02N-J00M-WQD5",
"customsNumber":"12",
"countryBranchNumber":[
{
"value":"00123456",
"type":"electrical",
"country":"PL",
"supplierId":"6543"
},
{
"value":"00321654",
"type":"electrical",
"country":"DE",
"supplierId":"8765"
},
...
]
},
"etimDescription":{
"version":"9",
"classId":"EC000722",
"groupId":"EG000006",
"features":{
"EF002169":"EV000179",
"EF000025":"false",
"EF001742":[
"2",
"4.5"
],
"EF001438":"80",
"EF000116":"NA",
"EF006007":"UN",
...
}
},
"orderInformation":{
"orderUnit":"LTR",
"contentUnit":"LTR",
"noCuPerOu":"1",
"priceQuantity":"1",
"quantityMin":"1",
"quantityInterval":"1"
},
"packingInformation":[
{
"packingUnitCode":"CT",
"quantityMin":"1",
"quantityMax":"2",
"volume":"1",
"weight":"1",
"length":"1",
"width":"1",
"depth":"1",
"diameter":"1",
"packingUnitName":"f-pak",
"packageBreak":"false",
"packingParts":"1",
"gtin":"1111111111111",
"gs1_128":"(01)01234567890128(15)051231",
"packingProductId":"PACK123"
},
...
],
"priceInformation":[
{
"priceType":"net_list",
"priceAmount":"7.22",
"priceCurrency":"EUR",
"tax":"0.19",
"lowerBound":"1",
"territory":[
"FR",
"DE",
...
],
"validStartDate":"2016-06-01",
"validEndDate":"2018-06-01",
"priceFactor":"0.9",
"priceUnit":"LTR",
"priceUnitFactor":"1"
},
...
],
"mime":[
{
"mimeCode":"MD01",
"mimeSource":"https://files.etim-mapper.com/branchekataloget/image.png",
"mimeDesignation":"Main product picture"
},
...
],
"attributes":{
"M1":"value",
"L2":"false",
"S3":"v2",
"N4":"5.2",
"R5":[
"2",
"5"
],
...
}
},
{
"productId":"XYZ124",
"lastModifiedDate":"2018-01-02 11:34:22",
"creationDate":"2017-08-16 16:30:57",
...
}
],
"total":"1658",
"pages":"17",
"parameters":{
"supplier":"sup1",
"lang":"en",
"na-values":"true",
"limit":"100",
"page":"1"
}
}
Main keys description:
- products - array with product data
- total - the total number of products
- pages - the total number of pages
- parameters - correct/default query string parameters
Get all products of specified supplier modified on or after a given date
https://branchekataloget.dk/api-gateway/Branchekataloget/products?supplier={identifier}&date-from={date}&lang={code}&na-values={false/true}&limit={integer}&page={integer}
Method: GET
The request is sent by an external system. API Gateway responds by sending all data of supplier products (according to the access level purchased) modified on or after a given date.
Query string parameters:
- supplier (mandatory) - identifier of the supplier
- date-from (mandatory) - date from which products are last modified (format is "yyyy-mm-dd")
- lang (mandatory) - language code acc. to ISO 639-1 (2 letter language code) in which the values of multilingual product description fields are returned
- na-values (default is "false") - specifies whether "not applicable" values (other than ETIM values) are to be included in the response ("false"/"true")
- limit (default is "100") - maximum number of products on one page (integer from 1 to 200)
- page (default is "1") - number of page with products (positive integer)
Example of a request (curl):
curl -X GET "https://branchekataloget.dk/api-gateway/Branchekataloget/products?supplier=sup1&date-from=2022-01-30&lang=en" -u username:passwordGet products by identifier
https://branchekataloget.dk/api-gateway/Branchekataloget/products?identifier={identifier}&value={value}&lang={code}&base64={false/true}&limit={integer}&page={integer}
Method: GET
The request is sent by an external system. API Gateway responds by sending product data (according to the access level purchased) that meet the identifier conditions.
Query string parameters:
- identifier (mandatory) - one of the following identifiers of the product:
- productId
- gtin
- altPid
- upc
- manufacturerPid
- manufacturerAltPid
- supplierPid
- supplierAltPid
- ItemDesignationBK
- ItemVVSNumber
- ProcessStatus_CVL
- value (mandatory) - value of the identifier
- lang (mandatory) - language code acc. to ISO 639-1 (2 letter language code) in which the values of multilingual product description fields are returned
- base64 (default is false) - specifies whether value is encoded with Base64 ("false"/"true")
- na-values (default is "false") - specifies whether "not applicable" values (other than ETIM values) are to be included in the response ("false"/"true")
- limit (default is 100) - maximum number of products on one page (integer from 1 to 200)
- page (default is 1) - number of page with products (positive integer)
Example of a request (curl):
curl -X GET "https://branchekataloget.dk/api-gateway/Branchekataloget/products?identifier=productId&value=XYZ123&lang=en" -u username:passwordExample of a response (JSON):
{
"products":[
{
"productId":"XYZ123",
"lastModifiedDate":"2018-01-02 10:17:23",
"creationDate":"2017-08-16 16:30:57",
...
}
],
"total":"1",
"pages":"1",
"parameters":{
"identifier":"productId",
"value":"XYZ123",
"lang":"en",
"base64":"false",
"na-values":"false",
"limit":"100",
"page":"1"
}
}
Changelog
1.4 (2023-04-24)
- Parameter "na-values" in product requestsThe possibility to include "not applicable" empty values (other than ETIM) marked as "-" (dash) or to omit them in the API response.
1.3 (2023-03-28)
- The main key "suppliers" in "Get all suppliers" responseThe introduction of "suppliers" key makes it possible to send in the response not only the correct purpose of the request but also additional information (such as the parameters with which the request was handled). The use of main keys also makes it possible to further extend the response without compromising the correctness of existing requests. The "with-keys" query parameter is introduced temporarily, to replace the existing response format (without keys) with the target response format (with keys). The introduction of the query parameter with the default value "false" does not change the existing response format. However, it sensitizes the change and makes it possible to use the target answer format with the value "true". In the second stage, the "true" will become the default value, but the old response format will be available with the "false" value. In the third final stage, the "with-keys" query parameter will be deleted, and the response will always be generated with keys.
1.2 (2023-03-15)
- New response key "parameters"For the convenience of users, the responses to some requests have been equipped with information about the parameters used in the request. These include all correctly used parameters (passed explicitly and implicitly).
1.1 (2022-11-04)
- No more keys with empty values in GET responsesThe rule that elements with empty values are not returned in API responses has been generalized (exceptions to this rule have been removed).
Deprecated elements
- 2023-03-28
- The default value "false" of the "with-keys" parameter in "Get all suppliers" request: valid till 2023-06-27