Branchekataloget API Gateway 1.17 documentation

• Introduction
• Communication
• URL format
• Authentication
• HTTP response status codes
• API Gateway requests
  • Get all suppliers
  • Get all products of specified supplier(s)
  • Get all products of specified supplier(s) modified on or after a given date
  • Get products by identifier
  • Get products by identifier modified on or after a given date
• Changelog
• Deprecated elements

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":

Example of curl response with status "400 Bad Request":

Example of curl response with status "404 Not Found":

Get all suppliers

https://branchekataloget.dk/api-gateway/Branchekataloget/suppliers

Method: GET

The request is sent by an external system. API Gateway responds by sending data of all suppliers.

Example of a request (curl):

Example of a response (JSON):

Main keys description:

• suppliers - array with supplier data
• parameters - correct/default query string parameters

Get all products of specified supplier(s)

https://branchekataloget.dk/api-gateway/Branchekataloget/products?supplier={identifier}&lang={code}&na-values={false/true}&limit={integer}&page={integer}

https://branchekataloget.dk/api-gateway/Branchekataloget/products?supplier1={identifier1}&supplier2={identifier2}...&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(s) products (according to the access level purchased).

Query string parameters:

• supplier | supplier{n} (mandatory; 1 ≤ n ≤ 1000) - 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):

Example of a response (JSON):

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(s) 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}

https://branchekataloget.dk/api-gateway/Branchekataloget/products?supplier1={identifier1}&supplier2={identifier2}...&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 | supplier{n} (mandatory; 1 ≤ n ≤ 1000) - 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):

Get products by identifier

https://branchekataloget.dk/api-gateway/Branchekataloget/products?identifier={identifier}&value={value}&lang={code}&base64={false/true}&limit={integer}&page={integer}

https://branchekataloget.dk/api-gateway/Branchekataloget/products?identifier={identifier}&value1={value1}&value2={value2}...&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
  • manufacturerPid
  • supplierPid
  • supplierAltPid
  • ItemDesignationBK
  • ItemVVSNumber
  • ProcessStatus_CVL
• value | value{n} (mandatory; 1 ≤ n ≤ 1000) - 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):

Example of a response (JSON):

Get products by identifier modified on or after a given date

https://branchekataloget.dk/api-gateway/Branchekataloget/products?identifier={identifier}&value={value}&date-from={date}&lang={code}&base64={false/true}&limit={integer}&page={integer}

https://branchekataloget.dk/api-gateway/Branchekataloget/products?identifier={identifier}&value1={value1}&value2={value2}...&date-from={date}&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 and are modified on or after a given date.

Query string parameters:

• identifier (mandatory) - one of the following identifiers of the product:
  • productId
  • gtin
  • altPid
  • manufacturerPid
  • supplierPid
  • supplierAltPid
  • ItemDesignationBK
  • ItemVVSNumber
  • ProcessStatus_CVL
• value | value{n} (mandatory; 1 ≤ n ≤ 1000) - value of the identifier
• 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
• 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):

Changelog

1.17 (2024-10-30)

• Language(s) of attachments
  Attachment element has been completed with an optional "language" field (multiple choice).
• Increase of the filtering limits for supplier and identifier values from 200 to 1000
  When filtering products by suppliers or identifiers, up to 1000 values can be entered.

1.16 (2024-08-22)

• Migration of "mime" to "attachments"
  As the application has been adapted to the xChange standard (replacing BMEcat), MIME elements have been replaced with ATX (attachment) elements. The structures/sections of MIME elements have been replaced with their ATX counterparts: "attachments". During the transition period, attachments will also be transmitted in their existing MIME form (see the deprecated elements).

1.15 (2024-06-19)

• Adding new fields in the "lca" section of the product response ("referenceFlowUnit", "reviewType")
  The LCA section has been completed with the two fields missing in the previous releases.
• New attribute type: "multiselect"
  The new attribute "multiselect" allows to define a set of allowed values. Each predefined value has an identifier (unique within the attribute) and a translation in the languages used. For a specific product, the attribute can take a subset of the allowed values.
