coupang
POST/v2/providers/seller_api/apis/api/v1/marketplace/seller-products2609170000

商品注册

# 01

简介

商品注册

# 02

详细内容

API支持的买家用户地区:韩国,台湾

该API用于注册在酷澎上销售的商品。

创建商品时,发货地/退货地、品类、通知信息、属性信息等需要符合酷澎的标准。

请下载下方商品注册指南,获取更多详细信息。

下载 酷澎 OPENAPI 商品注册指南

免费购买属性配置(公开属性)自2020年10月12日起适用。

请下载下方新商品创建API指南,获取更多信息。

Download New product creation API guide (12 Oct 2020)

CGF/CGF Lite 的商品发布,请参考如下链接CGF/CGF Lite商品发布

创建Rocket Growth产品,请参考以下文档:

路径

POST/v2/providers/seller_api/apis/api/v1/marketplace/seller-products

示例端点

https://api-gateway.coupang.com/v2/providers/seller_api/apis/api/v1/marketplace/seller-products

URL API Name

CREATE_PRODUCT
# 03

请求体参数

请求参数

请求体参数

NameTypeDescription
displayCategoryCode*number
显示品类代码

可下载品类列表查询API或品类信息excel,查看显示品类代码

※ 未输入时,品类可能会通过品类自动匹配服务自动注册。更多详细信息,请点击。
sellerProductName*string
注册商品名

订单上的商品名

最大长度:100个字符
vendorId*string
卖家ID

酷澎提供给卖家的固有代码

可登录Wing查询
saleStartedAt*string
销售开始日期

格式为"yyyy-MM-dd'T'HH:mm:ss"
saleEndedAt*string
销售结束日期

格式为"yyyy-MM-dd'T'HH:mm:ss" , *年份可选择至2099年
displayProductNamestring
显示商品名

实际在酷澎销售页面上显示的商品名

建议输入与[brand]+[generalProductName]相同的商品名,未输入商品名也可注册商品。

未输入时,可能会显示[brand]+

[generalProductName]或[sellerProductName]。

最大长度:100个字符
brandstring
品牌

输入品牌的韩文/英文标准名称

无需输入空格和特殊字符
generalProductNamestring
商品名

不包括购买属性[Attribute exposed]信息(尺寸、颜色等)。可另行添加型号名
productGroupstring
商品群

即商品类型; 输入商品群时,可参考显示品类的最下位名称。

与商品名[generalProductName]重复时,无需输入
deliveryMethod*string
配送方式
参数名 状态
SEQUENCIAL 一般配送 (依次发货)
COLD_FRESH 冷冻生鲜
MAKE_ORDER 订制
AGENT_BUY 代购
VENDOR_DIRECT 上门安装或卖家直接配送
INSTRUCTURE 上门安装
MAKE_ORDER_DIRECT 定制安装(卖家直接配送)
“INSTRUCTURE”及“MAKE_ORDER_DIRECT” 已合并为“VENDOR_DIRECT”。

若为生鲜食品,配送方式须选择冷冻生鲜,而不是一般配送。
deliveryCompanyCode*string
物流公司代码
点击下面链接查看物流代码列表
link for courier code
deliveryChargeType*string
配送费类型
参数名 状态
FREE 免费配送
NOT_FREE 付费配送
CHARGE_RECEIVED 运费到付
CONDITIONAL_FREE 指定条件包邮
  • 设置免费配送 设置初始退货运费(单程)[deliveryChargeOnReturn]及退货运费金额(单程)[returnCharge]
  • 设置付费配送
设置基本运费[deliveryCharge]及退货运费金额(单程)
  • 设置指定条件包邮
设置基本运费及退货运费金额(单程)
  • 设置运费到付(COD:collect on delivery)
我们已单独列出了符合运费到付条件的品类,并通过酷澎卖家客服中心分享,以指导卖家。

※ 使用[CONDITIONAL_FREE]时,您可单独设置想要的指定条件包邮值。
deliveryCharge*number
基本运费

若为付费配送或指定条件包邮,请输入单程运费值。
freeShipOverAmount*number
免运费门槛

● 示例: 如果您想将指定条件包邮的门槛金额设置为10,000 韩元及以上,请先将[deliveryChargeType]设置为'CONDITIONAL_FREE',然后在[freeShipOverAmount]中输入10000。

