ePIM.one RESTful API 5.2 documentation


Introduction

The purpose of the document is to define the communication principles of the ePIM.one 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/company/resource?parameters

  • api - the beginning of the address pointing to the API resource
  • company - company name
  • resource - the resource the request refers to
  • parameters - query string parameters

Example (request refers to products of the XYZ company):

https://epim.one/api/XYZ/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":"merge","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 | ePIM.one API: products

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

Method: GET

The request is sent by an external system. ePIM.one 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/XYZ/products?date-from=2022-02-15" -u XYZ: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 | ePIM.one API: products

https://epim.one/api/XYZ/products/filter?wildcards={false/true}&as-supplier={identifier}

Method: GET

The request is sent by an external system. ePIM.one 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:

  • wildcards (default is "false") - specifies whether wildcards are disabled or enabled in filtering ("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/XYZ/products/filter" -u XYZ:password -H "Content-Type: application/json" --data-binary "@filterData.json"

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

{ "descriptionShort":{ "pl":"kana" }, "gtin":"45", "attributes":{ "M1":{ "pl":"wart" }, "L2":"false", "S3":"v1", "N4":"4", "R5":"1..3" }, "labels":{ "identifiers":[ "Sold", "Gold" ], "selection_type":"at_least_one" }, "totalDescriptionCompleteness":{ "from":"20", "to":"40" }, "lastModifiedDate":{ "type":"last", "number":"2", "unit":"day", "includingCurrent":"true" }, "creationDate":{ "type":"range", "to":"2016-06-01 00:00:00" } }

Description of filter fields:

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

Remarks:

  • "language field" has keys corresponding to the two-letter language abbreviations, for example: "en", "pl"
  • "true/false field" has the following filter values:
    • true - meaning "yes"
    • false - meaning "no"
  • "reachInfo field" has the following 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"
  • "date field" has the following filter keys:
    • type - possible values:
      • last - filtering by relative dates ("in the last n days/weeks/months" etc.)
      • range - filtering by "range" of dates (from-to)
    • number (filter "last") - number of last hours/days/weeks covering the filtered dates [1-999]
    • unit (filter "last") - possible values:
      • day - full calendar day
      • week - full calendar week
      • month - full calendar month
      • year - full calendar year
    • includingCurrent (filter "last") - possible values:
      • false (default value) - the current day/week/month/year is not included/counted in the indicated "last" period
      • true - the current day/week/month/year is included/counted in the indicated "last" period
    • 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 field" has the following filter keys:
    • type - possible values:
      • last - filtering by relative dates ("in the last n days/weeks/months" etc.)
      • range - filtering by "range" of dates (from-to)
    • number (filter "last") - number of last hours/days/weeks covering the filtered dates [1-999]
    • unit (filter "last") - possible values:
      • minute - 60 seconds
      • hour - 60 minutes
      • day - full calendar day
      • week - full calendar week
      • month - full calendar month
      • year - full calendar year
    • includingCurrent (filter "last" and not for minute/hour unit) - possible values:
      • false (default value) - the current day/week/month/year is not included/counted in the indicated "last" period
      • true - the current day/week/month/year is included/counted in the indicated "last" period
    • 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 field" has the following filter keys:
    • from - from specified integer value [0-100]
    • to - to specified integer value [0-100]
  • If you want to use the logical operator "OR" for:
    • the filter group "lastModifiedDate" add to the filterData.json the entry "lastModifiedDateLogicalOperator":"OR"
    • the filter group "descriptionCompleteness" add to the filterData.json the entry "descriptionCompletenessLogicalOperator":"OR"

Example of a response (JSON):

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

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 \"selection_type\" in \"labels\"", "incorrect value of \"totalDescriptionCompleteness\"" ] }

Get product data | ePIM.one API: products

https://epim.one/api/XYZ/products?etim-version={number}&na-values={false/true}&as-supplier={identifier}&with-keys={false/true}

Method: GET

Request is sent by an external system. ePIM.one 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") - specified the version of ETIM classification ("9", "8", "7" or "6")
  • 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)
  • with-keys (default is "false") - specifies whether to add the "products" and "parameters" keys in the response ("false"/"true")

Example of a request (curl):