• Restoration of the "issueDate" and "expirationDate" fields in MIME
  Fields previously removed to simplify the MIME description have been restored for compatibility with the planned migration of MIME to attachments (ATX).

1.14 (2024-05-29)

• The new field of product description: "factorOfCustomsCommodityCode"
  This field has been added to complete the customs information in xChange format.

1.13 (2024-04-24)

• Change of the key name: "supplierDescriptionShort" -> "supplierProductName" in the product data
  The key name has been changed to be more intuitive and distinguishable from other description fields and in accordance with the previously changed key name "descriptionShort" -> "productName".

1.12 (2024-04-18)

• Adjustment of fields to the new xChange format
  The second stage of adapting field types, formats and names to the new xChange standard, replacing BMEcat, has been performed (list of changes).
• Renaming of fields (keys)
  The names of the following fields were changed, adapting them in meaning to the new xChange format:

  • "descriptionShort" ⇒ "productName" (overall)
  • "descriptionLong" ⇒ "longDescription" (overall)
  • "descriptionVeryShort" ⇒ "minimalDescription" (overall)
  • "tenderText" ⇒ "marketingText" (overall)
  • "remark" ⇒ "applicationInstruction" (overall)
  • "manufacturerAcronym" ⇒ "manufacturerShortName" (overall)
  • "productSeries" ⇒ "brandSeries" (overall)
  • "productVariation" ⇒ "brandVariation" (overall)
  • "productToStock" ⇒ "productInStock" (overall)
  • "netWeightOfHazardousSubstance" ⇒ "netWeightOfHazardousSubstances" (overall)
  • "discountGroupSupplier" ⇒ "discountGroupId" (overall)
  • "bonusGroupSupplier" ⇒ "bonusGroupId" (overall)
  • "shippingName" ⇒ "properShippingName" (overall)
  • "specialProvisionId" ⇒ "specialProvision" (overall)
  • "reachInfo" ⇒ "reachIndicator" (overall)
  • "reachListDate" ⇒ "reachDate" (overall)
  • "customsNumber" ⇒ "customsCommodityCode" (overall)
• Adaptation of the attribute value format to the xChange characteristics
  The value formats of the available attribute types have been adapted to the format of the so-called "characteristics" in the xChange standard.

1.11 (2024-03-26)

• Adjustment of fields to the new xChange product data exchange standard
  The introduction of a new product data exchange format called xChange, replacing the previously used BMEcat format, required the adaptation of field types, formats and names to the new standard (list of changes)
• Renaming of fields (keys)
  The names of the following fields were changed, adapting them in meaning to the new xChange format:

  • "netDepth" ⇒ "netHeight" (overall)
  • "noCuPerOu" ⇒ "contentUnitQuantity" (order)
  • "depth" ⇒ "height" (packing)
  • "quantityMin" & "quantityMax" ⇒ "quantity" (packing)
  • "tax" ⇒ "vat" (price)

1.10 (2023-12-05)

• Link to EPD in LCA data
  A link to the EPD document has been added to the LCA data.

1.9 (2023-10-17)

• Dynamic LCA (via API)
  The way of searching and accessing Life Cycle Assessment (LCA) data has been changed from static to dynamic (via API). Access to many different LCA databases has been enabled. When referring to LCA data, the version has been omitted (the reference is always to the latest version of the data).

1.8 (2023-09-20)

• Reference flow information in LCA data
  LCA data has been completed with "Reference flow" information.

1.7 (2023-09-05)

• GWP values
  Values of the Global Warming Potential (GWP) indicator can now be retrieved via the API gateway along with other product data.

1.6 (2023-08-03)

• Get products by identifier with many values
  In addition to the basic request for retrieving details of a single product with a given identifier (single value), an additional request has been created to retrieve the products with the indicated values (up to 200) of the selected identifier in a single query.