※ 输入单位须大于100韩元 (以100为增量)

※ 免费配送时,请输入0
deliveryChargeOnReturn*number
初始退货运费

若为免费配送,则顾客支付退货运费
remoteAreaDeliverable*string
偏远地区配送与否
参数名 状态
Y 偏远地区可配送
N 偏远地区不配送
unionDeliveryType*string
捆绑配送与否
参数名 状态
UNION_DELIVERY 可捆绑配送
NOT_UNION_DELIVERY 不可捆绑配送
※ 捆绑配送条件

必须输入发货地信息(只有发货地信息相同的商品才能捆绑配送)

不可设置“不可运费到付”
returnCenterCode*string
退货中心代码

创建退货地后,输入可取货的退货中心代码
  • 可通过Wing或“退货地创建 API”来创建退货地
  • 无法创建退货地时,可输入“NO_RETURN_CENTERCODE”,直接注册退货地信息
※ 自动退货链接服务(Goodsflow)仅适用于签约物流公司,且必须输入退货中心代码。

※ 若为海外配送商品,请务必输入韩国退货地址和签约物流公司代码,创建退货中心代码。*海外配送商品退货地指南(点击)
returnChargeName*string
退货地名称

通过酷澎WING或“退货地查询API”注册退货地后确认

“查询退货地时,输入shippingPlaceName的显示值”
companyContactNumber*string
退货地联系方式

通过酷澎WING或“退货地查询API”注册退货地后确认
returnZipCode*string
退货地邮政编码

通过酷澎WING或“退货地查询API”注册退货地后确认
returnAddress*string
退货地址

通过酷澎WING或“退货地查询API”注册退货地后确认
returnAddressDetail*string
退货地详细地址

通过酷澎WING或“退货地查询API”注册退货地后确认
returnCharge*number
退货运费

回收退货商品时的单程运费

*只能输入初始退货运费100%~150%的值。
outboundShippingPlaceCode*number
发货地代码

选择捆绑配送时必填。可通过“发货地查询API”进行查询

选择海外代购(AGENT_BUY)时,只能输入海外地址。
vendorUserId*string
真实用户ID(酷澎WING ID)

属于卖家(Vendor)的用户ID
requested*boolean
是否自动申请批准

注册商品时,选择是否自动申请批准
  • false : 只保存已填写的内容,审批未通过 (如果您想要销售商品,请通过“商品批准申请API”或WING进行申请)
  • true : 保存并自动申请批准销售
items*object[]
卖家商品属性列表

最多可注册200个属性
itemName*
items[].itemName
string
卖家商品属性名

输入各属性名,并保证每个商品不重复

此属性名不显示在网站上,可能会随购买属性而发生变化

最大长度:150个字符
originalPrice*
items[].originalPrice
number
折扣率基准价(定价)

此为折扣前的价格,以显示折扣率(%)。如果输入的价格与销售价格相同,则显示为“酷澎价”。审批完成后可通过[修改各属性折扣率基准价]API修改
salePrice*
items[].salePrice
number
售价

输入售价。

“最初”注册商品时,只能在申请商品审批前输入售价。审批通过后,可通过[修改各属性价格]API修改
autoPricingInfo
items[].autoPricingInfo
object
自动定价配置。仅在首次商品注册且审批前可填;审批后请改用 [按 item 改价] API。映射至内部 OSellerProduct.autoPricingInfo
minSalePrice
items[].autoPricingInfo.minSalePrice
number
自动定价最低售价。必须小于已有的 salePrice
active
items[].autoPricingInfo.active
boolean
是否启用自动定价(true/false)
maximumBuyCount*
items[].maximumBuyCount
number
可售数量

输入可销售的库存数量。

“最初”注册商品时,只能在申请商品审批前输入可销售数量。审批通过后,可通过[修改各属性数量]API修改

最大数量:99999
maximumBuyForPerson*
items[].maximumBuyForPerson
number
人均最多可购买数量

每人最多可购买的数量。

如果没有限制,请输入“0”

(例如:如果输入的人均最多可购买数量为 100,最长购买期限为 3。那么这意味着,一个人在3天内最多可购买 100 件)
maximumBuyForPersonPeriod*
items[].maximumBuyForPersonPeriod
number
最长购买期限

设置某个时间段内每人可以购买的最大数量 。