curl -X GET "https://epim.one/api/XYZ/products?na-values=true&with-keys=true" -u XYZ: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", "lastModifiedDate":"2018-01-02 10:17:23", "modifiedBy":"user2", "creationDate":"2017-03-01 09:34:24", "createdBy":"user1", "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" ], ... }, "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", ... } }, "descriptionCompleteness":{ "totalDescriptionCompleteness":"90", "generalDescriptionCompleteness":"80", "etimDescriptionCompletentess":"95", "orderDescriptionCompleteness":"100", "packingDescriptionCompleteness":"100", "priceDescriptionCompleteness":"91", "mimeDescriptionCompleteness":"80", "attributesDescriptionCompleteness":"80", "totalDescriptionCompletenessUserDefined":"86", "generalDescriptionCompletenessUserDefined":"81", "etimDescriptionCompletentessUserDefined":"85", "orderDescriptionCompletenessUserDefined":"100", "packingDescriptionCompletenessUserDefined":"100", "priceDescriptionCompletenessUserDefined":"70", "mimeDescriptionCompletenessUserDefined":"85", "attributesDescriptionCompletenessUserDefined":"75" }, "labels":[ "label1", "label2", ... ], "lastModifiedDateByType":{ "general":[ "date":"2018-01-02 10:17:23", "modifiedBy":"user2" ], "etim":[ "date":"2017-09-14 12:45:04", "modifiedBy":"user1" ], ... } }, { "productId":"XYZ124", "lastModifiedDate":"2018-01-02 11:34:22", ... } ], "parameters":{ "etim-version":"9", "na-values":"true", "with-keys":"true" } }

Fields description:

  • products - detailed information of the specified product(s):
    • productId - unique identifier of product
    • 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
    • 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
    • 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
    • descriptionCompleteness - part with the completeness indicators (given as a percentage) of the ETIM/product description (conform to default or user-defined completeness mask)
    • labels - product labels
    • lastModifiedDateByType - list of the last modification dates by product information type
  • parameters - correct/default query string parameters

 

Example of a request in a deprecated version (curl):

curl -X GET "https://epim.one/api/XYZ/products?with-keys=false" -u XYZ:password -H "Content-Type: application/json" --data-binary "@productsIDs.json"

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

[ "XYZ123", "XYZ124" ]

Example of a response in a deprecated version (JSON):

[ { "productId":"XYZ123", "lastModifiedDate":"2018-01-02 10:17:23", ... }, { "productId":"XYZ124", "lastModifiedDate":"2018-01-02 11:34:22", ... } ]

Get product data in a language-dependent version | ePIM.one API: products

https://epim.one/api/XYZ/products?lang={code}&etim-version={number}&na-values={false/true}&as-supplier={identifier}&with-keys={false/true}

Method: GET

Request is sent by an external system. ePIM.one 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") - specified the version of ETIM classification ("9", "8", "7" or "6")
  • 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)
  • with-keys (default is "false") - specifies whether to add the "products" and "parameters" keys in the response ("false"/"true")

Example of a request (curl):

curl -X GET "https://epim.one/api/XYZ/products?lang=en&na-values=true&with-keys=true" -u XYZ: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", "lastModifiedDate":"2018-01-02 10:17:23", "modifiedBy":"user2", "creationDate":"2017-03-01 09:34:24", "createdBy":"user1", "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", "na-values":"true", "with-keys":"true" } }

 

Example of a request in a deprecated version (curl):

curl -X GET "https://epim.one/api/XYZ/products?lang=en&with-keys=false" -u XYZ:password -H "Content-Type: application/json" --data-binary "@productsIDs.json"

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

[ "XYZ123", "XYZ124" ]

Example of a response in a deprecated version (JSON):

[ { "productId":"XYZ123", "lastModifiedDate":"2018-01-02 10:17:23", "modifiedBy":"user2", "creationDate":"2017-03-01 09:34:24", "createdBy":"user1", "overallInformation":{ ... }, "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" ], ... ] }, ... }, ... ]

Get product data as supplier | ePIM.one 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.

Put product data | ePIM.one API: products

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

Method: PUT

Request is sent by an external system. ePIM.one 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:
    • "merge" (default value) - in the case of an existing product, imported fields will be overwritten, others will remain unchanged
    • "complete" - in the case of an existing product, imported fields will be used to complete the product information (already existing product fields will remain unchanged)
    • "skip" - in the case of an existing product, it will be skipped
  • empty (only for "merge" mode) - one of the following values:
    • "false" (default value) - empty strings do not overwrite existing field values
    • "true" - empty strings 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/XYZ/products" -u XYZ: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" ], ... }, "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
  • 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":"merge", "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 | ePIM.one 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 | ePIM.one API: products

https://epim.one/api/XYZ/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. ePIM.one 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/XYZ/products" -u XYZ: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 | ePIM.one API: labels

https://epim.one/api/XYZ/labels?with-keys={false/true}

Method: GET

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

Query string parameters:

  • with-keys (default is "false") - specifies whether to add the "labelIdentifiers" key in the response ("false"/"true")