• Get products by identifier with many values modified on or after a given date
  The request for products by an identifier with multiple values can also be sent with a specified date (products modified on or after a given date are returned).

1.5 (2023-06-21)

• Get all products of specified suppliers
  In addition to the basic request for retrieving the products of a single supplier, an additional request has been created that allows retrieving the products of multiple suppliers (up to 200) in a single query.

1.4 (2023-04-24)

• Parameter "na-values" in product requests
  The 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" response
  The 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 responses
  The rule that elements with empty values are not returned in API responses has been generalized (exceptions to this rule have been removed).

Deprecated elements

• 2024-09-03
  • "country-of-origin-multiple" parameter in all "products" requests: valid till 2024-12-02
• 2024-08-22
  • MIME section ("mime" values) in the product description: valid till 2024-11-21 (successor: "attachments" section)
• 2024-04-24
  • Key "supplierDescriptionShort" in the product description ("overallInformation" values): valid till 2024-09-02 (successor: "supplierProductName")
• 2024-04-18
  • Key "descriptionShort" in the product description ("overallInformation" values): valid till 2024-09-02 (successor: "productName")
  • Key "descriptionLong" in the product description ("overallInformation" values): valid till 2024-09-02 (successor: "longDescription")
  • Key "descriptionVeryShort" in the product description ("overallInformation" values): valid till 2024-09-02 (successor: "minimalDescription")
  • Key "remark" in the product description ("overallInformation" values): valid till 2024-09-02 (successor: "applicationInstruction"; single multilingual field)
  • Key "manufacturerAcronym" in the product description ("overallInformation" values): valid till 2024-09-02 (successor: "manufacturerShortName")
  • Key "productSeries" in the product description ("overallInformation" values): valid till 2024-09-02 (successor: "brandSeries")
  • Key "productVariation" in the product description ("overallInformation" values): valid till 2024-09-02 (successor: "brandVariation")
  • Key "productToStock" in the product description ("overallInformation" values): valid till 2024-09-02 (successor: "productInStock")
  • Key "netWeightOfHazardousSubstance" in the product description ("overallInformation" values): valid till 2024-09-02 (successor: "netWeightOfHazardousSubstances")
  • Key "discountGroupSupplier" in the product description ("overallInformation" values): valid till 2024-09-02 (successor: "discountGroupId")
  • Key "bonusGroupSupplier" in the product description ("overallInformation" values): valid till 2024-09-02 (successor: "bonusGroupId")
  • Key "shippingName" in the product description ("overallInformation" values): valid till 2024-09-02 (successor: "properShippingName")
  • Key "specialProvisionId" in the product description ("overallInformation" values): valid till 2024-09-02 (successor: "specialProvision")
  • Key "reachInfo" in the product description ("overallInformation" values): valid till 2024-09-02 (successor: "reachIndicator")
  • Key "reachListDate" in the product description ("overallInformation" values): valid till 2024-09-02 (successor: "reachDate")
  • Key "customsNumber" in the product description ("overallInformation" values): valid till 2024-09-02 (successor: "customsCommodityCode")
  • The default value "false" of the "country-of-origin-multiple" parameter in all "products" requests: valid till 2024-09-02
• 2024-03-26
  • Key "netDepth" in the product description ("overallInformation" values): valid till 2024-06-25 (successor: "netHeight")
  • Key "noCuPerOu" in the product description ("orderInformation" values): valid till 2024-06-25 (successor: "contentUnitQuantity")
  • Key "depth" in the product description ("packingInformation" values): valid till 2024-06-25 (successor: "height")
  • Keys "quantityMin" and "quantityMax" in the product description ("packingInformation" values): valid till 2024-06-25 (successor: "quantity")
  • Key "tax" in the product description ("priceInformation" values): valid till 2024-06-25 (successor: "vat")
• 2023-07-18
  • "with-keys" parameter in "Get all suppliers" request: valid till 2023-10-17
• 2023-03-28
  • The default value "false" of the "with-keys" parameter in "Get all suppliers" request: valid till 2023-07-17