如果没有限制,请输入“1”

(例如:如果输入的人均最多可购买数量为 100,最长购买期限为 3。那么这意味着,一个人在3天内最多可购买 100 件)
outboundShippingTimeDay*
items[].outboundShippingTimeDay
number
标准发货日(天)

请输入订单日期(D-Day)之后预计的发货日期(以天为单位)。

(输入“1”表示当日发货。输入“1”表示次日(D+1)发货。)
sameDayShipping
items[].outboundShippingTimeDay.sameDayShipping
object
当日发货配置
active
items[].outboundShippingTimeDay.sameDayShipping.active
boolean
是否启用当日发货
cutOffTimeHour
items[].outboundShippingTimeDay.sameDayShipping.cutOffTimeHour
integer
当日发货订单截止时间为10:00至23:00。
cutOffTimeMinute
items[].outboundShippingTimeDay.sameDayShipping.cutOffTimeMinute
integer
截止时间(分钟)。当 active=true 时,截止时间必须为 0。
cutOffTimeZone
items[].outboundShippingTimeDay.sameDayShipping.cutOffTimeZone
string
系统管理,当 active=true 时默认为“KR”。
unitCount*
items[].unitCount
number
单位数量

unitCount 字段定义了单个商品清单中所包含的独立单位数量。系统将利用此数值来计算并向终端用户显示“单位价格”(例如:每克、每件或每毫升的价格),以确保批发或组合商品的价格透明度。若商品仅由单一单位组成,请将此值设为 1
adultOnly*
items[].adultOnly
string
19岁及以上
参数名 状态
ADULT_ONLY 19岁及以上可购买
EVERYONE 无购买年龄限制(默认值)
taxType*
items[].taxType
string
是否需纳税
参数名 状态
TAX 需纳税(默认值)
FREE 无需缴税
parallelImported*
items[].parallelImported
string
是否为平行进口
参数名 状态
PARALLEL_IMPORTED 平行进口
NOT_PARALLEL_IMPORTED 平行进口(默认值)
※ 创建平行进口商品时,应注册进口申报单URL – 注册指南(点击)
overseasPurchased*
items[].overseasPurchased
string
是否为海外代购
Parameter Name 状态
OVERSEAS_PURCHASED 代购
NOT_OVERSEAS_PURCHASED 非代购(默认值)
※ 创建代购商品时,应注
pccNeeded*
items[].pccNeeded
boolean
是否需要PCC(个人通关代码)

海外代购商品需要PCC。

如果是海外代购(AGENT_BUY),产品PCC必须填写为true。
  • 默认值: 不需要 (false)
true 顾客输入PCC后即可购买(PCC包含在订单中)
false 顾客可购买,无需输入PCC
Parameter NameStatus
true
false
externalVendorSku
items[].externalVendorSku
string
卖家商品编号 (企业商品编号)

可任意设置卖家固有的商品编号值,输入值包含在订单查询API response中。
barcode
items[].barcode
string
条形码

贴在商品上的有效标准商品编号
emptyBarcode
items[].emptyBarcode
boolean
无条形码

若无条形码,则为True
emptyBarcodeReason
items[].emptyBarcodeReason
string
没有条形码的原因

最大长度:100个字符
modelNo
items[].modelNo
string
型号
extraProperties
items[].extraProperties
object
卖家商品属性的附加信息

Key : 以值的形态存在。可根据需要多次重复输入。
Key
items[].extraProperties.Key
string
certifications
items[].certifications
object[]
商品认证信息
certificationType
items[].certifications[].certificationType
string
认证信息类型

可通过“品类元数据查询API”获取认证信息类型

非认证对象品类:NOT_REQUIRED
certificationCode
items[].certifications[].certificationCode
string
商品认证信息编号

该编号由认证机构颁发
certificationAttachments
items[].certifications[].certificationAttachments
object[]
认证信息附件

认证机构提供的移动设备卖方许可证证书图像;

Map 的 key 固定为以下两个,只需要其中一个:
1)vendorPath:如果图片不是源于Coupang CDN Server
2)cdnPath:如果图片已经上传至Coupang CDN Server

注意: 用于注册手机电子产品类别(displayCategoryCode = 62600, 家电/数码>手机/平板电脑/配件>手机/平板电脑>手机>裸机),
需要上传以下两张图片:
  1. 移动通信事先同意或认证机构证明

  2. 零售商预先批准的认证标志或移动运营商的认证标志

