Data Management API

OMNICOMMERCE 의 모든 기능을 사용하기 위해서는 필수적으로 Data Management API를 사용하여야 합니다. Data Management API 는 고객사의 상품 정보를 OMNICOMMERCE 으로 생성 / 수정 / 삭제 하는 역할을 수행 합니다.

주의

한 Request 당 최대 100 개 까지 한번에 create, update, delete 가능 합니다.
Data Management API는 5 RPS(Request per second)의 제한이 있어 많은 데이터를 등록 시 100건씩 POST 로 전달하시는 걸 권장드립니다.

API Endpoint

기본 API Endpoint는 아래와 같으며, 현재 최신 버전은 2022-08 입니다.

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

상품 정보 관리 API

POST /management/products: 신규 상품 등록

상품 ID 별로 상품 정보를 새롭게 등록합니다.

주의

기존에 동일한 상품ID가 존재하는 경우 데이터를 덮어쓰게 됩니다.

Request Header

Name	Required	Type	Description
X-Api-Key	필수	String	API Key (참조: API 인증 가이드)
Content-Type	필수	String	요청 Type. Application/json 만 지원합니다.

Request Body

주의

상품 아이디는 내부적으로 Unique Key로 처리되며 API 호출시 URL Path Parameter의 형태로도 사용됩니다. 이에 따라 [RFC3986]기준 URL Unreserved Characters(0-9 a-z A-Z - . _ ~)만 사용이 가능합니다.

Name	Required	Type	Description
options	선택	List[String]	입력 옵션. 아래와 같이 미리 정의된 String Enum type으로 넣어줍니다: `BLOCK_DUPLICATES`: 이미 Workspace에 포함되어 있는 동일한 상품 ID에 대한 중복 입력이 제한됩니다.
products	필수	List	상품 정보의 List. 최대 100개 까지 가능합니다.
├ products[].id	필수	String	상품 아이디 (최대 50자): 상품 아이디는 해당 Workspace 에서 Unique Key 로 사용됩니다. 중복되는 상품 아이디가 있다면 덮어쓰게 됩니다.
├ products[].url	필수	String	상품의 대표 이미지 URL
├ products[].detection	필수	String	Detection 정보 에 명시된 값 중 하나를 입력합니다. (예: 판매하는 상품이 상의 인 경우: TOP)
├ products[].salesUrl	필수	String	상품이 판매되고 있는 페이지의 URL
├ products[].mobileSalesUrl	선택	String	상품이 판매되고 있는 페이지의 모바일 버전 URL
└ products[].metadata	선택	Object	상품명, 브랜드, 가격, 시즌, 할인율 등 고객 사가 관리하는 다양한 상품 정보들 입니다. (참조: 상품 Meta정보)

정보

유사상품 추천을 사용하고자 하시는경우, 필히 판매하시는 상품 기준의 Detection 정보를 입력하여 전달해주셔야 추천의 정확도가 좋아집니다.

Request example

1) options가 BLOCK_DUPLICATES 이고, metadata가 있는경우 (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, 상품명2",
                "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) metadata 입력을 안하는 경우

{
    "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	비동기적인 등록 작업이 성공적으로 요청된 항목의 수
failure	Integer	비동기적인 등록 작업이 실패한 항목의 수
failureList	List	실패 사유에 대한 정보
├ failureList[].id	String	상품 아이디
└ failureList[].errors	String	실패 사유에 대한 설명

Response Example

202 Accepted

요청한 모든 항목에 대해 Error가 발생한 경우

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

하나의 항목이라도 요청이 들어간 경우

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

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

PUT /management/products: 상품 정보 수정

상품 아이디를 기준으로 상품의 정보를 수정 하기 위해 사용 합니다.

예시) 상품의 “상품명"이 변경 된경우

변경 전

상품아이디 : AE00001
상품명 : 린넨여름팬츠
가격 : 10,000

변경 요청

상품명 : 린넨팬츠

변경 후

상품아이디 : AE00001
상품명 : 린넨팬츠
가격 : 10,000

정보

요청한 정보만 수정 되고 다른 정보들은 그대로 유지 됩니다.

Request Header

Name	Required	Type	Description
X-Api-Key	필수	String	API Key (참조: API 인증 가이드)
Content-Type	필수	String	요청 Type. Application/json 만 지원합니다.

Request Body

Name	Required	Type	Description
products	필수	List	상품 정보의 List. 최대 100개 까지 가능합니다.
products[].id	필수	String	상품 아이디: 상품 아이디는 해당 Workspace 에서 Unique Key 로 사용됩니다. 중복되는 상품 아이디가 있다면 덮어쓰게 됩니다.
├ products[].salesUrl	필수	String	상품이 판매되고 있는 페이지의 URL
├ products[].mobileSalesUrl	선택	String	상품이 판매되고 있는 페이지의 모바일 버전 URL
└ products[].metadata	선택	Object	상품명, 브랜드, 가격, 시즌, 할인율 등 고객 사가 관리하는 다양한 상품 정보들 입니다. (참조: 상품 Meta정보)

Request Example

{
  "products": [
    {
      "id": "A1000",
      "metadata": {
        "productName": "product name3, 상품명"
      }
    },
    {
      "id": "A1001",
      "metadata": {
        "productName": "product name4, 상품명4",
        "originPrice": 20000
      }
    }
  ]
}

Response

Name	Type	Description
accept	Integer	비동기적인 등록 작업이 성공적으로 요청된 항목의 수
failure	Integer	비동기적인 등록 작업이 실패한 항목의 수
failureList	List	실패 사유에 대한 정보
├ failureList[].id	String	상품 아이디
└ failureList[].errors	String	실패 사유에 대한 설명

Response Example

202 Accepted

모든 항목에서 에러가 발생한 경우

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

하나의 항목이라도 요청이 들어간 경우

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

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

DELETE /management/products: 등록된 상품 삭제

상품 아이디를 기준으로 Workspace 에 등록된 상품을 삭제합니다.

Request Header

Name	Required	Type	Description
X-Api-Key	필수	String	API Key (참조: API 인증 가이드)

Request Body

Name	Required	Type	Description
productIds	필수	List[String]	상품 아이디의 List. 최대 100개 까지 가능합니다.

Request example

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

Response

Name	Type	Description
accept	Integer	비동기적인 등록 작업이 성공적으로 요청된 항목의 수
failure	Integer	비동기적인 등록 작업이 실패한 항목의 수
failureList	List	실패 사유에 대한 정보
├ failureList[].id	String	상품 아이디
└ failureList[].errors	String	실패 사유에 대한 설명

Response Example

202 Accepted

요청 성공

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

모든 항목에서 에러가 발생한 경우

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

Data Management API

API Endpoint​

상품 정보 관리 API​

POST /management/products: 신규 상품 등록​

Request Header​

Request Body​

Request example​

Response​

Response Example​

PUT /management/products: 상품 정보 수정​

Request Header​

Request Body​

Request Example​

Response​

Response Example​

DELETE /management/products: 등록된 상품 삭제​

Request Header​

Request Body​

Request example​

Response​

Response Example​

API Endpoint

상품 정보 관리 API

POST /management/products: 신규 상품 등록

Request Header

Request Body

Request example

Response

Response Example

PUT /management/products: 상품 정보 수정

Request Header

Request Body

Request Example

Response

Response Example

DELETE /management/products: 등록된 상품 삭제

Request Header

Request Body

Request example

Response

Response Example