Data Management API

In order to use all functions of OMNICOMMERCE, it is essential to use the Data Management API. Data Management API plays the role of creating/modifying/deleting customer product information in the workspace.

caution

Up to 100 items per request can be created, updated, and deleted at once.
The Data Management API has a limitation of 5 requests per second (RPS), so it is recommended to submit a large amount of data by using the POST method in batches of 100 records each.

API Endpoint

The default API Endpoint is as follows, and the current latest version is 2022-08.

https://api.kr.omnicommerce.ai/2022-08/

Product information management API

POST /management/products: Registration of new product information

caution

If the same product ID already exists in the workspace, the data will be overwritten.

Request Header

Name	Required	Type	Description
X-Api-Key	Required	String	API Key (refer to API Authentication Guide)
Content-Type	Required	String	Content Type. Only `Application/json` is supported.

Request Body

caution

The product ID is internally treated as a Unique Key and is also used in the form of a URL Path Parameter when calling API. Accordingly, URL Unreserved Characters(0-9 a-z A-Z - . _ ~) based on [RFC3986] is used only.

Name	Required	Type	Description
options	Optional	List[String]	Update options as string enumerate type like below: `BLOCK_DUPLICATES`: Restrict duplicate entries for the same product ID already registered in the workspace.
products	Required	List	List of product information. A maximum of 100 is possible.
├ products[].id	Required	String	Product ID (Max length 50 characters). The product ID is used as a unique key in the corresponding workspace. If there is a duplicate product ID, it will be overwritten.
├ products[].url	Required	String	The URL of the representative image of the product.
├ products[].detection	Required	String	Enter one of the specified values in Detection Field . (Example: If the product is kind of top: `TOP`)
├ products[].salesUrl	Required	String	URL of the page where the product is being sold
├ products[].mobileSalesUrl	Optional	String	Mobile version URL of the page where the product is being sold
└ products[].metadata	Optional	Object	Various product information managed by the customer, such as product name, brand, price, season, and discount rate. (See: Product metadata)

info

It is strongly recommended to contain detection information for accurate recommendations related to the product you are selling during an image when using Visual Recommendation.

Request example

1) If options is BLOCK_DUPLICATES and metadata is present (name, price)

{
    "options": ["BLOCK_DUPLICATES"],
    "products": [
        {
            "id": "A1000",
            "url": "https://image-url.jpg",
            "salesUrl": "https://sales_url.com",
            "mobileSalesUrl": "https://m.sales_url.com",
            "detection": "TOP",
            "metadata": {
                "productName": "product name",
                "originPrice": 10000,
                "currency": "KRW"
            }
        },
        {
            "id": "A1001",
            "url": "https://image-url2.jpg",
            "salesUrl": "https://sales_url.com",
            "mobileSalesUrl": "https://m.sales_url.com",
            "detection": "WHOLEBODY",
            "metadata": {
                "productName": "product name2",
                "originPrice": 20000,
                "currency": "KRW"
            }
        },
        {
            "id": "A1002",
            "url": "https://image-url3.jpg",
            "salesUrl": "https://sales_url3.com",
            "mobileSalesUrl": "https://m.sales_url3.com",
            "detection": "PANTS",
            "metadata": {
                "productName": "product name3, 상품명3",
                "originPrice": 30000,
                "currency": "KRW"
            }
        }
    ]
}

2) Adding products without metadata field

{
    "products": [
        {
            "id": "A1000",
            "url": "https://image-url.jpg",
            "salesUrl": "https://sales_url.com",
            "detection": "TOP"
        },
        {
            "id": "A1001",
            "url": "https://image-url2.jpg",
            "salesUrl": "https://sales_url.com",
            "detection": "WHOLEBODY"
        },
        {
            "id": "A1002",
            "url": "https://image-url3.jpg",
            "salesUrl": "https://sales_url3.com",
            "mobileSalesUrl": "https://m.sales_url3.com",
            "detection": "PANTS"
        }
    ]
}

Response

Name	Type	Description
accept	Integer	The number of items for which an asynchronous registration operation was successfully requested.
failure	Integer	The number of items for which the asynchronous registration operation failed.
failureList	List	Information on the reason for the failure.
├ failureList[].id	String	Product id of failure case.
└ failureList[].errors	String	Description of the reason for the failure.

Response Example

202 Accepted

An example case of an error occurs for all requested items.

{
  "accept": 0,
  "failure": 3,
  "failureList": [
    {
      "id": "A1000",
      "errors": "bad reqeust"
    },
    {
      "id": "A1001",
      "errors": "fail to prove image from url."
    },
    {
      "id": "A1002",
      "errors": "Block duplicate products."
    }
  ]
}

