API documentation

RESTful API 5.10 documentation

Introduction
Communication
URL format
Authentication
HTTP response status codes
Limits
RESTful API: products
RESTful API: labels
RESTful API: attributes
RESTful API: relations by attribute
RESTful API: suppliers
RESTful API: buyers
RESTful API: categories
RESTful API: synchronization triggers
- Run synchronization trigger
- Check status of synchronization trigger
External API: products
- Handle a list of new, modified and deleted products

Introduction

The purpose of the document is to define the communication principles of the application with systems of external companies. The external systems should develop their own RESTful API that allows the mutual access to the available resources of both sides. Both API interfaces should work according to the same principles described below.

Communication

In order to use the RESTful API, 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 provides GET, PUT and DELETE requests. GET is used to read data from the server, PUT to update data on the server (create or modify), and DELETE to remove the existing data from the server. Not all resources must have all types of requests (see the specification for details).

The application uses the 24-hour Central European Time (CET). All queries in the API should be given in the CET time.

URL format

https://epim.one/api/api-identifier/resource?parameters

api - the beginning of the address pointing to the API resource
api-identifier - API identifier (unique for each company)
resource - the resource the request refers to
parameters - query string parameters

Example:

https://epim.one/api/api-identifier/products?date-from=2023-01-21

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 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
< 
{"all":"1","unique":"1","new":"0","modified":"1","classified":"0","reclassified":"0","deletedClassifications":"0","deletedRelatedProducts":"1","createdRelatedProducts":"2","limitExceeded":"0","parameters":{"new":"add","existing":"replace","empty":"false"}}

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":["Limit parameter should be set to integer from the range [1, 100000]", "Page parameter should be set to positive integer"]}

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

Limits

1 API user = 1 IP address. An API user is created for communication with a single external system. In this sense, each API user corresponds to one unique IP address. In exceptional situations, a pool of IP addresses (for systems running in the cloud and changing IP address) or no restrictions on IP addresses (API supplier users) may be allowed, but in such cases, the number of IP addresses using a given API user is monitored and should not exceed one address per day.

For security and performance reasons, the daily number of API requests is limited for each API user. It is proportional to the limit of products in the account (regular API user) or the number of supplier products (API supplier user). The limits are chosen in such a way that they allow the entire product information to be read/written or deleted multiple times, as well as regularly querying for any changes. Since unreasonable management of API requests may cause the limits to be exceeded, we would like to point out that each GET type API request can retrieve detailed information about 100 products, and that a large number of products can be modified in PUT type requests (the limitation here is the 16 MB JSON file, which constitutes the attachment/body of a such type of request).

List of all IDs of products modified on or after a given date | RESTful API: products

https://epim.one/api/api-identifier/products?date-from={date}&as-supplier={identifier}

Method: GET

The request is sent by an external system. The application responds by sending IDs of products modified on or after a given date.

Query string parameters:

date-from (default is "2000-01-01") - date from which products are last modified (format is "yyyy-mm-dd")
as-supplier (optional; only for accounts with suppliers; not for supplier users) - possibility to read product information "as a supplier", so that the products are accessed on the basis of the pair: "supplier"-"supplierPid", instead of on the basis of the "productId" (for details see "Get product data as supplier" section)

Example of a request (curl):

curl -X GET "https://epim.one/api/api-identifier/products?date-from=2022-02-15" -u username:password

Example of a response (JSON):

{
  "productIds":[
    "XYZ123",
    "XYZ134",
    ...
  ],
  "total":"2634",
  "parameters":{
    "date-from":"2022-02-15"
  }
}

Fields description:

productIds - all IDs of products modified on or after a given date
total - number of all products modified on or after a given date
parameters - correct/default query string parameters

Product filtering | RESTful API: products

https://epim.one/api/api-identifier/products/filter?as-supplier={identifier}

Method: GET

The request is sent by an external system. The application responds by sending IDs of the products that meet the filter conditions and their last modification dates (according to specified limit and page). In case of incorrect filter parameters, basic information about the detected errors is returned.

Query string parameters:

as-supplier (optional; only for accounts with suppliers; not for supplier users) - possibility to read product information "as a supplier", so that the products are accessed on the basis of the pair: "supplier"-"supplierPid", instead of on the basis of the "productId" (for details see "Get product data as supplier" section)

Example of a request (curl):

curl -X GET "https://epim.one/api/api-identifier/products/filter" -u username:password -H "Content-Type: application/json" --data-binary "@filterData.json"

The filterData.json file example (UTF-8 encoded):

{  
  "descriptionShort":{  
    "pl":"kana"
  },
  "gtin":0,
  "attributes":{  
    "M1":{  
      "pl":"wart"
    },
    "L2":[
      "false"
    ],
    "S3":[
      "v1",
      "v2"
    ],
    "N4":"4",
    "R5":{
      "from":"1",
      "to":"3"
    }
  },
  "labels":{  
    "withType":"at_least_one",
    "with":[  
      "Sold",
      "Gold"
    ],
    "without":[
      "Public"  
    ]
  },
  "lca":{  
    "database":[
      "OEKOBAU.DAT"
    ],
    "uuid":"4df"
  },
  "hazardClass":{  
    "withType":"at_least_one",
    "with":[  
      "1",
      "2.1",
      "2.2"
    ],
    "without":[
      "9"  
    ]
  },
  "totalDescriptionCompleteness":{
    "from":"20",
    "to":"40"
  },
  "lastModifiedDate":{
    "type":"last",
    "number":"2",
    "unit":"day",
    "includingCurrent":"true"
  },
  "creationDate":{
    "type":"range",
    "to":"2016-06-01 00:00:00"
  }
}

Filter field types:

text - you can use wildcards
array - array of values (up to 200)
range - valid filter keys:
- from - from specified value
- to - to specified value
labels - valid filter keys:
- withType - one of the following values (applies to labels from the "with" field):
  - at_least_one (default value)
  - at_least_selected
  - only_selected
- with - array of label identifiers (searching for products WITH these labels)
- without - array of label identifiers (searching for products WITHOUT these labels)
multi-valued - valid filter keys:
- withType - one of the following values (applies to values from the "with" field):
  - at_least_one (default value)
  - at_least_selected
  - only_selected
- with - array of values (searching for products WITH these values)
- without - array of values (searching for products WITHOUT these values)
date - valid filter keys:
- type - possible values:
- number (filter "last") - number of last hours/days/weeks covering the filtered dates [1-999]
- unit (filter "last") - possible values:
- includingCurrent (filter "last") - possible values:
- from (filter "range") - from specified date in format "YYYY-MM-DD"
- to (only for "range" type filter) - to specified date in format "YYYY-MM-DD"
datetime - valid filter keys:
- type - possible values:
- number (filter "last") - number of last hours/days/weeks covering the filtered dates [1-999]
- unit (filter "last") - possible values:
- includingCurrent (filter "last" and not for minute/hour unit) - possible values:
- from (filter "range") - from specified date in format "YYYY-MM-DD HH:MM:SS"
- to (filter "range") - to specified date in format "YYYY-MM-DD HH:MM:SS"
pdc - valid filter keys:
- from - from specified integer value [0-100]
- to - to specified integer value [0-100]
lca - valid filter keys:
- database - array of LCA database identifiers:
  - BRE_EPD_Hub
  - ECOSMDP
  - ENVIRONDEC
  - EPD_IRELAND
  - EPD_ITALY
  - EPD-NORWAY_DIGI
  - IBU_DATA
  - ITBPOLAND
  - OEKOBAU.DAT
  - MRPI
- uuid - UUID of the dataset (filter field type: text)
language - keys corresponding to the two-letter language abbreviations, for example: "en", "pl"
identifiers - values corresponding to identifiers of the given element
true-false - valid filter values:
- true - meaning "yes"
- false - meaning "no"
reach-info - valid filter values:
- no data
- true - meaning "contains a SVHC in excess of 0.1% product weight"
- false - meaning "does not contain any SVHC in excess of 0.1% product weight"
hazard-class - valid filter values:
- 1
- 2.1
- 2.2
- 2.3
- 3
- 4.1
- 4.2
- 4.3
- 5.1
- 5.2
- 6.1
- 6.2
- 7
- 8
- 9
country - values corresponding to the two-letter country codes, for example: "PL", "FR"
etim-class - values corresponding to ETIM class codes ("ECxxxxxx")
0 - search for empty values (set the value to 0 integer, without brackets)
1 - search for not empty values (set the value to 1 integer, without brackets)
2 - search for not applicable values (set the value to 2 integer, without brackets)

Remarks:

"text" fields can be also used as an array of values (up to 200)
the default operator applied when filtering with an array of values is the logical "OR"

Description of filter fields:

productId - filter by product ID (filter field type: text)
gtin - filter by GTIN (filter field type: text | 0 | 1 | 2)
altPid - filter by alternative product ID (filter field type: text | 0 | 1 | 2)
upc - filter by UPC (filter field type: text | 0 | 1 | 2)
descriptionShort - filter by product name (filter field type: language | text | 0 | 1 | 2)
descriptionLong - filter by product long description (filter field type: language | text | 0 | 1 | 2)
descriptionVeryShort - filter by product invoice description (filter field type: language | text | 0 | 1 | 2)
tenderText - filter by product markieting text (filter field type: language | text | 0 | 1 | 2)
supplier - filter by supplier identifier (filter field type: identifiers | array | 0 | 1)
supplierPid - filter by supplier product ID (filter field type: text | 0 | 1)
supplierDescriptionShort - filter by supplier product name (filter field type: language | text | 0 | 1 | 2)
supplierAltPid - filter by supplier alternative product ID (filter field type: text | 0 | 1 | 2)
manufacturerName - filter by manufacturer name (filter field type: text | 0 | 1 | 2)
manufacturerPid - filter by manufacturer product ID (filter field type: text | 0 | 1 | 2)
manufacturerTypeDesc - filter by manufacturer type description (filter field type: language | text | 0 | 1 | 2)
manufacturerAltPid - filter by manufacturer alternative product ID (filter field type: text | 0 | 1 | 2)
brandName - filter by brand name (filter field type: text | 0 | 1 | 2)
productSeries - filter by product series (filter field type: language | text | 0 | 1 | 2)
productVariation - filter by product variation (filter field type: language | text | 0 | 1 | 2)
shelfLifePeriod - filter by shelf life (filter field type: text | 0 | 1 | 2)
batteryContained - filter by indicating whether product contains an included battery (filter field type: true-false | array | 0 | 1 | 2)
ceMarking - filter by indicating whether product has the CE mark (filter field type: true-false | array | 0 | 1 | 2)
countryOfOrigin - filter by product country of origin (filter field type: country | array | 0 | 1 | 2)
validFrom - filter by validity starting date of the product (filter field type: date | 0 | 1 | 2)
expirationDate - filter by validity expiration date of the product (filter field type: date | 0 | 1 | 2)
deliveryTime - filter by product delivery time (filter field type: text | 0 | 1 | 2)
discountGroupSupplier - filter by discount group of the supplier (filter field type: text | 0 | 1 | 2)
unNumber - filter by UN number (filter field type: text | 0 | 1 | 2)
liIonTested - filter by indicating whether the Li-ion cell has been tested (filter field type: true-false | array | 0 | 1 | 2)
hazardClass - filter by hazard classes (filter field type: hazard-class | multi-valued | 0 | 1 | 2)
reachInfo - filter by REACH info (filter field type: reach-info | array | 0 | 1 | 2)
scipNumber - filter by SCIP number (filter field type: text | 0 | 1 | 2)
customsNumber - filter by customs number (filter field type: text | 0 | 1 | 2)
classId - filter by ETIM class ID (filter field type: etim-class | array | 0 | 1)
attributes - filter by values of global attributes (the keys are attribute identifiers); the type of filter depends on the type of attribute:
- multilingual text (filter field type: language | text | 0 | 1 | 2)
- text (filter field type: text | 0 | 1 | 2)
- numeric (filter field type: text | 0 | 1 | 2)
- range (filter field type: range | 0 | 1 | 2)
- logical (filter field type: true-false | array | 0 | 1 | 2)
- date (filter field type: date | 0 | 1 | 2)
- select (filter field type: identifiers | array | 0 | 1 | 2)
lca - filter by LCA (filter field type: lca | 0 | 1)
categoryTreeIdentifier - filter by identifier of category tree (filter field type: identifiers | array | 0 | 1)
categoryIdentifier - filter by identifier of category (filter field type: identifiers | array | 0 | 1)
labels - filter by labels (filter field type: labels | 0 | 1)
totalDescriptionCompleteness - filter by (default) total completeness of product description (filter field type: pdc)
generalDescriptionCompleteness - filter by (default) completeness of product overall information (filter field type: pdc)
etimDescriptionCompleteness - filter by (default) completeness of ETIM description (filter field type: pdc)
orderDescriptionCompleteness - filter by (default) completeness of product order information (filter field type: pdc)
packingDescriptionCompleteness - filter by (default) completeness of product packing information (filter field type: pdc)
priceDescriptionCompleteness - filter by (default) completeness of product price information (filter field type: pdc)
mimeDescriptionCompleteness - filter by (default) completeness of product MIME information (filter field type: pdc)
attributesDescriptionCompleteness - filter by (default) completeness of product attribute values (filter field type: pdc)
totalDescriptionCompletenessUserDefined - filter by (user-defined) total completeness of product description (filter field type: pdc)
generalDescriptionCompletenessUserDefined - filter by (user-defined) completeness of product overall information (filter field type: pdc)
etimDescriptionCompletenessUserDefined - filter by (user-defined) completeness of ETIM description (filter field type: pdc)
orderDescriptionCompletenessUserDefined - filter by (user-defined) completeness of product order information (filter field type: pdc)
packingDescriptionCompletenessUserDefined - filter by (user-defined) completeness of product packing information (filter field type: pdc)
priceDescriptionCompletenessUserDefined - filter by (user-defined) completeness of product price information (filter field type: pdc)
mimeDescriptionCompletenessUserDefined - filter by (user-defined) completeness of product MIME information (filter field type: pdc)
attributesDescriptionCompletenessUserDefined - filter by completeness of product attribute values (filter field type: pdc)
lastModifiedDate - filter by last modified date of the products (filter field type: datetime)
generalLastModifiedDate - filter by last modified date of product overall information (filter field type: datetime)
etimLastModifiedDate - filter by last modified date of ETIM description (filter field type: datetime)
orderLastModifiedDate - filter by last modified date of product order information (filter field type: datetime)
packingLastModifiedDate - filter by last modified date of product packing information (filter field type: datetime)
priceLastModifiedDate - filter by last modified date of product price information (filter field type: datetime)
mimeLastModifiedDate - filter by last modified date of product MIME information (filter field type: datetime)
attributesLastModifiedDate - filter by last modified date of product attribute values (filter field type: datetime)
lcaLastModifiedDate - filter by last modified date of product LCA (Life Cycle Assessment) (filter field type: datetime)
additionalTechnicalDescriptionLastModifiedDate - filter by last modified date of product additional technical description (filter field type: datetime)
seoLastModifiedDate - filter by last modified date of product SEO information (filter field type: datetime)
wwwLastModifiedDate - filter by last modified date of product WWW information (filter field type: datetime)
relatedProductsLastModifiedDate - filter by last modified date of related products (filter field type: datetime)
relationsByAttributeLastModifiedDate - filter by last modified date of product relations by attribute (filter field type: datetime)
categoriesLastModifiedDate - filter by last modified date of product categories (filter field type: datetime)
labelsLastModifiedDate - filter by last modified date of product labels (filter field type: datetime)
creationDate - filter by creation date of the products (filter field type: datetime)
modifiedBy - filter by user name who last modified a product (filter field type: text)
generalModifiedBy - filter by user name who last modified product overall information (filter field type: text)
etimModifiedBy - filter by user name who last modified ETIM description (filter field type: text)
orderModifiedBy - filter by user name who last modified product order information (filter field type: text)
packingModifiedBy - filter by user name who last modified product packing information (filter field type: text)
priceModifiedBy - filter by user name who last modified product price information (filter field type: text)
mimeModifiedBy - filter by user name who last modified product MIME information (filter field type: text)
attributesModifiedBy - filter by user name who last modified product attribute values (filter field type: text)
lcaModifiedBy - filter by user name who last modified product LCA (Life Cycle Assessment) (filter field type: text)
additionalTechnicalDescriptionModifiedBy - filter by user name who last modified product additional technical description (filter field type: text)
seoModifiedBy - filter by user name who last modified product SEO information (filter field type: text)
wwwModifiedBy - filter by user name who last modified product WWW information (filter field type: text)
relatedProductsModifiedBy - filter by user name who last modified related products (filter field type: text)
relationsByAttributeModifiedBy - filter by user name who last modified product relations by attribute (filter field type: text)
categoriesModifiedBy - filter by user name who last modified product categories (filter field type: text)
labelsModifiedBy - filter by user name who last modified product labels (filter field type: text)
createdBy - filter by user name who created a product (filter field type: text)

Example of a response (JSON):

{
  "productIds":[
    "XYZ123",
    "XYZ519",
    ...
  ],
  "total":"43",
  "parameters":[]
}

Fields description:

productIds - all IDs of products that meet the filter conditions
total - number of all products that meet the filter conditions
parameters - correct/default query string parameters

Example of error response:

{
  "errors":[
    "incorrect value of \"withType\" in \"labels\"",
    "incorrect value of \"totalDescriptionCompleteness\""
  ]
}

Get product data | RESTful API: products

https://epim.one/api/api-identifier/products?etim-version={number}&completeness={false/true}&dates-by-type={false/true}&na-values={false/true}&as-supplier={identifier}

Method: GET

Request is sent by an external system. The application responds with the detailed information of the specified product(s). It is necessary to send the list of product IDs (as a JSON data) that you want to get.

You can get by default up to 100 products in one GET request.

Query string parameters:

etim-version (default is "9") - specifies the version of ETIM classification ("9", "8", "7" or "6")
completeness (default is "true") - specifies whether the part "descriptionCompleteness" are to be included in the response ("false"/"true")
dates-by-type (default is "true") - specifies whether the part "lastModifiedDateByType" are to be included in the response ("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")
as-supplier (optional; only for accounts with suppliers; not for supplier users) - possibility to read product information "as a supplier", so that the products are accessed on the basis of the pair: "supplier"-"supplierPid", instead of on the basis of the "productId" (for details see "Get product data as supplier" section)

Example of a request (curl):

curl -X GET "https://epim.one/api/api-identifier/products?completeness=true&dates-by-type=true&na-values=true" -u username:password -H "Content-Type: application/json" --data-binary "@productsIDs.json"

The productsIDs.json file example (UTF-8 encoded):

[  
  "XYZ123",
  "XYZ124"
]

Example of a response (JSON):