Example of a request (curl):

curl -X GET "https://epim.one/api/XYZ/labels?with-keys=true" -u XYZ:password

Example of a response (JSON):

{ "labelIdentifiers":[ "Public", "label1", "label2", "label3" ], "parameters":{ "with-keys":"true" } }

Fields description:

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

 

Example of a request in a deprecated version (curl):

curl -X GET "https://epim.one/api/XYZ/labels?with-keys=false" -u XYZ:password

Example of a response in a deprecated version (JSON):

[ "Public", "label1", "label2", "label3" ]

Get label data | ePIM.one API: labels

https://epim.one/api/XYZ/labels?with-keys={false/true}

Method: GET

Request is sent by an external system. ePIM.one 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.

Query string parameters:

  • with-keys (default is "false") - specifies whether to add the "labels" key in the response ("false"/"true")

Example of a request (curl):

curl -X GET "https://epim.one/api/XYZ/labels?with-keys=true" -u XYZ: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":{ "with-keys":"true" } }

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

 

Example of a request in a deprecated version (curl):

curl -X GET "https://epim.one/api/XYZ/labels?with-keys=false" -u XYZ:password -H "Content-Type: application/json" --data-binary "@labelIdentifiers.json"

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

[ "Public", "label1" ]

Example of a response in a deprecated version (JSON):

[ { "identifier":"Public", "permanent":"true", "letter":"P", "color":"grey", "description":"Products having this label are visible for external users" }, ... ]

Put label data | ePIM.one API: labels

https://epim.one/api/XYZ/labels

Method: PUT

Request is sent by an external system. ePIM.one 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.

Example of a request (curl):

curl -X PUT "https://epim.one/api/XYZ/labels" -u XYZ: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 | ePIM.one API: labels

https://epim.one/api/XYZ/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. ePIM.one 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/XYZ/labels" -u XYZ: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 | ePIM.one API: attributes

https://epim.one/api/XYZ/attributes?with-keys={false/true}

Method: GET

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

Query string parameters:

  • with-keys (default is "false") - specifies whether to add the "attributeIdentifiers" key in the response ("false"/"true")

Example of a request (curl):

curl -X GET "https://epim.one/api/XYZ/attributes?with-keys=true" -u XYZ:password

Example of a response (JSON):

{ "attributeIdentifiers":[ "M1", "L2", "S3", "N4", "R5", "A6" ], "parameters":{ "with-keys":"true" } }

Fields description:

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

 

Example of a request in a deprecated version (curl):

curl -X GET "https://epim.one/api/XYZ/attributes?with-keys=false" -u XYZ:password

Example of a response in a deprecated version (JSON):

[ "M1", "L2", "S3", "N4", "R5", "A6" ]

Get attribute data | ePIM.one API: attributes

https://epim.one/api/XYZ/attributes?with-keys={false/true}

Method: GET

Request is sent by an external system. ePIM.one 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.

Query string parameters:

  • with-keys (default is "false") - specifies whether to add the "attributes" key in the response ("false"/"true")

Example of a request (curl):

curl -X GET "https://epim.one/api/XYZ/attributes?with-keys=true" -u XYZ: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":{ "with-keys":"true" } }

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
      • 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

 

Example of a request in a deprecated version (curl):

curl -X GET "https://epim.one/api/XYZ/attributes?with-keys=false" -u XYZ: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 in a deprecated version (JSON):

[ { "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" }, ... ]

Put attribute data | ePIM.one API: attributes

https://epim.one/api/XYZ/attributes

Method: PUT

Request is sent by an external system. ePIM.one 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.

Example of a request (curl):

curl -X PUT "https://epim.one/api/XYZ/attributes" -u XYZ: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
    • 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 | ePIM.one API: attributes

https://epim.one/api/XYZ/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. ePIM.one 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/XYZ/attributes" -u XYZ: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 | ePIM.one API: relations by attribute

https://epim.one/api/XYZ/relations-by-attribute?with-keys={false/true}

Method: GET

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

Query string parameters:

  • with-keys (default is "false") - specifies whether to add the "relationByAttributeIdentifiers" key in the response ("false"/"true")

Example of a request (curl):

curl -X GET "https://epim.one/api/XYZ/relations-by-attribute?with-keys=true" -u XYZ:password

Example of a response (JSON):

{ "relationByAttributeIdentifiers":[ "ST", "ST1", ... ], "parameters":{ "with-keys":"true" } }

Fields description:

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

 

Example of a request in a deprecated version (curl):

curl -X GET "https://epim.one/api/XYZ/relations-by-attribute?with-keys=false" -u XYZ:password

Example of a response in a deprecated version (JSON):