An example of when a request was made for even one item.

{
  "accept": 3,
  "failure": 0,
  "failureList": []
}

{
  "accept": 1,
  "failure": 2,
  "failureList": [
    {
      "id": "A1000",
      "errors": "bad reqeust"
    },
    {
      "id": "A1002",
      "errors": "Block duplicate products."
    }
  ]
}

PUT /management/products: Modification of product information

It is used to modify product information based on product ID.

Example) When the “product name” of the product is changed.

Before Change

Product ID : AE00001
Product Name : Linen Summer Pants
Price : 10 USD

Change Request

Product Name : Linen Pants

After Change

Product ID : AE00001
Product Name : Linen Pants
Price : 10 USD

info

Only the requested information will be modified, other information will remain the same.

Request Header

Name	Required	Type	Description
X-Api-Key	Required	String	API Key (refer to API Authentication Guide)
Content-Type	Required	String	Content Type. Only `Application/json` is supported.

Request Body

Name	Required	Type	Description
products	Required	List	List of product information. A maximum of 100 is possible.
├ products[].id	Required	String	Product ID. The product ID is used as a unique key in the corresponding workspace. If there is a duplicate product ID, it will be overwritten.
├ products[].salesUrl	Required	String	URL of the page where the product is being sold
├ products[].mobileSalesUrl	Optional	String	Mobile version URL of the page where the product is being sold
└ products[].metadata	Optional	Object	Various product information managed by the customer, such as product name, brand, price, season, and discount rate. (See: Product metadata)

Request Example

{
  "products": [
    {
      "id": "A1000",
      "metadata": {
        "productName": "product name3"
      }
    },
    {
      "id": "A1001",
      "metadata": {
        "productName": "product name4",
        "originPrice": 200
      }
    }
  ]
}

Response

Name	Type	Description
accept	Integer	The number of items for which an asynchronous registration operation was successfully requested.
failure	Integer	The number of items for which the asynchronous registration operation failed.
failureList	List	Information on the reason for the failure.
├ failureList[].id	String	Product id of failure case.
└ failureList[].errors	String	Description of the reason for the failure.

Response Example

202 Accepted

An example case of an error occurs for all requested items.

{
    "accept": 0,
    "failure": 2,
    "failureList": [
        {
            "id": "A1000",
            "errors": "bad reqeust"
        },
        {
            "id": "A1001",
            "errors": "fail to prove image from url."
        }
    ]
}

An example of when a request was made for even one item.

{
    "accept": 2,
    "failure": 0,
    "failureList": []
}

{
    "accept": 1,
    "failure": 1,
    "failureList": [
        {
            "id": "A1000",
            "errors": "bad reqeust"
        }
    ]
}

DELETE /management/products: Delete registered product

Deletes products registered in Workspace based on product ID.

Request Header

Name	Required	Type	Description
X-Api-Key	Required	String	API Key (refer to API Authentication Guide)

Request Body

Name	Required	Type	Description
productIds	Required	List[String]	List of product IDs to be deleted. A maximum of 100 is possible.

Request example

{
    "productIds": [
        "A1000", "A1001", "A1002"
    ]
}

Response

Name	Type	Description
accept	Integer	The number of items for which an asynchronous registration operation was successfully requested.
failure	Integer	The number of items for which the asynchronous registration operation failed.
failureList	List	Information on the reason for the failure.
├ failureList[].id	String	Product id of failure case.
└ failureList[].errors	String	Description of the reason for the failure.

Response Example

202 Accepted

Success Case

{
  "accept": 3,
  "failure": 0,
  "failureList": []
}

An example case of an error occurs for all requested items.

{
    "accept": 0,
    "failure": 2,
    "failureList": [
        {
            "id": "A1000",
            "errors": "bad reqeust"
        }
    ]
}

Data Management API

API Endpoint​

Product information management API​

POST /management/products: Registration of new product information​

Request Header​

Request Body​

Request example​

Response​

Response Example​

PUT /management/products: Modification of product information​

Request Header​

Request Body​

Request Example​

Response​

Response Example​

DELETE /management/products: Delete registered product​

Request Header​

Request Body​

Request example​

Response​

Response Example​

API Endpoint

Product information management API

POST /management/products: Registration of new product information

Request Header

Request Body

Request example

Response

Response Example

PUT /management/products: Modification of product information

Request Header

Request Body

Request Example

Response

Response Example

DELETE /management/products: Delete registered product

Request Header

Request Body

Request example

Response

Response Example