Example:
"certifications": [
       {
         "certificationType": "MOBILE_DEVICE_DEALER_PERMIT",
         "certificationCode": "",
         "certificationAttachments": [
           {
              "vendorPath": "http://vendor.com/image/vendoritem/3001519145/cert.jpg"
           },
           {
              "vendorPath": "http://vendor.com/image/vendoritem/3001519145/logo.jpg"
          }
         ]
       }
]
searchTags
items[].searchTags
object[]
搜索词

可根据需要重复输入。["搜索词1","搜索词2"]

最多可输入20个搜索词,每个搜索词不得超过20个字符,不得输入 !@#$%^&*-+;:'. 外的其它特殊字符
images*
items[].images
object[]
图片列表

可根据需要重复输入
imageOrder*
items[].images[].imageOrder
number
图片标示顺序

0,1,2...
imageType*
items[].images[].imageType
string
图片类型

主图类型

可将3MB或以下的正方形图片以 JPG /PNG格式上传(最小 500 x 500 px,最大 5000 x 5000 px)
  • 必选
REPRESENTATION : 正方形主图
  • 可选
DETAIL : 其它图片(最多可上传9个)

USED_PRODUCT : 曾用图片(最多可上传4个)
cdnPath*
items[].images[].cdnPath
string
酷澎CDN路径

如果上传到酷澎CDN,请手动输入,且须在vendorPath和cdnPath中至少任选其一

最大长度:150个字符
vendorPath*
items[].images[].vendorPath
string
卖家图片路径

卖家使用的图像路径。 若路径以 http://为开头,则会被自动下载并添加至酷澎CDN。且须在vendorPath和cdnPath中至少任选其一

最大长度:200个字符
notices
items[].notices
object[]
商品通知信息列表

可通过“品类元数据查询API”或整体品类列表的Excel文件,查看并选择所需的通知信息项
noticeCategoryName
items[].notices[].noticeCategoryName
string
商品通知信息品类名

为各品类输入一个可用的商品通知信息品类

可通过“品类元数据查询API”或整体品类列表的Excel文件,查看并选择所需的通知信息项。
noticeCategoryDetailName
items[].notices[].noticeCategoryDetailName
string
商品通知信息品类详细名
content
items[].notices[].content
string
内容
attributes*
items[].attributes
object[]
属性列表(属性)

输入按品类确定的属性列表

可重复输入想要注册的购买属性数量

若购买属性(attribute exposed)的所有值都重复,则无法注册。

必须注册1个以上,可将不想输入的属性从attributes 列表中删除或将attributeValueName输入为 ""后发送。
attributeTypeName*
items[].attributes[].attributeTypeName
string
属性类型名

可通过“品类元数据查询API”或整体品类列表的Excel文件,查看并选择与品类合适的属性类型名

最大长度:25个字符
attributeValueName*
items[].attributes[].attributeValueName
string
属性值

输入单位时,请一并输入属性类型名[attributeTypeName]的值

(例如 :"200ml")

最大长度:30个字符
contents*
items[].contents
object[]
内容列表

可根据需要重复输入
contentsType*
items[].contents[].contentsType
string
内容类型
参数名称 含义
IMAGE 图片
IMAGE_NO_SPACE 图片 (无空白)
TEXT 文本
IMAGE_TEXT 图片-文本
TEXT_IMAGE 文本-图片
IMAGE_IMAGE 图片-图片
TEXT_TEXT 文本-文本
TITLE 标题
HTML HTML
contentDetails*
items[].contents[].contentDetails
object[]
详细内容列表
content*
items[].contents[].contentDetails[].content
string
内容
detailType*
items[].contents[].contentDetails[].detailType
string
详细类型
类型 含义
IMAGE 图片
TEXT 文本
offerCondition
items[].offerCondition
string
商品状态

商品创建后,无法修改offerCondition。

可根据显示品类代码选择以下数值。未选择时,则将其视为NEW。
参数名称 含义
NEW 新商品
REFURBISHED 翻新
USED_BEST 二手 (优秀)
USED_GOOD 二手 (良好)
USED_NORMAL 二手 (一般)
offerDescription
items[].offerDescription
string
曾用商品的详细说明