[ "ST", "ST1", ... ]

Get relation by attribute data | ePIM.one API: relations by attribute

https://epim.one/api/XYZ/relations-by-attribute?with-keys={false/true}

Method: GET

Request is sent by an external system. ePIM.one 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.

Query string parameters:

  • with-keys (default is "false") - specifies whether to add the "relationsByAttribute" key in the response ("false"/"true")

Example of a request (curl):

curl -X GET "https://epim.one/api/XYZ/relations-by-attribute?with-keys=true" -u XYZ: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":{ "with-keys":"true" } }

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

 

Example of a request in a deprecated version (curl):

curl -X GET "https://epim.one/api/XYZ/relations-by-attribute?with-keys=false" -u XYZ:password -H "Content-Type: application/json" --data-binary "@relationByAttributeIdentifiers.json"

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

[ "ST", "EF1" ]

Example of a response in a deprecated version (JSON):

[ { "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" ] }, ... ]

Get relation by attribute data in a language-dependent version | ePIM.one API: relations by attribute

https://epim.one/api/XYZ/relations-by-attribute?lang={code}&with-keys={false/true}

Method: GET

Request is sent by an external system. ePIM.one 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.)
  • with-keys (default is "false") - specifies whether to add the "relationsByAttribute" and "parameters" keys in the response ("false"/"true")

Example of a request (curl):

curl -X GET "https://epim.one/api/XYZ/relations-by-attribute?lang=en&with-keys=true" -u XYZ: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", "with-keys":"true" } }

 

Example of a request in a deprecated version (curl):

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

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

[ "ST", "EF1", ]

Example of a response in a deprecated version (JSON):

[ { "identifier":"ST", "attribute":"STAT", "name":"Product status", "products":[ "XYZ", "XYZ212", ... ], "productValues":{ "XYZ212":[ "Core product (121)" ], ... }, "virtualProducts":[ "XYZ" ] }, ... ]

Put relation by attribute data | ePIM.one API: relations by attribute

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

Method: PUT

Request is sent by an external system. ePIM.one 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.

Example of a request (curl):

curl -X PUT "https://epim.one/api/XYZ/relations-by-attribute" -u XYZ: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 | ePIM.one API: relations by attribute

https://epim.one/api/XYZ/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. ePIM.one 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/XYZ/relations-by-attribute" -u XYZ: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 | ePIM.one API: suppliers

https://epim.one/api/XYZ/suppliers?with-keys={false/true}

Method: GET

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

Query string parameters:

  • with-keys (default is "false") - specifies whether to add the "supplierIdentifiers" key in the response ("false"/"true")

Example of a request (curl):

curl -X GET "https://epim.one/api/XYZ/suppliers?with-keys=true" -u XYZ:password

Example of a response (JSON):

{ "supplierIdentifiers":[ "sup1", "sup2", "sup3" ], "parameters":{ "with-keys":"true" } }

Fields description:

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

 

Example of a request in a deprecated version (curl):

curl -X GET "https://epim.one/api/XYZ/suppliers?with-keys=false" -u XYZ:password

Example of a response in a deprecated version (JSON):

[ "sup1", "sup2", "sup3" ]

Get supplier data | ePIM.one API: suppliers

https://epim.one/api/XYZ/suppliers?with-keys={false/true}

Method: GET

Request is sent by an external system. ePIM.one 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.

Query string parameters:

  • with-keys (default is "false") - specifies whether to add the "suppliers" key in the response ("false"/"true")

Example of a request (curl):

curl -X GET "https://epim.one/api/XYZ/suppliers?with-keys=true" -u XYZ: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":{ "with-keys":"true" } }

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

 

Example of a request in a deprecated version (curl):

curl -X GET "https://epim.one/api/XYZ/suppliers?with-keys=false" -u XYZ:password -H "Content-Type: application/json" --data-binary "@supplierIdentifiers.json"

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

[ "sup1", "sup2" ]

Example of a response in a deprecated version (JSON):

[ { "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" }, ... ]

Put supplier data | ePIM.one API: suppliers

https://epim.one/api/XYZ/suppliers

Method: PUT

Request is sent by an external system. ePIM.one 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.

Example of a request (curl):

curl -X PUT "https://epim.one/api/XYZ/suppliers" -u XYZ: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 | ePIM.one API: suppliers

https://epim.one/api/XYZ/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. ePIM.one 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/XYZ/suppliers" -u XYZ: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 | ePIM.one API: buyers

https://epim.one/api/XYZ/buyers?with-keys={false/true}

Method: GET

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

Query string parameters:

  • with-keys (default is "false") - specifies whether to add the "buyerIdentifiers" key in the response ("false"/"true")