{
  "products":[  
    {
      "productId":"XYZ123",
      "overallInformation":{
        "gtin":"1111111111111",
        "altPid":"123ABC",
        "upc":"-",
        "descriptionShort":{  
          "pl":"XYZ nazwa123",
          "en":"XYZ name123",
          ...
        },
        "descriptionLong":{  
          "pl":"XYZ opis szczegółowy 123",
          "en":"XYZ detailed description 123",
          ...
        },
        "descriptionVeryShort":{  
          "pl":"XYZ-n123",
          "en":"XYZn123",
          ...
        },
        "tenderText":{  
          "pl":"XYZ nazwa123 - prawdopodobnie najlepszy produkt na rynku",
          "en":"XYZ nazwa123 - probably the best product on the market",
          ...
        },
        "keyword":{  
          "pl":[  
            "słowo kluczowe 1",
            "słowo kluczowe 2",
            "słowo kluczowe 3",
            ...
          ],
          "en":[  
            "keyword 1",
            "keyword 2",
            "keyword 3",
            ...
          ],
          ...
        },
        "remark":{  
          "pl":[  
            "uwaga1",
            "uwaga2",
            ...
          ],
          "en":[  
            "remark1",
            "remark2",
            ...
          ],
          ...
        },
        "productStatus":{  
          "pl":[  
            {  
              "type":"core_product",
              "value":"Asortyment podstawowy"
            },
            {  
              "type":"new",
              "value":"Fabrycznie nowy"
            },
            ...
          ],
          "en":[  
            {  
              "type":"core_product",
              "value":"Core product"
            },
            {  
              "type":"new",
              "value":"Brand new"
            },
            ...
          ],
          ...
        },
        "supplier":"AAA",
        "supplierPid":"ZWZ652986",
        "supplierDescriptionShort":{  
          "pl":"AAA nazwa123",
          "en":"AAA name123",
          ...
        },
        "supplierAltPid":"CCC73545",
        "manufacturerName":"AA",
        "manufacturerPid":"12",
        "manufacturerTypeDesc":{  
          "pl":"pl123",
          "en":"en123",
          ...
        },
        "manufacturerAcronym":"BB",
        "manufacturerAltPid":"AA12",
        "brandName":"XYZ",
        "productSeries":{  
          "pl":"seria 1",
          "en":"serie 1",
          ...
        },
        "productVariation":{  
          "pl":"typ 12",
          "en":"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":{
          "pl":"UN 2902 PESTYCYD",
          "en":"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":{  
          "pl":"promocja sezonowa",
          "en":"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":{  
            "pl":"pak",
            "en":"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":{  
            "pl":"https://files.epim.one/xyz/zdjecie1",
            "en":"https://files.epim.one/xyz/zdjecie1",
            ...
          },
          "mimeDesignation":{  
            "pl":"Główne zdjęcie produktu",
            "en":"Main product picture",
            ...
          }
        },
        ...
      ],
      "attributes":{  
        "M1":{  
          "pl":"wartosc",
          "en":"value",
          ...
        },
        "L2":"false",
        "S3":"v2",
        "N4":"5.2",
        "R5":[  
          "2",
          "5"
        ],
        ...
      },
      "lca":{
        "database":"OEKOBAU.DAT",
        "uuid":"301c6f09-ce88-4818-96c3-e420fe799d62",
        "link":"https://www.oekobaudat.de/OEKOBAU.DAT/resource/processes/301c6f09-ce88-4818-96c3-e420fe799d62"
      },
      "additionalTechnicalDescription":{  
        "tech data 1 name":"tech data 1 value",
        "tech data 2 name":"tech data 2 value",
        ...
      },
      "seo":{
        "index":"true",
        "follow":"false",
        "canonical":{
          "pl":"https://website.com/pl/page",
          "en":"https://website.com/en/page",
          ...
        },
        "url":{
          "pl":"https://website.com/pl/page/product/xyz123",
          "en":"https://website.com/en/page/product/xyz123",
          ...
        },
        "metaDescription":{
          "pl":"XYZ123 jest przykladowym produktem na naszej stronie",
          "en":"XYZ123 is an example product on our website",
          ...
        },
        "metaKeywords":{
          "pl":"xyz123, produkt, etim, klasyfikacja",
          "en":"xyz123, product, etim, classification",
          ...
        },
        "title":{
          "pl":"Produkt XYZ123 | Website.com",
          "en":"XYZ123 product | Website.com",
          ...
        },
        "h1":{
          "pl":"Produkt XYZ123",
          "en":"XYZ123 product",
          ...
        }
      },
      "www":[  
        {  
          "header":{  
            "pl":"Laptop i tablet w jednym",
            "en":"Laptop and tablet in one",
            ...
          },
          "text":{  
            "pl":"Laptop 2 w 1 łączy w sobie lekkość, mobilność oraz dotykowe ekrany tabletów z <strong>mocą obliczeniową</strong> notebooków. ...",
            "en":"2 in 1 laptop combines lightness, mobility and touch screens of tablets with <strong>the computing power</strong> of notebooks. ...",
            ...
          },
          "imageUrl":{  
            "pl":"https://files.epim.one/xyz/image-pl.jpg",
            "en":"https://files.epim.one/xyz/image-en.jpg",
            ...
          },
          "imageTitle":{  
            "pl":"Laptop 2 w 1",
            "en":"2 in 1 laptop",
            ...
          },
          "imageAlt":{  
            "pl":"zdjęcie laptopa 2 w 1",
            "en":"picture of 2 in 1 laptop",
            ...
          }
        },
        ...
      ],
      "relatedProducts":[  
        {  
          "relatedProductId":"ABC123",
          "relationType":"accessories",
          "quantity":"1",
          "description":{  
            "pl":"akcesorium do produktu",
            "en":"product accessory",
            ...
          }
        },
        ...
      ],
      "relationsByAttribute":[  
        "relation1",
        "relation2",
        ...
      ],
      "categories":{  
        "leaves":{  
          "TC1":[  
            "C1",
            "SC5",
            ...
          ],
          ...
        },
        "paths":{  
          "TC1":[  
            "/C1",
            "/C5/SC5",
            ...
          ],
          ...
        },
        "descriptionCompleteness":{  
          "TC1":"83",
          ...
        }
      },
      "labels":[  
        "label1",
        "label2",
        ...
      ],
      "descriptionCompleteness":{  
        "totalDescriptionCompleteness":"90",
        "generalDescriptionCompleteness":"80",
        "etimDescriptionCompleteness":"95",
        "orderDescriptionCompleteness":"100",
        "packingDescriptionCompleteness":"100",
        "priceDescriptionCompleteness":"91",
        "mimeDescriptionCompleteness":"80",
        "attributesDescriptionCompleteness":"80",
        "totalDescriptionCompletenessUserDefined":"86",
        "generalDescriptionCompletenessUserDefined":"81",
        "etimDescriptionCompletenessUserDefined":"85",
        "orderDescriptionCompletenessUserDefined":"100",
        "packingDescriptionCompletenessUserDefined":"100",
        "priceDescriptionCompletenessUserDefined":"70",
        "mimeDescriptionCompletenessUserDefined":"85",
        "attributesDescriptionCompletenessUserDefined":"75"
      },
      "lastModifiedDateByType":{  
        "general":[  
          "date":"2018-01-02 10:17:23",
          "modifiedBy":"user2"
        ],
        "etim":[  
          "date":"2017-09-14 12:45:04",
          "modifiedBy":"user1"
        ],
        ...
      },
      "lastModifiedDate":"2018-01-02 10:17:23",
      "modifiedBy":"user2",
      "creationDate":"2017-03-01 09:34:24",
      "createdBy":"user1"
    },
    {  
      "productId":"XYZ124",
      ...
    }
  ],
  "parameters":{
    "etim-version":"9",
    "completeness":"true",
    "dates-by-type":"true",
    "na-values":"true"
  }
}

Fields description:

products - detailed information of the specified product(s):
- productId - unique identifier of product
- overallInformation - part of the general product information
- etimDescription - part of the ETIM description
- orderInformation - part of the product order information
- packingInformation - part of the product packaging information
- priceInformation - part of the product price information
- mime - part of the product MIME information
- attributes - values of product attributes
- lca - part of the product LCA (Life Cycle Assessment)
- additionalTechnicalDescription - additional technical features of the product (they can be used in automatic classification of products)
- seo - data to improve the positioning in search engines results
- www - information to facilitate and enrich the presentation of product information on websites
- relatedProducts - part of the related products information
- relationsByAttribute - product relations by attribute
- categories - product categories
- labels - product labels
- descriptionCompleteness - part with the completeness indicators (given as a percentage) of the ETIM/product description (conform to default or user-defined completeness mask)
- lastModifiedDateByType - part with the last modification dates by product information type
- lastModifiedDate - date of the last modification in the format: YYYY-MM-DD HH:MM:SS
- modifiedBy - name of the user who made the last modification of the product
- creationDate - date of the creation in the format: YYYY-MM-DD HH:MM:SS
- createdBy - name of the user who created the product
parameters - correct/default query string parameters

Get product data in a language-dependent version | RESTful API: products

https://epim.one/api/api-identifier/products?lang={code}&etim-version={number}&completeness={false/true}&dates-by-type={false/true}&na-values={false/true}&as-supplier={identifier}

Method: GET

Request is sent by an external system. The application responds with the detailed information of the specified product(s). All the coded information is sent in the requested language. It is necessary to send the list of product IDs (as a JSON data) that you want to get.

You can get by default up to 100 products in one GET request.

Query string parameters:

lang - required language code acc. to ISO 639-1 (2 letter language code, for example, "en" for English, "pl" for Polish etc.)
etim-version (default is "9") - specifies the version of ETIM classification ("9", "8", "7" or "6")
completeness (default is "true") - specifies whether the part "descriptionCompleteness" are to be included in the response ("false"/"true")
dates-by-type (default is "true") - specifies whether the part "lastModifiedDateByType" are to be included in the response ("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")
as-supplier (optional; only for accounts with suppliers; not for supplier users) - possibility to read product information "as a supplier", so that the products are accessed on the basis of the pair: "supplier"-"supplierPid", instead of on the basis of the "productId" (for details see "Get product data as supplier" section)

Example of a request (curl):

curl -X GET "https://epim.one/api/api-identifier/products?lang=en&na-values=true" -u username:password -H "Content-Type: application/json" --data-binary "@productsIDs.json"

The productsIDs.json file example (UTF-8 encoded):

[  
  "XYZ123",
  "XYZ124"
]

Example of a response (JSON):

{
  "products":[  
    {  
      "productId":"XYZ123",
      "overallInformation":{
        "gtin":"1111111111111",
        "altPid":"123ABC",
        "upc":"Not applicable",
        "descriptionShort":"XYZ name123",
        ...
      },
      "etimDescription":{  
        "version":"9",
        "classId":"On-floor installation duct (EC000722)",
        "groupId":"Installation ducts for wall and ceiling (EG000006)",
        "features":[  
          [
            "Material",
            "Steel"
          ],
          [
            "Halogen free",
            "No"
          ],
          [
            "Operating temperature",
            "2..4.5 °C"
          ],
          [
            "Length",
            "80 mm"
          ],
          [
            "RAL-number",
            "Not applicable"
          ],
          [
            "With anti-slip layer",
            "Unknown"
          ],
          ...
        ]
      },
      ...
    },
    ...
  ],
  "parameters":{
    "lang":"en",
    "etim-version":"9",
    "completeness":"true",
    "dates-by-type":"true",
    "na-values":"true"
  }
}

Get product data as supplier | RESTful API: products

When accessing a product, the primary product identifier ("productId") is usually used. However, for accounts using supplier management capabilities, it is sometimes convenient to refer to a product based on supplier information and use the supplier product identifier ("supplierPid"). This mode of access is enabled by the "as supplier" parameter. It gives the possibility to retrieve product information "as supplier". In this case, the product is accessed based on the pair: "supplier"-"supplierPid", instead of the main product identifier ("productId"). This allows retrieving the product information as if it was generated from a supplier account, i.e. where the main product identifier is "supplierPid". This way of accessing data forces the substitution of certain fields.

If the parameter "as-supplier" is used (i.e. a supplier identifier is specified as the value of the parameter "as-supplier"), the following fields of the downloaded product information are treated differently:

"supplierPid" overwrites "productId"
"supplierAltPid" overwrites "altPid"
"supplierDescriptionShort" (if exists) overwrites "descriptionShort"
"supplier", "supplierPid", "supplierDescriptionShort" and "supplierAltPid" (if exist) are skipped

Lack of access rights to the listed fields will restrict or prevent the retrieval of product information.

Get product LCA (Life Cycle Assessment) data | RESTful API: products

https://epim.one/api/api-identifier/products/lca?as-supplier={identifier}

Method: GET

Request is sent by an external system. The application responds with the detailed LCA information of the specified product(s). It is necessary to send the list of product IDs (as a JSON data) whose LCA data are to be obtained.

You can get by default up to 100 products in one GET request.

Query string parameters:

as-supplier (optional; only for accounts with suppliers; not for supplier users) - possibility to read product information "as a supplier", so that the products are accessed on the basis of the pair: "supplier"-"supplierPid", instead of on the basis of the "productId" (for details see "Get product data as supplier" section)

Example of a request (curl):

curl -X GET "https://epim.one/api/api-identifier/products/lca" -u username:password -H "Content-Type: application/json" --data-binary "@productsIDs.json"

The productsIDs.json file example (UTF-8 encoded):

[  
  "XYZ123",
  "XYZ124"
]

Example of a response (JSON):

{
  "products":[  
    {  
      "productId":"XYZ123",
      "database":"OEKOBAU.DAT",
      "uuid":"5488d3f3-1e39-4a71-b357-ef605b65ed9c",
      "link":"https://www.oekobaudat.de/OEKOBAU.DAT/resource/processes/5488d3f3-1e39-4a71-b357-ef605b65ed9c",
      "epdLink":"https://www.oekobaudat.de/OEKOBAU.DAT/resource/processes/5488d3f3-1e39-4a71-b357-ef605b65ed9c/epd",
      "category":"Dämmstoffe / Holzfasern / Holzfaserdämmplatte",
      "name":"Wood fiber insulation - dry process (German average)",
      "location":"DE",
      "validTo":"2028",
      "referenceFlowName":"Holzfaserdämmstoffplatte Trockenverfahren (Durchschnitt DE)",
      "referenceFlowLink":"https://www.oekobaudat.de/OEKOBAU.DAT/resource/flows/e12dff6e-bbdb-4870-b5e3-ae334ec7df70",
      "type":"representative dataset",
      "owner":"Thünen-Institut für Holzforschung",
      "compliance":"EN 16485 / EN 15804+A2",
      "values":{
        "ADPE":{
          "A1":"3.005714796856335E-6",
          "A1-A3":"7.516841284601982E-6",
          "A2":"1.15699514681913E-7",
          "A3":"4.395426973063735E-6",
          "A5 Entsorgung Verpackung":"1.97400663487565E-8",
          "C2":"3.9506857895014E-8",
          "C3":"8.58293413238524E-8",
          "D energetisch":"-1.2675668817016163E-5",
          "unit":"kg Sb-Äqv."
        },
        ...
      }
    },
    ...
  ],
  "parameters":[]
}

Fields description:

products - detailed LCA information of the specified product(s):
- productId - unique identifier of product
- database - name of the source LCA database
- uuid - universal unique identifier for the LCA dataset
- link - link to the source LCA dataset in the database
- epdLink - link to the Environmental Product Declaration (EPD)
- category - the category of the LCA dataset
- name - the name of the LCA dataset
- location - country/region of the LCA dataset
- validTo - year of validity of the LCA dataset
- referenceFlowName - name of the reference product flow set
- referenceFlowLink - link to the reference product flow set
- type - the type of LCA dataset
- owner - the owner/creator of the LCA dataset
- compliance - the conformity of the LCA dataset to DIN/EN standards
- values - the values of the individual indicators of the LCA dataset according to the life cycle stages of the product
parameters - correct/default query string parameters

Put product data | RESTful API: products

https://epim.one/api/api-identifier/products?new={add/skip}&existing={replace/complete/skip}&empty={false/true}&as-supplier={identifier}

Method: PUT

Request is sent by an external system. The application writes the received information in its database and responds with a short report. Only string values (delimited by double quotes) are accepted. Also numbers should be transfered as strings delimited by quotations marks. Strings should not contain spaces at the beginning and at the end (such spaces will be anyway skiped/trimmed when importing).

You can send by default up to 16 MB data in one PUT request.

Query string parameters:

new - one of the following values:
- "add" (default value) - in the case of a new product, it will be added
- "skip" - in the case of a new product, it will be skipped
existing - one of the following values:
- "replace" (default value) - in the case of an existing product, imported elements replace existing elements of a given type
- "complete" - in the case of an existing product, imported values overwrite only empty values, and imported multiple elements are added to the existing elements
- "skip" - in the case of an existing product, it will be skipped
empty (only for "replace" mode) - one of the following values:
- "false" (default value) - empty values do not overwrite existing field values
- "true" - empty values overwrite existing field values
as-supplier (optional; only for accounts with suppliers; not for supplier users) - possibility to deliver product information "as a supplier", so that the products are accessed on the basis of the pair: "supplier"-"supplierPid", instead of on the basis of the "productId" (for details see "Put product data as supplier" section)

Example of a request (curl):

curl -X PUT "https://epim.one/api/api-identifier/products" -u username:password -H "Content-Type: application/json" --data-binary "@productsData.json"

The productsData.json file example (UTF-8 encoded):

[  
  {  
    "productId":"XYZ123",
    "overallInformation":{
      "gtin":"1111111111111",
      "altPid":"123ABC",
      "upc":"-",
      "descriptionShort":{  
        "pl":"XYZ nazwa123",
        "en":"XYZ name123",
        ...
      },
      "descriptionLong":{  
        "pl":"XYZ opis szczegółowy 123",
        "en":"XYZ detailed description 123",
        ...
      },
      "descriptionVeryShort":{  
        "pl":"XYZ-n123",
        "en":"XYZn123",
        ...
      },
      "tenderText":{  
        "pl":"XYZ nazwa123 - prawdopodobnie najlepszy produkt na rynku",
        "en":"XYZ nazwa123 - probably the best product on the market",
        ...
      },
      "keyword":{  
        "pl":[  
          "słowo kluczowe 1",
          "słowo kluczowe 2",
          "słowo kluczowe 3",
          ...
        ],
        "en":[  
          "keyword 1",
          "keyword 2",
          "keyword 3",
          ...
        ],
        ...
      },
      "remark":{  
        "pl":[  
          "uwaga1",
          "uwaga2",
          ...
        ],
        "en":[  
          "remark1",
          "remark2",
          ...
        ],
        ...
      },
      "productStatus":{  
        "pl":[  
          {  
            "type":"core_product",
            "value":"Asortyment podstawowy"
          },
          {  
            "type":"new",
            "value":"Fabrycznie nowy"
          },
          ...
        ],
        "en":[  
          {  
            "type":"core_product",
            "value":"Core product"
          },
          {  
            "type":"new",
            "value":"Brand new"
          },
          ...
        ],
        ...
      },
      "supplier":"AAA",
      "supplierPid":"ZWZ652986",
      "supplierDescriptionShort":{  
        "pl":"AAA nazwa123",
        "en":"AAA name123",
        ...
      },
      "supplierAltPid":"CCC73545",
      "manufacturerName":"AA",
      "manufacturerPid":"12",
      "manufacturerTypeDesc":{  
        "pl":"pl123",
        "en":"en123",
        ...
      },
      "manufacturerAcronym":"BB",
      "manufacturerAltPid":"AA12",
      "brandName":"XYZ",
      "productSeries":{  
        "pl":"seria 1",
        "en":"serie 1",
        ...
      },
      "productVariation":{  
        "pl":"typ 12",
        "en":"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":{
        "pl":"UN 2902 PESTYCYD",
        "en":"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":{  
        "pl":"promocja sezonowa",
        "en":"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":{  
          "pl":"pak",
          "en":"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":{  
          "pl":"https://files.epim.one/xyz/zdjecie1",
          "en":"https://files.epim.one/xyz/zdjecie1",
          ...
        },
        "mimeDesignation":{  
          "pl":"Główne zdjęcie produktu",
          "en":"Main product picture",
          ...
        }
      },
      ...
    ],
    "attributes":{  
      "M1":{  
        "pl":"wartosc",
        "en":"value",
        ...
      },
      "L2":"false",
      "S3":"v2",
      "N4":"5.2",
      "R5":[  
        "2",
        "5"
      ],
      ...
    },
    "lca":{
      "database":"OEKOBAU.DAT",
      "uuid":"301c6f09-ce88-4818-96c3-e420fe799d62"
    },
    "additionalTechnicalDescription":{  
      "tech data 1 name":"tech data 1 value",
      "tech data 2 name":"tech data 2 value",
      ...
    },
    "seo":{
      "index":"true",
      "follow":"false",
      "canonical":{
        "pl":"https://website.com/pl/page",
        "en":"https://website.com/en/page",
        ...
      },
      "url":{
        "pl":"https://website.com/pl/page/product/xyz123",
        "en":"https://website.com/en/page/product/xyz123",
        ...
      },
      "metaDescription":{
        "pl":"XYZ123 jest przykladowym produktem na naszej stronie",
        "en":"XYZ123 is an example product on our website",
        ...
      },
      "metaKeywords":{
        "pl":"xyz123, produkt, etim, klasyfikacja",
        "en":"xyz123, product, etim, classification",
        ...
      },
      "title":{
        "pl":"Produkt XYZ123 | Website.com",
        "en":"XYZ123 product | Website.com",
        ...
      },
      "h1":{
        "pl":"Produkt XYZ123",
        "en":"XYZ123 product",
        ...
      }
    },
    "www":[  
      {  
        "header":{  
          "pl":"Laptop i tablet w jednym",
          "en":"Laptop and tablet in one",
          ...
        },
        "text":{  
          "pl":"Laptop 2 w 1 łączy w sobie lekkość, mobilność oraz dotykowe ekrany tabletów z <strong>mocą obliczeniową</strong> notebooków. ...",
          "en":"2 in 1 laptop combines lightness, mobility and touch screens of tablets with <strong>the computing power</strong> of notebooks. ...",
          ...
        },
        "imageUrl":{  
          "pl":"https://files.epim.one/xyz/image-pl.jpg",
          "en":"https://files.epim.one/xyz/image-en.jpg",
          ...
        },
        "imageTitle":{  
          "pl":"Laptop 2 w 1",
          "en":"2 in 1 laptop",
          ...
        },
        "imageAlt":{  
          "pl":"zdjęcie laptopa 2 w 1",
          "en":"picture of 2 in 1 laptop",
          ...
        }
      },
      ...
    ],
    "relatedProducts":[  
      {  
        "relatedProductId":"ABC123",
        "relationType":"accessories",
        "quantity":"1",
        "description":{  
          "pl":"akcesorium do produktu",
          "en":"product accessory",
          ...
        }
      },
      ...
    ],
    "relationsByAttribute":[  
      "relation1",
      "relation2",
      ...
    ],
    "categories":{  
      "leaves":{  
        "TC1":[  
          "C1",
          "SC5",
          ...
        ],
        ...
      }
    },
    "labels":[  
      "label1",
      "label2",
      ...
    ]
  },
  ...
]

Fields description:

productId - unique identifier of product
overallInformation - part of the general product information
etimDescription - part of the ETIM description
orderInformation - part of the product order information
packingInformation - part of the product packaging information
priceInformation - part of the product price information
mime - part of the product MIME information
attributes - values of product attributes
lca - part of the product LCA (Life Cycle Assessment)
additionalTechnicalDescription - additional technical features of the product (they can be used in automatic classification of products)
seo - data to improve the positioning in search engines results
www - information to facilitate and enrich the presentation of product information on websites
relatedProducts - part of the related products information
relationsByAttribute - product relations by attribute
categories - product categories
labels - product labels

Example of a response (JSON):

{  
  "all":"10",
  "rejected (product ID longer than 32 characters)":"1 (JHJJFF76742345-fsgdfhgddskjhf34581)",
  "unique":"8",
  "new":"5",
  "modified":"3",
  "classified":"2",
  "reclassified":"1",
  "deletedClassifications":"0",
  "deletedRelatedProducts":"9",
  "createdRelatedProducts":"7",
  "limitExceeded":"0",
  "parameters":{
      "new":"add",
      "existing":"replace",
      "empty":"false"
  }
}

Fields description:

all - number of all products in the request
rejected - number of products that can not be properly handled (with the list of up to 4 first occurrences)
unique - number of unique (relative to "productId") products in the request
new - number of products that have been added to the database
modified - number of products that have been modified in the database
classified - number of products that have been classified (ETIM)
reclassified - number of products that have been reclassified (ETIM)
deletedClassifications - number of products with deleted class (ETIM)
deletedRelatedProducts - number of deleted related products
createdRelatedProducts - number of created related products
limitExceeded - number of new products for which the limit has been exceeded
parameters - correct/default query string parameters

Put product data as supplier | RESTful API: products

When accessing a product, the primary product identifier ("productId") is usually used. However, for accounts using supplier management capabilities, it is sometimes convenient to refer to a product based on supplier information and use the supplier product identifier ("supplierPid"). This mode of access is enabled by the "as supplier" parameter. It gives the possibility to deliver product information "as supplier". In this case, the product is accessed based on the pair: "supplier"-"supplierPid", instead of the main product identifier ("productId"). This allows to delivery of product information where the main product identifier is "supplierPid". This way of accessing data forces the substitution of certain fields.

If the parameter "as-supplier" is used (i.e. a supplier identifier is specified as the value of the parameter "as-supplier"), the following fields of the imported product(s) are treated differently:

"productId" is saved as "supplierPid"
"altPid" is saved as "supplierAltPid"
"descriptionShort" is saved as "supplierDescriptionShort" and "descriptionShort"
"supplier", "supplierPid", "supplierDescriptionShort" and "supplierAltPid" (if exist) are skipped

In the case of duplicate values of the "supplierPid" field, the application merges products. In the case of new products, the value of the "productId" field is automatically generated as a concatenation of supplier identifier, "_" (underscore) and "supplierPid" (the application ensures that there are no duplicates of the "productId" field).

Lack of access rights to the fields listed above will restrict or prevent the saving of product information.

You can send by default up to 16 MB data in one PUT request.

Delete products | RESTful API: products

https://epim.one/api/api-identifier/products

Method: DELETE

The request is sent by an external system. It is necessary to send a list of product IDs (as a JSON data) that you want to delete. The application deletes the product(s) in its database and responds with a short report.

Example of a request (curl):

curl -X DELETE "https://epim.one/api/api-identifier/products" -u username:password -H "Content-Type: application/json" --data-binary "@productsIDs.json"

The productsIDs.json file example (UTF-8 encoded):

[  
  "XYZ123",
  "XYZ124"
]

Example of a response (JSON):

{  
  "deletedProducts":"2",
  "parameters":[]
}

Fields description:

deletedProducts - number of deleted products
parameters - correct/default query string parameters

List of all identifiers of labels | RESTful API: labels

https://epim.one/api/api-identifier/labels

Method: GET

The request is sent by an external system. The application responds by sending all identifiers of labels.

Example of a request (curl):

curl -X GET "https://epim.one/api/api-identifier/labels" -u username:password

Example of a response (JSON):

{
  "labelIdentifiers":[  
    "Public",
    "label1",
    "label2",
    "label3"
  ],
  "parameters":[]
}

Fields description:

labelIdentifiers - all identifiers of labels
parameters - correct/default query string parameters

Get label data | RESTful API: labels

https://epim.one/api/api-identifier/labels

Method: GET

Request is sent by an external system. The application responds with the detailed information of the specified label(s). It is necessary to send the list of label identifiers (as a JSON data) that you want to get.

Example of a request (curl):

curl -X GET "https://epim.one/api/api-identifier/labels" -u username:password -H "Content-Type: application/json" --data-binary "@labelIdentifiers.json"

The labelIdentifiers.json file example (UTF-8 encoded):

[  
  "Public",
  "label1"
]

Example of a response (JSON):

{
  "labels":[  
    {  
      "identifier":"Public",
      "permanent":"true",
      "letter":"P",
      "color":"grey",
      "description":"Products having this label are visible for external users"
    },
    {  
      "identifier":"label1",
      "permanent":"false",
      "letter":"E",
      "color":"green"
    }
  ],
  "parameters":[]
}

Fields description:

labels - detailed information of the specified label(s):
- identifier - unique identifier of label
- permanent - indication whether the label is permanent (you can not edit or delete permanent labels)
- letter - letter in the label icon
- color - color of the label icon
- description - description of the label
parameters - correct/default query string parameters

Put label data | RESTful API: labels

https://epim.one/api/api-identifier/labels

Method: PUT

You can send by default up to 16 MB data in one PUT request.

Example of a request (curl):

curl -X PUT "https://epim.one/api/api-identifier/labels" -u username:password -H "Content-Type: application/json" --data-binary "@labelsData.json"

The labelsData.json file example (UTF-8 encoded):

[
   { 
      "identifier":"label1",
      "letter":"S",
      "color":"red",
      "description":"Products for sale"
   },
   { 
      "identifier":"label2",
      "letter":"O",
      "color":"grey",
      "description":"Old products"
   },
   ...
]

Fields description:

identifier - unique identifier of label (max. 16 characters, allowed characters: A-Za-z0-9_-)
letter (default is "A") - letter of the label icon (acceptable values: "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z")
color (default is "blue") - color of the label icon (acceptable values: "blue", "brown", "green", "grey", "yellow", "red", "violet")
description - description of the label

Fields with the indicated default value can be omitted. Label(s) with the incorrect value(s) will be rejected.

Example of a response (JSON):

{  
  "all":"4",
  "rejected":"1",
  "unique":"3",
  "replaced":"1",
  "new":"2",
  "parameters":[]
}

Fields description:

all - number of all labels in the request
rejected - number of labels that can not be properly handled
unique - number of unique (relative to identifier) labels in the request
replaced - number of labels that have been replaced in the database
new - number of labels that have been added to the database
parameters - correct/default query string parameters

Delete labels | RESTful API: labels

https://epim.one/api/api-identifier/labels

Method: DELETE

The request is sent by an external system. It is necessary to send a list of label identifiers (as a JSON data) that you want to delete. The application deletes the label(s) in its database and responds with a short report.

Example of a request (curl):

curl -X DELETE "https://epim.one/api/api-identifier/labels" -u username:password -H "Content-Type: application/json" --data-binary "@labelIdentifiers.json"

The labelIdentifiers.json file example (UTF-8 encoded):

[  
  "label1",
  "label2"
]

Example of a response (JSON):

{  
  "deletedLabels":"2",
  "parameters":[]
}

Fields description:

deletedLabels - number of deleted labels
parameters - correct/default query string parameters

List of all identifiers of attributes | RESTful API: attributes

https://epim.one/api/api-identifier/attributes

Method: GET

The request is sent by an external system. The application responds by sending all identifiers of attributes.

Example of a request (curl):

curl -X GET "https://epim.one/api/api-identifier/attributes" -u username:password

Example of a response (JSON):

{
  "attributeIdentifiers":[  
    "M1",
    "L2",
    "S3",
    "N4",
    "R5",
    "A6"
  ],
  "parameters":[]
}

Fields description:

attributeIdentifiers - all identifiers of attributes
parameters - correct/default query string parameters

Get attribute data | RESTful API: attributes

https://epim.one/api/api-identifier/attributes

Method: GET

Request is sent by an external system. The application responds with the detailed information of the specified attribute(s). It is necessary to send the list of attributes identifiers (as a JSON data) that you want to get.

Example of a request (curl):

curl -X GET "https://epim.one/api/api-identifier/attributes" -u username:password -H "Content-Type: application/json" --data-binary "@attributeIdentifiers.json"

The attributeIdentifiers.json file example (UTF-8 encoded):

[  
  "M1",
  "L2",
  "S3"
]

Example of a response (JSON):

{
  "attributes":[  
    {  
      "identifier":"M1",
      "type":"M",
      "permanent":"false",
      "global":"true",
      "productCharacteristic":"true",
      "forSynch":"true",
      "importance":"0",
      "name":{  
        "pl":"Atrybut 1",
        "en":"Attribute 1",
        ...
      },
      "description":{  
        "pl":"Opis atrybutu 1",
        "en":"Description of attribute 1",
        ...
      },
      "inCompletenessMask":"false"
    },
    {  
      "identifier":"L2",
      "type":"L",
      "permanent":"false",
      "global":"false",
      "productCharacteristic":"false",
      "forSynch":"false",
      "importance":"5",
      "name":{  
        "pl":"Atrybut 2",
        "en":"Attribute 2",
        ...
      },
      "description":{  
        "pl":"Opis atrybutu 2",
        "en":"Description of attribute 2",
        ...
      },
      "inCompletenessMask":"true"
    },
    {  
      "identifier":"S3",
      "type":"S",
      "permanent":"false",
      "global":"true",
      "productCharacteristic":"true",
      "forSynch":"false",
      "importance":"2",
      "name":{  
        "pl":"Atrybut 3",
        "en":"Attribute 3",
        ...
      },
      "description":{  
        "pl":"Opis atrybutu 3",
        "en":"Description of attribute 3",
        ...
      },
      "values":[
        {  
          "identifier":"v1",
          "value":{
            "pl":"wartość select 1",
            "en":"select value 1",
            ...
          }
        },
        ...
      ],
      "inCompletenessMask":"false"
    }
  ],
  "parameters":[]
}

Fields description:

attributes - detailed information of the specified attribute(s):
- identifier - unique identifier of attribute
- type - attribute type:
  - M - multilingual text
  - T - text
  - N - numeric
  - R - range
  - L - logical
  - D - date
  - S - select
- permanent - indication whether the attribute is permanent (you can not edit or delete permanent attributes)
- global - indication whether the attribute is global
- productCharacteristic - indication whether the attribute is used as a product characteristic in BMEcat
- forSynch - indication whether the attribute is subject to synchronization
- importance - importance of the attribute (from "0" to "15")
- name - names of the attribute in various languages
- values - values of the attribute (only for select attribtues)
- inCompletenessMask - indication whether the attribute is in user-defined completeness mask (only additional and global attributes can be in user-defined completeness mask)
parameters - correct/default query string parameters

Put attribute data | RESTful API: attributes

https://epim.one/api/api-identifier/attributes

Method: PUT

You can send by default up to 16 MB data in one PUT request.

Example of a request (curl):

curl -X PUT "https://epim.one/api/api-identifier/attributes" -u username:password -H "Content-Type: application/json" --data-binary "@attributesData.json"

The attributesData.json file example (UTF-8 encoded):

[  
  {  
    "identifier":"M1",
    "type":"M",
    "global":"true",
    "productCharacteristic":"true",
    "forSynch":"false",
    "importance":"2",
    "name":{  
      "pl":"Atrybut 1",
      "en":"Attribute 1",
      ...
    },
    "description":{  
      "pl":"Opis atrybutu 1",
      "en":"Description of attribute 1",
      ...
    }
  },
  {  
    "identifier":"S3",
    "type":"S",
    "global":"true",
    "productCharacteristic":"true",
    "forSynch":"false",
    "importance":"2",
    "name":{  
      "pl":"Atrybut 3",
      "en":"Attribute 3",
      ...
    },,
    "description":{  
      "pl":"Opis atrybutu 3",
      "en":"Description of attribute 3",
      ...
    },
    "values":[
      {  
        "identifier":"val1",
        "value":{
          "pl":"wart 1",
          "en":"val 1",
          ...
        }
      },
      ...
    ]
  },
  ...
]

Fields description:

identifier - unique identifier of attribute (max. 60 characters)
type (default is "M") - attribute type:
- M - multilingual text
- T - text
- N - numeric
- R - range
- L - logical
- D - date
- S - select
global (default is "true") - indication whether the attribute is global
productCharacteristic (default is "false") - indication whether the attribute is used as a product characteristic in BMEcat
forSynch (default is "false") - indication whether the attribute is subject to synchronization (you can set it to "true" only for additional and global attributes)
importance (default is "0") - importance of the attribute (from "0" to "15")
name - names of the attribute in various languages
values - values of the attribute (only for select attribtues)

Fields with the indicated default value can be omitted. Attribute(s) with the incorrect value(s) will be rejected.

For attributes that are used in a user-defined completeness mask, you cannot:

change the type
change the globality
delete the value(s) of a select attribute

To make this possible, you must first remove these attributes from the completeness mask.

Example of a response (JSON):

{  
  "all":"6",
  "rejected":"1",
  "unique":"5",
  "replaced":"4",
  "new":"1",
  "parameters":[]
}

Fields description:

all - number of all attributes in the request
rejected - number of attributes that can not be properly handled
unique - number of unique (relative to identifier) attributes in the request
replaced - number of attributes that have been replaced in the database
new - number of attributes that have been added to the database
parameters - correct/default query string parameters

Delete attributes | RESTful API: attributes

https://epim.one/api/api-identifier/attributes

Method: DELETE

The request is sent by an external system. It is necessary to send a list of attribute identifiers (as a JSON data) that you want to delete. The application deletes the attribute(s) in its database and responds with a short report.

Example of a request (curl):

curl -X DELETE "https://epim.one/api/api-identifier/attributes" -u username:password -H "Content-Type: application/json" --data-binary "@attributeIdentifiers.json"

The attributeIdentifiers.json file example (UTF-8 encoded):

[  
  "M1",
  "L2"
]

Example of a response (JSON):

{  
  "deletedAttributes":"2",
  "parameters":[]
}

Fields description:

deletedAttributes - number of deleted attributes
parameters - correct/default query string parameters

You cannot delete attributes that are used in a user-defined completeness mask. To make this possible, you must first remove these attributes from the completeness mask.

List of all identifiers of relations by attribute | RESTful API: relations by attribute

https://epim.one/api/api-identifier/relations-by-attribute

Method: GET

The request is sent by an external system. The application responds by sending all identifiers of relations by attribute.

Example of a request (curl):

curl -X GET "https://epim.one/api/api-identifier/relations-by-attribute" -u username:password

Example of a response (JSON):

{
  "relationByAttributeIdentifiers":[  
    "ST",
    "ST1",
    ...
  ],
  "parameters":[]
}

Fields description:

relationByAttributeIdentifiers - all identifiers of relations by attribute
parameters - correct/default query string parameters

Get relation by attribute data | RESTful API: relations by attribute

https://epim.one/api/api-identifier/relations-by-attribute

Method: GET

Request is sent by an external system. The application responds with the detailed information of the specified relation(s) by attribute. It is necessary to send the list of relation identifiers (as a JSON data) that you want to get.

Example of a request (curl):

curl -X GET "https://epim.one/api/api-identifier/relations-by-attribute" -u username:password -H "Content-Type: application/json" --data-binary "@relationByAttributeIdentifiers.json"

The relationByAttributeIdentifiers.json file example (UTF-8 encoded):

[  
  "ST",
  "EF1"
]

Example of a response (JSON):

{
  "relationsByAttribute":[ 
    { 
      "identifier":"ST",
      "attribute":"STAT",
      "name":{ 
        "pl":"Status produktu",
        "en":"Product status",
        ...
      },
      "products":[ 
        "XYZ",
        "XYZ212",
        ...
      ],
      "productValues":{ 
        "XYZ212":{ 
          "pl":[ 
            { 
              "type":"core_product",
              "value":"121"
            }
          ],
          "en":[ 
            { 
              "type":"core_product",
              "value":"121"
            }
          ],
          ...
        },
        ...
      },
      "virtualProducts":[ 
        "XYZ"
      ]
    },
    { 
      "identifier":"EF1",
      "attribute":"EF000363",
      "name":{ 
        "pl":"Oznaczenie rozmiaru",
        "en":"Size indication",
        ...
      },
      "products":[ 
        "XYZ12",
        ...
      ],
      "productValues":{ 
        "XYZ12":"EV000877",
        ...
      }
    }
  ],
  "parameters":[]
}

Fields description:

relationsByAttribute - detailed information of the specified relation(s) by attribute:
- identifier - unique identifier of relation by attribute
- attribute - unique identifier of grouping attribute
- name - names of the relation by attribute in various languages
- products - identifiers of all products which are in the relation by attribute
- productValues - product values of the grouping attribute
- virtualProducts - identifiers of virtual products
parameters - correct/default query string parameters

Get relation by attribute data in a language-dependent version | RESTful API: relations by attribute

https://epim.one/api/api-identifier/relations-by-attribute?lang={code}

Method: GET

Request is sent by an external system. The application responds with the detailed information of the specified relation(s) by attribute. All the coded information is sent in the requested language. It is necessary to send the list of relation identifiers (as a JSON data) that you want to get.

Query string parameters:

lang - required language code acc. to ISO 639-1 (2 letter language code, for example, "en" for English, "pl" for Polish etc.)

Example of a request (curl):

curl -X GET "https://epim.one/api/api-identifier/relations-by-attribute?lang=en" -u username:password -H "Content-Type: application/json" --data-binary "@relationByAttributeIdentifiers.json"

The relationByAttributeIdentifiers.json file example (UTF-8 encoded):

[  
  "ST",
  "EF1",
]

Example of a response (JSON):

{
  "relationsByAttribute":[ 
    { 
      "identifier":"ST",
      "attribute":"STAT",
      "name":"Product status",
      "products":[ 
        "XYZ",
        "XYZ212",
        ...
      ],
      "productValues":{ 
        "XYZ212":[ 
          "Core product (121)"
        ],
        ...
        },
      "virtualProducts":[ 
        "XYZ"
      ]
      },
    { 
      "identifier":"EF1",
      "attribute":"EF000363",
      "name":"Size indication",
      "products":[ 
        "XYZ12",
        ...
      ],
      "productValues":{ 
        "XYZ12":"Mignon",
        ...
      }
    }
  ],
  "parameters":{
    "lang":"en"
  }
}

Put relation by attribute data | RESTful API: relations by attribute

https://epim.one/api/api-identifier/relations-by-attribute

Method: PUT

You can send by default up to 16 MB data in one PUT request.

Example of a request (curl):

curl -X PUT "https://epim.one/api/api-identifier/relations-by-attribute" -u username:password -H "Content-Type: application/json" --data-binary "@relationsData.json"

The relationsData.json file example (UTF-8 encoded):

[
  { 
    "identifier":"ST",
    "attribute":"STAT",
    "name":{ 
      "pl":"Status produktu",
      "en":"Product status",
      ...
    },
    "products":[ 
      "XYZ212",
      ...
    ]
  },
  { 
    "identifier":"EF1",
    "attribute":"EF000363",
    "name":{ 
      "pl":"Oznaczenie rozmiaru",
      "en":"Size indication",
      ...
    },
    "products":[ 
      "XYZ12",
      ...
    ]
  },
  ...
]

Fields description:

identifier - unique identifier of relation by attribute (max. 16 characters, allowed characters: A-Za-z0-9_-)
attribute - unique identifier of grouping attribute
name - names of the relation by attribute in various languages
products - identifiers of all products which are in the relation by attribute

Example of a response (JSON):

{  
  "all":"5",
  "rejected":"1",
  "unique":"4",
  "replaced":"3",
  "new":"1",
  "parameters":[]
}

Fields description:

all - number of all relations by attribute in the request
rejected - number of relations by attribute that can not be properly handled
unique - number of unique (relative to identifier) relations by attribute in the request
replaced - number of relations by attribute that have been replaced in the database
new - number of relations by attribute that have been added to the database
parameters - correct/default query string parameters

Delete relations by attribute | RESTful API: relations by attribute

https://epim.one/api/api-identifier/relations-by-attribute

Method: DELETE

The request is sent by an external system. It is necessary to send a list of relation identifiers (as a JSON data) that you want to delete. The application deletes the relation(s) by attribute in its database and responds with a short report.

Example of a request (curl):

curl -X DELETE "https://epim.one/api/api-identifier/relations-by-attribute" -u username:password -H "Content-Type: application/json" --data-binary "@relationByAttributeIdentifiers.json"

The relationByAttributeIdentifiers.json file example (UTF-8 encoded):

[  
  "ST",
  "EF1"
]

Example of a response (JSON):

{  
  "deletedRelationsByAttribute":"2",
  "parameters":[]
}

Fields description:

deletedRelationsByAttribute - number of deleted relations by attribute
parameters - correct/default query string parameters

List of all identifiers of suppliers | RESTful API: suppliers

https://epim.one/api/api-identifier/suppliers

Method: GET

The request is sent by an external system. The application responds by sending all identifiers of suppliers.

Example of a request (curl):

curl -X GET "https://epim.one/api/api-identifier/suppliers" -u username:password

Example of a response (JSON):

{
  "supplierIdentifiers":[  
    "sup1",
    "sup2",
    "sup3"
  ],
  "parameters":[]
}

Fields description:

supplierIdentifiers - all identifiers of suppliers
parameters - correct/default query string parameters

Get supplier data | RESTful API: suppliers

https://epim.one/api/api-identifier/suppliers

Method: GET

Request is sent by an external system. The application responds with the detailed information of the specified supplier(s). It is necessary to send the list of supplier identifiers (as a JSON data) that you want to get.

Example of a request (curl):

curl -X GET "https://epim.one/api/api-identifier/suppliers" -u username:password -H "Content-Type: application/json" --data-binary "@supplierIdentifiers.json"

The supplierIdentifiers.json file example (UTF-8 encoded):

[  
  "sup1",
  "sup2"
]

Example of a response (JSON):

{
  "suppliers":[  
    {  
      "identifier":"sup1",
      "name":"Supplier1 Name",
      "manufacturer":"false",
      "vatId":"PL5211111111",
      "gln":"1234567000004",
      "duns":"130692711",
      "street":"Mlynarska 16",
      "postalCode":"91-823",
      "city":"Lodz",
      "country":"PL",
      "contactPerson":"Jan Kowalski",
      "phone":"+48690589234",
      "email":"office@supplier1name.com",
      "website":"supplier1name.com",
      "logo":"https://files.epim.one/xyz/sup1-logo.jpg"
    },
    ...
  ],
  "parameters":[]
}

Fields description:

suppliers - detailed information of the specified supplier(s):
- identifier - unique supplier identifier
- name - supplier name
- manufacturer - indication whether the supplier is manufacturer
- vatId - supplier VAT-ID
- gln - supplier GLN number
- duns - supplier DUNS number
- street - supplier's address: street name and house number
- postalCode - supplier's address: postal code
- city - supplier's address: city
- country - supplier's address: country
- contactPerson - contact person of the supplier
- phone - the phone of the supplier
- email - the main email of the supplier
- website - supplier's website
- logo - supplier's logo URL
parameters - correct/default query string parameters

Put supplier data | RESTful API: suppliers

https://epim.one/api/api-identifier/suppliers

Method: PUT

You can send by default up to 16 MB data in one PUT request.

Example of a request (curl):

curl -X PUT "https://epim.one/api/api-identifier/suppliers" -u username:password -H "Content-Type: application/json" --data-binary "@suppliersData.json"

The suppliersData.json file example (UTF-8 encoded):

[
  {  
    "identifier":"sup1",
    "name":"Supplier1 Name",
    "manufacturer":"false",
    "vatId":"PL5211111111",
    "gln":"1234567000004",
    "duns":"130692711",
    "street":"Mlynarska 16",
    "postalCode":"91-823",
    "city":"Lodz",
    "country":"PL",
    "contactPerson":"Jan Kowalski",
    "phone":"+48690589234",
    "email":"office@supplier1name.com",
    "website":"supplier1name.com",
    "logo":"https://files.epim.one/xyz/sup1-logo.jpg"
  },
   ...
]

Fields description:

identifier - unique identifier of supplier (max. 16 characters, allowed characters: A-Za-z0-9_-)
name - supplier name (mandatory field)
manufacturer (default is "false") - indication whether the supplier is manufacturer
vatId - supplier VAT-ID
gln - supplier GLN number
duns - supplier DUNS number
street - supplier's address: street name and house number
postalCode - supplier's address: postal code
city - supplier's address: city
country - supplier's address: country (country code acc. to ISO 3166-1)
contactPerson - contact person of the supplier
phone - the phone of the supplier
email - the main email of the supplier
website - supplier's website
logo - supplier's logo URL

Fields with the indicated default value can be omitted. Supplier(s) with the incorrect value(s) will be rejected.

Example of a response (JSON):

{  
  "all":"3",
  "rejected":"1",
  "unique":"2",
  "replaced":"1",
  "new":"1",
  "parameters":[]
}

Fields description:

all - number of all suppliers in the request
rejected - number of suppliers that can not be properly handled
unique - number of unique (relative to identifier) suppliers in the request
replaced - number of suppliers that have been replaced in the database
new - number of suppliers that have been added to the database
parameters - correct/default query string parameters

Delete suppliers | RESTful API: suppliers

https://epim.one/api/api-identifier/suppliers?delete-products={false/true}

Method: DELETE

The request is sent by an external system. It is necessary to send a list of supplier identifiers (as a JSON data) that you want to delete. The application deletes the supplier(s) in its database and responds with a short report.

Query string parameters:

delete-products (default is "false") - specifies whether to delete products whose suppliers are deleted ("false"/"true")

Example of a request (curl):

curl -X DELETE "https://epim.one/api/api-identifier/suppliers" -u username:password -H "Content-Type: application/json" --data-binary "@supplierIdentifiers.json"

The supplierIdentifiers.json file example (UTF-8 encoded):

[  
  "sup1",
  "sup2"
]

Example of a response (JSON):

{  
  "deletedSuppliers":"2",
  "parameters":{
    "delete-products":"false"
  }
}

Fields description:

deletedSuppliers - number of deleted suppliers
parameters - correct/default query string parameters

List of all identifiers of buyers | RESTful API: buyers

https://epim.one/api/api-identifier/buyers

Method: GET

The request is sent by an external system. The application responds by sending all identifiers of buyers.

Example of a request (curl):

curl -X GET "https://epim.one/api/api-identifier/buyers" -u username:password

Example of a response (JSON):

{
  "buyerIdentifiers":[  
    "buy1",
    "buy2",
    "buy3"
  ],
  "parameters":[]
}

Fields description:

buyerIdentifiers - all identifiers of buyers
parameters - correct/default query string parameters

Get buyer data | RESTful API: buyers

https://epim.one/api/api-identifier/buyers

Method: GET

Request is sent by an external system. The application responds with the detailed information of the specified buyer(s). It is necessary to send the list of buyer identifiers (as a JSON data) that you want to get.

Example of a request (curl):

curl -X GET "https://epim.one/api/api-identifier/buyers" -u username:password -H "Content-Type: application/json" --data-binary "@buyerIdentifiers.json"

The buyerIdentifiers.json file example (UTF-8 encoded):

[  
  "buy1",
  "buy2"
]

Example of a response (JSON):

{
  "buyers":[  
    {  
      "identifier":"buy1",
      "name":"Buyer1 Name",
      "gln":"7654321000008"
    },
    ...
  ],
  "parameters":[]
}

Fields description:

buyers - detailed information of the specified buyer(s):
- identifier - unique buyer identifier
- name - buyer name
- gln - buyer GLN number
parameters - correct/default query string parameters

Put buyer data | RESTful API: buyers

https://epim.one/api/api-identifier/buyers

Method: PUT

You can send by default up to 16 MB data in one PUT request.

Example of a request (curl):

curl -X PUT "https://epim.one/api/api-identifier/buyers" -u username:password -H "Content-Type: application/json" --data-binary "@buyersData.json"

The buyersData.json file example (UTF-8 encoded):

[
   { 
      "identifier":"buy1",
      "name":"Buyer1 Name",
      "gln":"7654321000008"
   },
   ...
]

Fields description:

identifier - unique identifier of buyer (max. 16 characters, allowed characters: A-Za-z0-9_-)
name - buyer name (mandatory field)
gln - buyer GLN number

Buyer(s) with the incorrect value(s) will be rejected.

Example of a response (JSON):

{  
  "all":"3",
  "rejected":"1",
  "unique":"2",
  "replaced":"1",
  "new":"1",
  "parameters":[]
}

Fields description:

all - number of all buyers in the request
rejected - number of buyers that can not be properly handled
unique - number of unique (relative to identifier) buyers in the request
replaced - number of buyers that have been replaced in the database
new - number of buyers that have been added to the database
parameters - correct/default query string parameters

Delete buyers | RESTful API: buyers

https://epim.one/api/api-identifier/buyers

Method: DELETE

The request is sent by an external system. It is necessary to send a list of buyer identifiers (as a JSON data) that you want to delete. The application deletes the buyer(s) in its database and responds with a short report.

Example of a request (curl):

curl -X DELETE "https://epim.one/api/api-identifier/buyers" -u username:password -H "Content-Type: application/json" --data-binary "@buyerIdentifiers.json"

The buyerIdentifiers.json file example (UTF-8 encoded):

[  
  "buy1",
  "buy2"
]

Example of a response (JSON):

{  
  "deletedBuyers":"2",
  "parameters":[]
}

Fields description:

deletedBuyers - number of deleted buyers
parameters - correct/default query string parameters

List of all identifiers of category trees | RESTful API: categories

https://epim.one/api/api-identifier/categories

Method: GET

The request is sent by an external system. The application responds by sending all identifiers of category trees.

Example of a request (curl):

curl -X GET "https://epim.one/api/api-identifier/categories" -u username:password

Example of a response (JSON):

{
  "categoryTreeIdentifiers":[  
    "TC1",
    "TC2"
  ],
  "parameters":[]
}

Fields description:

categoryTreeIdentifiers - all identifiers of category trees
parameters - correct/default query string parameters

Get category tree data | RESTful API: categories

https://epim.one/api/api-identifier/categories

Method: GET

Request is sent by an external system. The application responds with the detailed information of the specified category tree(s). It is necessary to send the list of category trees identifiers (as a JSON data) that you want to get.

Example of a request (curl):

curl -X GET "https://epim.one/api/api-identifier/categories" -u username:password -H "Content-Type: application/json" --data-binary "@categoryTreeIdentifiers.json"

The categoryTreeIdentifiers.json file example (UTF-8 encoded):

[  
  "TC1",
  "TC2"
]

Example of a response (JSON):

{
  "categoryTrees":[  
    {  
      "categoryTreeIdentifier":"TC1",
      "categoryTreeName":{  
        "pl":"Sklep1",
        "en":"Shop1",
        ...
      },
      "categoryTreeAttributes":[  
        "M1",
        "L2"
      ],
      "categories":[  
        {  
          "identifier":"C1",
          "name":{  
            "pl":"Kategoria 1",
            "en":"Category 1",
            ...
          },
          "seo":{
            "index":"true",
            "follow":"true",
            "canonical":{
              "pl":"https://website.com/pl/page",
              "en":"https://website.com/en/page",
              ...
            },
            "url":{
              "pl":"https://website.com/pl/page/kategoria/C1",
              "en":"https://website.com/en/page/category/C1",
              ...
            },
            "metaDescription":{
              "pl":"C1 jest przykladowa kategoria na naszej stronie",
              "en":"C1 is an example category on our website",
              ...
            },
            "metaKeywords":{
              "pl":"c1, kategoria, etim, klasyfikacja",
              "en":"c1, category, etim, classification",
              ...
            },
            "title":{
              "pl":"Kategoria C1 | Website.com",
              "en":"C1 category | Website.com",
              ...
            },
            "h1":{
              "pl":"Kategoria C1",
              "en":"C1 category",
              ...
            }
          },
          "www":[  
            {  
              "header":{  
                "pl":"Laptopy i tablety w jednym",
                "en":"Laptops and tablets in one",
                ...
              },
              "text":{  
                "pl":"Laptopy 2 w 1 łączą w sobie lekkość, mobilność oraz dotykowe ekrany tabletów z <strong>mocą obliczeniową</strong> notebooków. ...",
                "en":"2 in 1 laptops combine lightness, mobility and touch screens of tablets with <strong>the computing power</strong> of notebooks. ...",
                ...
              },
              "imageUrl":{  
                "pl":"https://files.epim.one/xyz/category-pl.jpg",
                "en":"https://files.epim.one/xyz/category-en.jpg",
                ...
              },
              "imageTitle":{  
                "pl":"Laptopy 2 w 1",
                "en":"2 in 1 laptops",
                ...
              },
              "imageAlt":{  
                "pl":"zdjęcie laptopów 2 w 1",
                "en":"picture of 2 in 1 laptops",
                ...
              }
            },
            ...
          ]
        },
        {  
          "identifier":"C2",
          "name":{  
            "pl":"Kategoria 2",
            "en":"Category 2",
            ...
          },
          "seo":{
            ...
          },
          "www":[  
            ...
          ]
        },
        {  
          "identifier":"SC1",
          "parent":"C1",
          "name":{  
            "pl":"Podkategoria 1",
            "en":"Subcategory 1",
            ...
          },
          "attributes":[  
            "N4",
            "A6",
            "GASCAT"
          ],
          "seo":{
            ...
          },
          "www":[  
            ...
          ]
        },
        {  
          "identifier":"SC2",
          "parent":"C1",
          "name":{  
            "pl":"Podkategoria 2",
            "en":"Subcategory 2",
            ...
          },
          "attributes":[  
            "N4",
            "A6"
          ],
          "seo":{
            ...
          },
          "www":[  
            ...
          ]
        },
        ...
      ]
    },
    ...
  ],
  "parameters":[]
}

Fields description:

categoryTrees - detailed information of the specified category tree(s):
- categoryTreeIdentifier - unique identifier of the category tree
- categoryTreeName - names of category tree in various languages
- categoryTreeAttributes - identifiers of the product attributes assigned to the whole category tree (as required for products in each category of the category tree)
- categories - part of the categories information
- identifier - unique (within the category tree) category identifier
- parent - parent category identifier (if there is no "parent" key, the category is the main category)
- name - names of the category in various languages
- attributes - identifiers of the product attributes assigned to the category (as required for products in this category)
- seo - data to improve the positioning in search engines results
- www - information to facilitate and enrich the presentation of category information on websites
parameters - correct/default query string parameters

Put category tree data | RESTful API: categories

https://epim.one/api/api-identifier/categories

Method: PUT

You can send by default up to 16 MB data in one PUT request.

Example of a request (curl):

curl -X PUT "https://epim.one/api/api-identifier/categories" -u username:password -H "Content-Type: application/json" --data-binary "@categoryTreesData.json"

The categoryTreesData.json file example (UTF-8 encoded):

[  
  {  
    "categoryTreeIdentifier":"TC1",
    "categoryTreeName":{  
      "pl":"Sklep1",
      "en":"Shop1",
      ...
    },
    "categoryTreeAttributes":[  
      "M1",
      "L2"
    ],
    "categories":[  
      {  
        "identifier":"C1",
        "name":{  
          "pl":"Kategoria 1",
          "en":"Category 1",
          ...
        },
        "seo":{
          "index":"true",
          "follow":"true",
          "canonical":{
            "pl":"https://website.com/pl/page",
            "en":"https://website.com/en/page",
            ...
          },
          "url":{
            "pl":"https://website.com/pl/page/kategoria/C1",
            "en":"https://website.com/en/page/category/C1",
            ...
          },
          "metaDescription":{
            "pl":"C1 jest przykladowa kategoria na naszej stronie",
            "en":"C1 is an example category on our website",
            ...
          },
          "metaKeywords":{
            "pl":"c1, kategoria, etim, klasyfikacja",
            "en":"c1, category, etim, classification",
            ...
          },
          "title":{
            "pl":"Kategoria C1 | Website.com",
            "en":"C1 category | Website.com",
            ...
          },
          "h1":{
            "pl":"Kategoria C1",
            "en":"C1 category",
            ...
          }
        },
        "www":[  
          {  
            "header":{  
              "pl":"Laptopy i tablety w jednym",
              "en":"Laptops and tablets in one",
              ...
            },
            "text":{  
              "pl":"Laptopy 2 w 1 łączą w sobie lekkość, mobilność oraz dotykowe ekrany tabletów z <strong>mocą obliczeniową</strong> notebooków. ...",
              "en":"2 in 1 laptops combine lightness, mobility and touch screens of tablets with <strong>the computing power</strong> of notebooks. ...",
              ...
            },
            "imageUrl":{  
              "pl":"https://files.epim.one/xyz/category-pl.jpg",
              "en":"https://files.epim.one/xyz/category-en.jpg",
              ...
            },
            "imageTitle":{  
              "pl":"Laptopy 2 w 1",
              "en":"2 in 1 laptops",
              ...
            },
            "imageAlt":{  
              "pl":"zdjęcie laptopów 2 w 1",
              "en":"picture of 2 in 1 laptops",
              ...
            }
          },
          ...
        ]
      },
      {  
        "identifier":"C2",
        "name":{  
          "pl":"Kategoria 2",
          "en":"Category 2",
          ...
        },
        "seo":{
          ...
        },
        "www":[  
          ...
        ]
      },
      {  
        "identifier":"SC1",
        "parent":"C1",
        "name":{  
          "pl":"Podkategoria 1",
          "en":"Subcategory 1",
          ...
        },
        "attributes":[  
          "N4",
          "A6",
          "GASCAT"
        ],
        "seo":{
          ...
        },
        "www":[  
          ...
        ]
      },
      {  
        "identifier":"SC2",
        "parent":"C1",
        "name":{  
          "pl":"Podkategoria 2",
          "en":"Subcategory 2",
          ...
        },
        "attributes":[  
          "N4",
          "A6"
        ],
        "seo":{
          ...
        },
        "www":[  
          ...
        ]
      },
      ...
    ]
  },
  ...
]

Fields description:

categoryTreeIdentifier - unique identifier of the category tree (max. 16 characters, allowed characters: A-Za-z0-9_-)
categoryTreeName - names of category tree in various languages
categoryTreeAttributes - identifiers of the product attributes assigned to the whole category tree (as required for products in each category of the category tree)
categories - part of the categories information
identifier - unique (within the category tree) category identifier (max. 16 characters, allowed characters: A-Za-z0-9_-)
parent - parent category identifier (if empty or there is no "parent" key, the category is the main category)
name - names of the category in various languages
attributes - identifiers of the product attributes assigned to the category (as required for products in this category)
seo - data to improve the positioning in search engines results
www - information to facilitate and enrich the presentation of category information on websites

Example of a response (JSON):

{  
  "all":"3",
  "rejected":"1",
  "unique":"2",
  "replaced":"1",
  "new":"1",
  "parameters":[]
}

Fields description:

all - number of all category trees in the request
rejected - number of category trees that can not be properly handled
unique - number of unique (relative to category tree identifier) category trees in the request
replaced - number of category trees that have been replaced in the database
new - number of category trees that have been added to the database
parameters - correct/default query string parameters

Delete category trees | RESTful API: categories

https://epim.one/api/api-identifier/categories

Method: DELETE

The request is sent by an external system. It is necessary to send a list of category trees identifiers (as a JSON data) that you want to delete. The application deletes the category tree(s) in its database and responds with a short report.

Example of a request (curl):

curl -X DELETE "https://epim.one/api/api-identifier/categories" -u username:password -H "Content-Type: application/json" --data-binary "@categoryTreeIdentifiers.json"

The categoryTreeIdentifiers.json file example (UTF-8 encoded):

[  
  "TC1",
  "TC2"
]

Example of a response (JSON):

{  
  "deletedCategoryTrees":"2",
  "parameters":[]
}

Fields description:

deletedCategoryTrees - number of deleted category trees
parameters - correct/default query string parameters

Delete categories | RESTful API: categories

https://epim.one/api/api-identifier/categories?category-tree-identifier={identifier}

Method: DELETE

The request is sent by an external system. It is necessary to send a list of category identifiers (as a JSON data) that you want to delete and specify their category tree in the "category-tree-identifier" parameter. The application deletes the categories in its database and responds with a short report.

Query string parameters:

category-tree-identifier - identifier of the category tree containing the categories to be deleted

Example of a request (curl):

curl -X DELETE "https://epim.one/api/api-identifier/categories?category-tree-identifier=TC1" -u username:password -H "Content-Type: application/json" --data-binary "@categoryIdentifiers.json"

The categoryIdentifiers.json file example (UTF-8 encoded):

[  
  "C1",
  "SC2"
]

Example of a response (JSON):

{  
  "deletedCategories":"2",
  "parameters":{
    "category-tree-identifier":"TC1"
  }
}

Fields description:

deletedCategories - number of deleted categories
parameters - correct/default query string parameters

Run synchronization trigger | RESTful API: synchronization triggers

https://epim.one/api/api-identifier/synchronizations/run/{trigger-identifier}

Method: GET

The request is sent by an external system. The application runs the synchronization for the specified trigger identifier and responds with the status of the running synchronization.

Query string parameters:

trigger-identifier - the identifier of the synchronization trigger you want to run

Example of a request (curl):

curl -X GET "https://epim.one/api/api-identifier/synchronizations/run/tr67" -u username:password

Example of a response (JSON):

response with "in progress" status - the percentage progress of the triggered synchronization is given, as well as a 32-character progress identifier ("progress-id") for later checking the synchronization progress (see "Check status of synchronization trigger" section):{ "status":"in progress", "trigger-identifier":"tr67", "starting-time":"2021-04-15 10:20:03", "info":"52.65%", "progress-id":"sskYwG9068tDoSy7nfD7Dbzxj6iUSo9g" }
response with "done" status - means that the synchronization has already finished and the statistics of the completed synchronization are provided in the "info" field:{ "status":"done", "trigger-identifier":"tr67", "starting-time":"2021-04-15 11:15:23", "info":"Source: CompanyXYZ | Target: CompanyABC | Creation of new products: yes | Deletion of products: yes | Overwriting of additional global attributes: yes | Selected products: 1000 | Created products: 0 | Modified products: 1000 | Deleted products: 0 | Classified products: 0 | Reclassified products: 0 | Products with deleted class: 0 | Overwritten additional global attributes: 0 | Created additional global attributes: 0" }
response with "error" status - means that the synchronization has ended with an error provided in the "info" field:{ "status":"error", "trigger-identifier":"tr67", "starting-time":"2021-04-15 08:34:09", "info":"This operation is already in progress (started by userA)." }

Check status of synchronization trigger | RESTful API: synchronization triggers

https://epim.one/api/api-identifier/synchronizations/check/{progress-id}

Method: GET

The request is sent by an external system. The application responds with the current status of the running synchronization. The synchronization process is identified by "progress-id", returned by the system when the synchronization is run (see "Run synchronization trigger" section).

Query string parameters:

progress-id - the progress identifier of the synchronization trigger, returned by the system when the synchronization is run (the "progress-id" field in the response with the status "in progress")

Example of a request (curl):

curl -X GET "https://epim.one/api/api-identifier/synchronizations/check/sskYwG9068tDoSy7nfD7Dbzxj6iUSo9g" -u username:password

Example of a response (JSON):

response with "in progress" status - the percentage progress of the triggered synchronization is given:{ "status":"in progress", "trigger-identifier":"tr67", "starting-time":"2021-04-15 10:20:03", "info":"87.10%", "progress-id":"sskYwG9068tDoSy7nfD7Dbzxj6iUSo9g" }
response with "done" status - means that the synchronization has already finished and the statistics of the completed synchronization are provided in the "info" field:{ "status":"done", "trigger-identifier":"tr67", "starting-time":"2021-04-15 10:20:03", "info":"Source: CompanyXYZ | Target: CompanyABC | Creation of new products: yes | Deletion of products: yes | Overwriting of additional global attributes: yes | Selected products: 1000 | Created products: 0 | Modified products: 1000 | Deleted products: 0 | Classified products: 0 | Reclassified products: 0 | Products with deleted class: 0 | Overwritten additional global attributes: 0 | Created additional global attributes: 0" }
response with "error" status - means that the synchronization has ended with an error provided in the "info" field:{ "status":"error", "trigger-identifier":"tr67", "starting-time":"2021-04-15 10:20:03", "info":"Attributes conflicted: Attr1: attribute (logical) vs. attribute (numeric)" }

Handle a list of new, modified and deleted products | External API: products

Method: PUT

The request is sent by the application. Company receives the request and handles identifiers of products, that has been added, modified or deleted in the application.

Example of a request (JSON):

{  
  "new":[  
    "XYZ123",
    "XYZ245",
    ...
  ],
  "modified":[  
    "XYZ567",
    "XYZ568",
    ...
  ],
  "deleted":[  
    "XYZ45",
    "XYZ12",
    ...
  ]
}