对曾用商品状态的说明,700个字符以内

仅在offerCondition输入为“曾用”时可用
requiredDocumentsobject[]
必须提交所需文件时输入

文件须为小于 5MB 的文档(PDF、HWP、DOC、

DOCX、TXT、PNG、JPG、JPEG)
templateName
requiredDocuments[].templateName
string
所需文件模版名

可通过“品类元数据查询API”确认
documentPath
requiredDocuments[].documentPath
string
所需文件酷澎CDN路径

须在documentPath和vendorDocumentPath中任选其一

最大长度:150个字符
vendorDocumentPath
requiredDocuments[].vendorDocumentPath
string
所需文件卖家路径

所需文件路径。若路径以 http://为开头,则会被自动下载并添加至酷澎CDN。须在documentPath和vendorDocumentPath中任选其一

最大长度:150个字符
extraInfoMessagestring
订制指南

将配送方式选为“订制”时,请输入要发给顾客的信息
manufacturestring
制造商

无法输入准确的制造商时,可输入与 [brand] 相同的内容
bundleInfoobject
捆绑商品
bundleType
bundleInfo.bundleType
string
捆绑商品类型

● SINGLE : 同种组合商品(默认值)

● AB : 混合组合商品

注册混合组合商品时,无法配置选项,添加捆绑商品信息后,无法修改捆绑商品值。这被视为与注册新产品相同,并相应应用。

请注意:
对于 AB 捆绑商品,不需要提供 UID(MPN 或 GTIN)。
请求示例application/json
{
  "code": "SUCCESS",
  "message": "[]",
  "data": 16009258995,
  "details": "다음과 같이 필수 구매 옵션을 입력해주세요. : '개당 용량' or '개당 중량'. 다음과 같이 필수 구매 옵션 (미입력시 등록/노출 제한)을 입력해주세요. : '개당 용량' and '개당 중량'. 자세한 사항은 아래 errorItems 에서 확인할 수 있습니다. 또한, 카테고리 메타 정보 조회 API(https://developers.coupangcorp.com/hc/en-us/articles/360034035713-Category-Metadata-Query) 혹은 공지사항에서 업데이트된 내용 확인할 수 있으며, 상품 생성 API (https://developers.coupangcorp.com/hc/en-us/articles/360033877853-Product-Creation)에서 업데이트된 에러 스펙 확인할 수 있습니다.",
  "errorItems": [
    {
      "itemIndex": 0,
      "itemName": "350ml 1개",
      "itemAttributes": [
        {
          "attributeTypeName": "개당 용량",
          "attributeValueName": null,
          "message": "번들 속성 그룹(groupNumber=1)의 '개당 용량', '개당 중량'에서 필수 속성을 하나만 선택합니다"
        },
        {
          "attributeTypeName": "개당 중량",
          "attributeValueName": null,
          "message": "번들 속성 그룹(groupNumber=1)의 '개당 용량', '개당 중량'에서 필수 속성을 하나만 선택합니다"
        },
        {
          "attributeTypeName": "개당 용량",
          "attributeValueName": null,
          "message": "필수 구매 옵션 (미입력시 등록/노출 제한) 존재하지 않습니다."
        },
        {
          "attributeTypeName": "개당 중량",
          "attributeValueName": null,
          "message": "필수 구매 옵션 (미입력시 등록/노출 제한) 존재하지 않습니다."
        }
      ]
    }
  ]
}
# 04

响应体

响应消息

NameTypeDescription
codestring
result code

SUCCES/ERROR
messagestring
message
datainteger
registered product ID

=sellerProductId

Response Example