Example of a request (curl):

curl -X GET "https://epim.one/api/XYZ/buyers?with-keys=true" -u XYZ:password

Example of a response (JSON):

{ "buyerIdentifiers":[ "buy1", "buy2", "buy3" ], "parameters":{ "with-keys":"true" } }

Fields description:

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

 

Example of a request in a deprecated version (curl):

curl -X GET "https://epim.one/api/XYZ/buyers?with-keys=false" -u XYZ:password

Example of a response in a deprecated version (JSON):

[ "buy1", "buy2", "buy3" ]

Get buyer data | ePIM.one API: buyers

https://epim.one/api/XYZ/buyers?with-keys={false/true}

Method: GET

Request is sent by an external system. ePIM.one 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.

Query string parameters:

  • with-keys (default is "false") - specifies whether to add the "buyers" key in the response ("false"/"true")

Example of a request (curl):

curl -X GET "https://epim.one/api/XYZ/buyers?with-keys=true" -u XYZ: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":{ "with-keys":"true" } }

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

 

Example of a request in a deprecated version (curl):

curl -X GET "https://epim.one/api/XYZ/buyers?with-keys=false" -u XYZ:password -H "Content-Type: application/json" --data-binary "@buyerIdentifiers.json"

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

[ "buy1", "buy2" ]

Example of a response in a deprecated version (JSON):

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

Put buyer data | ePIM.one API: buyers

https://epim.one/api/XYZ/buyers

Method: PUT

Request is sent by an external system. ePIM.one 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.

Example of a request (curl):

curl -X PUT "https://epim.one/api/XYZ/buyers" -u XYZ: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 | ePIM.one API: buyers

https://epim.one/api/XYZ/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. ePIM.one 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/XYZ/buyers" -u XYZ: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 | ePIM.one API: categories

https://epim.one/api/XYZ/categories?with-keys={false/true}

Method: GET

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

Query string parameters:

  • with-keys (default is "false") - specifies whether to add the "categoryTreeIdentifiers" key in the response ("false"/"true")

Example of a request (curl):

curl -X GET "https://epim.one/api/XYZ/categories?with-keys=true" -u XYZ:password

Example of a response (JSON):

{ "categoryTreeIdentifiers":[ "TC1", "TC2" ], "parameters":{ "with-keys":"true" } }

Fields description:

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

 

Example of a request in a deprecated version (curl):

curl -X GET "https://epim.one/api/XYZ/categories?with-keys=false" -u XYZ:password

Example of a response in a deprecated version (JSON):

[ "TC1", "TC2" ]

Get category tree data | ePIM.one API: categories

https://epim.one/api/XYZ/categories?with-keys={false/true}

Method: GET

Request is sent by an external system. ePIM.one 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.

Query string parameters:

  • with-keys (default is "false") - specifies whether to add the "categoryTrees" key in the response ("false"/"true")

Example of a request (curl):

curl -X GET "https://epim.one/api/XYZ/categories?with-keys=true" -u XYZ: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":{ "with-keys":"true" } }

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

 

Example of a request in a deprecated version (curl):

curl -X GET "https://epim.one/api/XYZ/categories?with-keys=false" -u XYZ:password -H "Content-Type: application/json" --data-binary "@categoryTreeIdentifiers.json"

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

[ "TC1", "TC2" ]

Example of a response in a deprecated version (JSON):

[ { "categoryTreeIdentifier":"TC1", "categoryTreeName":{ "pl":"Sklep1", "en":"Shop1", ... }, ... }, ... ]

Put category tree data | ePIM.one API: categories

https://epim.one/api/XYZ/categories

Method: PUT

Request is sent by an external system. ePIM.one 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.

Example of a request (curl):

curl -X PUT "https://epim.one/api/XYZ/categories" -u XYZ: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 | ePIM.one API: categories

https://epim.one/api/XYZ/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. ePIM.one 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/XYZ/categories" -u XYZ: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 | ePIM.one API: categories

https://epim.one/api/XYZ/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. ePIM.one 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/XYZ/categories?category-tree-identifier=TC1" -u XYZ: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 | ePIM.one API: synchronization triggers

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

Method: GET

The request is sent by an external system. ePIM.one 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/XYZ/synchronizations/run/tr67" -u XYZ: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 | ePIM.one API: synchronization triggers

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

Method: GET

The request is sent by an external system. ePIM.one 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/XYZ/synchronizations/check/sskYwG9068tDoSy7nfD7Dbzxj6iUSo9g" -u XYZ: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 in ePIM.one | External API: products

Method: PUT

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

Example of a request (JSON):

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