{
  "code": "SUCCESS",
  "message": "[]",
  "data": 16009258995,
  "details": "다음과 같이 필수 구매 옵션을 입력해주세요. : '개당 용량' or '개당 중량'. 다음과 같이 필수 구매 옵션 (미입력시 등록/노출 제한)을 입력해주세요. : '개당 용량' and '개당 중량'. 자세한 사항은 아래 errorItems 에서 확인할 수 있습니다. 또한, 카테고리 메타 정보 조회 API(https://developers.coupangcorp.com/hc/en-us/articles/360034035713-Category-Metadata-Query) 혹은 공지사항에서 업데이트된 내용 확인할 수 있으며, 상품 생성 API (https://developers.coupangcorp.com/hc/en-us/articles/360033877853-Product-Creation)에서 업데이트된 에러 스펙 확인할 수 있습니다.",
  "errorItems": [
    {
      "itemIndex": 0,
      "itemName": "350ml 1개",
      "itemAttributes": [
        {
          "attributeTypeName": "개당 용량",
          "attributeValueName": null,
          "message": "번들 속성 그룹(groupNumber=1)의 '개당 용량', '개당 중량'에서 필수 속성을 하나만 선택합니다"
        },
        {
          "attributeTypeName": "개당 중량",
          "attributeValueName": null,
          "message": "번들 속성 그룹(groupNumber=1)의 '개당 용량', '개당 중량'에서 필수 속성을 하나만 선택합니다"
        },
        {
          "attributeTypeName": "개당 용량",
          "attributeValueName": null,
          "message": "필수 구매 옵션 (미입력시 등록/노출 제한) 존재하지 않습니다."
        },
        {
          "attributeTypeName": "개당 중량",
          "attributeValueName": null,
          "message": "필수 구매 옵션 (미입력시 등록/노출 제한) 존재하지 않습니다."
        }
      ]
    }
  ]
}
# 05

错误码

HTTP代码消息
400HTTP_400Bad Request

错误说明

HTTP类型错误消息解决方案
400400 (确认请求参数)

Error:"The value of attributeValueName is incorrect. Please enter the acceptable values as following the error spec guide.”

attributeValueName 的值不正确。 请按照错误规范指南输入可接受的值

请确认输入的尿布级别是否可用,只能输入以下值,每个库存ID最多可以新输入1个值。

1단계, 2단계, 3단계, 4단계, 5단계, 6단계, 7단계, 신생아(NB), 소형(S), 중형(M), 대형(L), 특대형(XL), 점보형(2XL), 점보형 이상(3XL)

400400 (确认请求参数)

品类的必需属性不存在。

这是属性(attributes)值中必需(MANDATORY)

输入的项目被遗漏时发生的错误,需要通过“品类元数据查询API”确认并输入所需的属性值。

400400 (确认请求参数)

必填购买选项(若未输入将导致注册/曝光受限)不存在。

请输入必填购买选项。请检查商品详情,确保已正确输入必要的选项值。

400400 (确认请求参数)

输入值错误。line: 123

确认请求的 JSON 文本相应line中输入的参数、值和数组格式是否正确。

400400 (确认请求参数)

请输入正确的退货中心代码。

通过“发货地&退货地查询API”确认您输入的发货地和退货地代码是否正确。

400400 (确认请求参数)

java.lang.NullPointerException

需要确认请求的 JSON 文本中是否存在拼写错误。.

400400 (确认请求参数)

输入的商品必需通知信息[例如:制造商和制造经销商]与品类[例如:化妆品]中提供的信息不同。

这是输入的通知信息有问题时出现的错误。请查询品类元数据信息,确认其是否与输入的通知信息(“notices”:[])完全一致。

400400 (确认请求参数)

配送费类型为满19800免费配送时,

如果设置了 freeShipOverAmount:19800,

400400 (确认请求参数)

指定条件包邮价格为19800韩元,初始运费为0韩元。

则需要确认初始运费 (deliveryChargeOnReturn) 值是否输入为“0”。

400400 (确认请求参数)

请确认[物流公司代码]。

如果设置了偏远地区配送(remoteAreaDeliverable:“Y”),则只能输入在发货地注册的物流公司。

400400 (确认请求参数)

UNAUTHORIZATION

这是因认证信息不正确而出现的错误。请确认认证是否正确。

400400 (check request parameter)

请检查送货方式。

如果您选择海外代购(AGENT_BUY),请检查收货地址是否为海外收货地址。 无法选择国内(韩国)收货地址。

400400 (check request parameter)

如果发货方式是代购(AGENT_BUY),Coupang强制要求客户进入PCCC发货。

如果选择海外代购(AGENT_BUY),请检查pccNeeded参数值是否设置为true。

400400 (check request parameter)

autoPricingInfo.minSalePrice must be less than salePrice

请将 minSalePrice 设为低于 salePrice

400400 (check request parameter)

autoPricingInfo cannot be modified after product approval

审批通过后请改用 [按 item 改价] API