更新賣場資訊調整提案單

賣場資訊調整提案 #

更新賣場資訊調整提案單 #

更新 賣場資訊調整提案單。透過指定 subProposals，可指定是否同時修改賣場圖片、影片、詳情和規格表。

Endpoint URL: https://tw.supplier.yahoo.com/api/spa/v1/proposal/updateListings/{id}
HTTP Method: PUT

Request Body #

applicant #

提案人。
資料型態: String
必填: 是
長度限制: 最長 10 個字
格式: 繁/簡體中文

note #

備註。
資料型態: String
必填: 是
長度限制: 最長 200 個字

reviewStatus #

審核結果。
資料型態: String
必填: 是
欄位內容:

  • draft 儲存暫不提案
  • pendingReview 待審核

subProposals #

子提案申請類型。
資料型態: SubProposal[]
必填: 是
欄位內容:

  • id 新增賣場資訊調整提案單時所建立的子提案單號
  • type 子提案單號對應的提案類型，僅允許填入以下提案類型:
    • updateImageV2: 修改賣場/商品圖片
    • updateVideo: 修改賣場影片
    • updateCopy: 修改賣場/商品詳情
    • updateListingAttribute: 修改賣場規格表

listing #

賣場資訊。
資料型態: ProposalListing

欄位說明

  • id
    賣場編號。
    資料型態: Integer
    必填: 是

  • name
    賣場名稱。
    資料型態: String
    必填: 是
    長度限制: 最長 100 個字

  • productName
    賣場主件商品名稱。
    資料型態: String
    必填: 否
    長度限制: 最長 100 個字，若賣場配送方式為快速到貨，則最長 50 個字
    欄位說明: 賣場為無屬性賣場時才能更改

  • brandId
    品牌 ID。
    資料型態: String
    必填: 是
    欄位說明: 品牌 ID 可透過 品牌名稱關鍵字搜尋

    • brands[] 中會有多筆符合搜尋條件的品牌資料，選擇欲使用的品牌名稱 ex. Yahoo!，在提案內容 listing.brandId 填寫相對應的 id value 即可。

  • model
    商品型號。
    資料型態: String
    必填: 否
    長度限制: 最長 40 個字
    格式: 不允許大小於符號和換行

  • partNo
    賣場主件商品供應商商品料號。
    資料型態: String
    必填: 否
    長度限制: 最長 50 個字
    格式: 不允許換行和 tab

  • featureTitle
    特色標題。
    資料型態: String
    必填: 否
    長度限制: 最長 20 個字
    格式: 只接受繁/簡體中文、英文、數字、日文、注音符號、空格、 , 、ˊ 、 ˇ 和 ˋ

  • shortDescription
    賣場商品特色。
    資料型態: String[]
    必填: 是
    長度限制: 每條最長 15 個字
    格式: 不允許大小於符號和換行
    欄位說明: 至少需填 1 條，最多 5 條

  • copy
    商品詳情 (文案)，HTML content。
    資料型態: String
    必填: 否
    欄位內容: 請參考 賣場/商品詳情(文案)限制
    欄位說明:

    • SubProposal 需包含 updateCopy 才能更改
    • 當 SubProposal 包含 updateCopy 時，此欄位為必填

  • warranty
    商品保證。
    資料型態: ProductWarranty
    必填: 否
    欄位說明: SubProposal 需包含 updateCopy 才能更改

  • attributeDisplayMode
    商品規格顯示方式。
    資料型態: String
    必填: 否
    預設值: table
    欄位內容:

    • table
    • list

    欄位說明:

    • SubProposal 需包含 updateListingAttribute 才能更改
    • 當 SubProposal 包含 updateListingAttribute 時，此欄位為必填

  • struDataAttrClusterId
    結構化資料屬性集 ID (Structured data attribute cluster ID)。
    資料型態: String
    必填: 否
    欄位說明:

    • SubProposal 需包含 updateListingAttribute 才能更改
    • 當 SubProposal 包含 updateListingAttribute 時，此欄位為必填

  • attributes
    商品規格表。
    資料型態: Attribute[]
    必填: 否
    欄位說明:

    • SubProposal 需包含 updateListingAttribute 才能更改
    • 當 SubProposal 包含 updateListingAttribute 時，此欄位為必填
    • 和賣場屬性相同的 Attribute，不可再填入此欄位。例如賣場屬性名稱為 顏色，則此欄位不可再指定 顏色 這個規格。 其餘 structured data attribute cluster 定義的 必填欄位 (即 required 設為 ture) 則必須提供， 指的即是 GET v1/struDataAttrClusters 取回的內容 (即 StruDataAttrCluster 中的 attributes)。

  • images
    商品圖。
    資料型態: ProductImage[]
    必填: 否
    欄位說明: 商品圖可透過 檔案上傳 取得上傳的圖片連結。規則如下:

    • 賣場為無屬性賣場時才能更改
    • SubProposal 需包含 updateImageV2 才能更改
    • 最多 10 張，需要為正方形，尺寸大於 1000^2 pixels 會被縮至 1000^2, 400^2, 250^2, 135^2 及 80^2 pixels、大於 400^2 pixels 會被縮至 400^2, 250^2, 135^2 及 80^2 pixels
    • 至少需要兩張主圖 (1000^2 pixels)，可增加 8 張副圖 (1000^2 or 400^2 pixels)

  • syncProductImages
    是否同時修改無屬性賣場之商品圖片。
    資料型態: Boolean
    必填: 否
    預設值: true
    欄位說明:

    • 賣場為無屬性賣場時才能更改
    • SubProposal 需包含 updateImageV2 才能更改

  • shareMediaBetweenModels
    是否共用同一組商品圖/影片。
    資料型態: Boolean
    必填: 否
    預設值: false
    欄位說明:

    • 賣場為單層屬性賣場時才能更改
    • SubProposal 需包含 updateImageV2 或 updateVideo 才能更改
    • 若為 true ，則 models 只有第一個 model 可以有圖/影片 (models[0].images / models[0].videos)

  • videos
    商品影片。
    資料型態: ProductVideo[]
    必填: 否
    欄位說明: 商品影片 / 商品圖可透過 檔案上傳 取得上傳的圖片連結

    • 賣場為無屬性賣場時才能更改
    • SubProposal 需包含 updateVideo 才能更改

  • models
    賣場屬性商品資訊。
    資料型態: ProposalModel[]
    必填: 否
    欄位說明: 每一個屬性商品即為一筆 ProposalModel，models 說明如下:

    • 賣場為有屬性賣場時才能更改

    • sku
      第 1 層屬性的商品編號。
      資料型態: Integer
      必填: 是

    • spec
      第 1 層屬性。
      資料型態: Attribute
      必填: 否
      欄位說明: 若未填寫，將自動帶入該 SKU 的屬性值

      • name
        第 1 層屬性名稱 (e.g. 顏色)。
        資料型態: String
        必填: 否
        欄位說明: 不需填寫，提案將自動帶入該 SKU 的屬性名稱，倘若填寫也無法更新屬性名稱
      • selectedValue
        第 1 層屬性值 (e.g. 白色系)。
        資料型態: String
        必填: 是
        長度限制: 最長 100 個字
        欄位說明: 第 1 層屬性的各個屬性值不可相同

    • partNo
      第 1 層屬性商品供應商商品料號。
      資料型態: String
      必填: 否
      長度限制: 最長 50 個字
      格式: 不允許換行和 tab
      欄位說明: 賣場為單層屬性賣場時才能更改

    • name
      第 1 層屬性商品名稱。
      資料型態: String
      必填: 否
      長度限制: 最長 100 個字，若賣場配送方式為快速到貨，則最長 50 個字
      欄位說明:

      • 賣場為單層屬性賣場時才能更改
      • 賣場為單層屬性賣場時必填

    • videos
      商品影片。
      資料型態: ProductVideo[]
      必填: 否 欄位說明: 商品影片 / 商品圖可透過 檔案上傳 取得上傳的圖片連結

      • SubProposal 需包含 updateVideo 才能更改

    • images
      商品圖。
      資料型態: ProductImage[]
      必填: 是
      欄位說明: 商品影片 / 商品圖可透過 檔案上傳 取得上傳的圖片連結。規則如下:

      • SubProposal 需包含 updateImageV2 才能更改
      • 最多 10 張，需要為正方形，尺寸大於 1000^2 pixels 會被縮至 1000^2, 400^2, 250^2, 135^2 及 80^2 pixels、大於 400^2 pixels 會被縮至 400^2, 250^2, 135^2 及 80^2 pixels
      • 至少需要兩張主圖 (1000^2 pixels)，可增加 8 張副圖 (1000^2 or 400^2 pixels)

    • items
      第 2 層屬性商品資訊。
      資料型態: ProposalItem[]
      必填: 否
      欄位說明: 賣場為雙層屬性賣場時才能更改

      • sku
        第 2 層屬性的商品編號。
        資料型態: Integer
        必填: 是

      • spec
        第 2 層屬性。
        資料型態: Attribute
        必填: 否
        欄位說明: 若未填寫，將自動帶入該 SKU 的屬性值

        • name
          第 2 層屬性名稱 (e.g. 尺寸)。
          資料型態: String
          必填: 否
          欄位說明: 不需填寫，提案將自動帶入該 SKU 的屬性名稱，倘若填寫也無法更新屬性名稱
        • selectedValue
          第 2 層屬性的屬性值 (e.g. M號)。
          資料型態: String
          必填: 是
          長度限制: 最長 100 個字
          欄位說明: 同一個第 1 層屬性值中，第 2 層屬性的各個屬性值不可相同

      • partNo
        第 2 層屬性商品供應商商品料號。
        資料型態: String
        必填: 否
        長度限制: 最長 50 個字
        格式: 不允許換行和 tab
        欄位說明: 賣場為雙層屬性賣場時才能更改

      • name
        第 2 層屬性商品名稱。
        資料型態: String
        必填: 否
        長度限制: 最長 100 個字，若賣場配送方式為快速到貨，則最長 50 個字
        欄位說明:

        • 賣場為雙層屬性賣場時才能更改
        • 賣場為雙層屬性賣場時必填

Request/Response Syntax #

PUT /api/spa/v1/proposal/updateListingModels/{id}

{
  "applicant": string,
  "listing": {
    "attributeDisplayMode": string,
    "attributes": [
      {
        "name": string,
        "values": [
          string
        ]
      }
    ],
    "brandId": string,
    "copy": string,
    "featureTitle": string,
    "id": number,
    "images": [
      {
        "height": number,
        "order": number,
        "url": string,
        "width": number
      }
    ],
    "model": string,
    "models": [
      {
        "sku": number,
        "spec": {
          "selectedValue": string
        },
        "items": [
          {
            "sku": number,
            "spec": {
              "selectedValue": string
            },
            "name": string,
            "partNo": string
          }
        ],
        "images": [
          {
            "height": number,
            "order": number,
            "url": string,
            "width": number
          }
        ],
        "videos": [
          {
            "url": string,
            "order": number
          }
        ]
      }
    ],
    "name": string,
    "partNo": string,
    "productName": string,
    "shareMediaBetweenModels": boolean,
    "shortDescription": [
      string
    ],
    "struDataAttrClusterId": string,
    "syncProductImages": boolean,
    "videos": [
      {
        "url": string,
        "order": number
      }
    ],
    "warranty": {
      "description": string,
      "handler": string,
      "period": string,
      "scope": string,
      "productStatus": string
    }
  },
  "note": string,
  "reviewStatus": string,
  "subProposals": [
    {
      "type": string
    }
  ]
}

{
  "applicant": string,
  "contactWindow": string,
  "createdTs": string,
  "creator": string,
  "executeStatus": string,
  "expiredTs": string,
  "id": number,
  "listing": {
    "attributeDisplayMode": string,
    "attributes": [
      {
        "name": string,
        "values": [
          string
        ]
      }
    ],
    "brandId": string,
    "brandName": string,
    "copy": string,
    "featureTitle": string,
    "id": number,
    "images": [
      {
        "height": number,
        "order": number,
        "url": string,
        "width": number
      }
    ],
    "model": string,
    "models": [
      {
        "sku": number,
        "spec": {
          "name": string,
          "selectedValue": string
        },
        "items": [
          {
            "sku": number,
            "spec": {
              "name": string,
              "selectedValue": string
            },
            "name": string,
            "partNo": string
          }
        ],
        "images": [
          {
            "height": number,
            "order": number,
            "url": string,
            "width": number
          }
        ],
        "videos": [
          {
            "url": string,
            "order": number
          }
        ]
      }
    ],
    "name": string,
    "partNo": string,
    "productName": string,
    "shareMediaBetweenModels": boolean,
    "shortDescription": [
      string
    ],
    "struDataAttrClusterId": string,
    "syncProductImages": boolean,
    "videos": [
      {
        "url": string,
        "order": number
      }
    ],
    "warranty": {
      "description": string,
      "handler": string,
      "period": string,
      "scope": string,
      "productStatus": string
    }
  },
  "modifiedTimes": number,
  "modifiedTs": string,
  "modifier": string,
  "note": string,
  "reviewStatus": string,
  "subProposals": [
    {
      "id": number,
      "type": string,
      "errors": [
        "invalidValue": string,
        "message": string,
        "code": number
      ]
    }
  ],
  "subStationId": string,  
  "subStationName": string,
  "supplierId": number
}

Response Elements #

若操作成功，API 會回傳 HTTP 200 response。並以 JSON 格式回傳完整的 UpdateListingProposal 物件。

id #

提案編號。
資料型態: Integer

supplierId #

供應商編號。
資料型態: Integer

subProposals #

子提案申請類型。
資料型態: SubProposal[]
欄位內容:

  • id 新增賣場資訊調整提案單時所建立的子提案單號
  • type 子提案單號對應的提案類型
  • errors 若建立/更新子提案單時發生錯誤，則此欄位會顯示詳細錯誤資訊

listing #

賣場資訊。
資料型態: ProposalListing

subStationId #

提案當下的提案子站編號, e.g. sub1。
資料型態: String

subStationName #

提案當下的提案子站名稱。
資料型態: String

applicant #

提案人。
資料型態: String

appliedTs #

提案時間。
資料型態: String
格式: ISO-8601

expiredTs #

提案有效時間。
資料型態: String
格式: ISO-8601

contactWindow #

提案對象。
資料型態: String

createdTs #

建檔時間。
資料型態: String
格式: ISO-8601

creator #

建檔者。
資料型態: String

modifiedTimes #

更新次數。
資料型態: Integer

modifiedTs #

更新時間。
資料型態: String
格式: ISO-8601

modifier #

更新者。
資料型態: String

executeStatus #

執行狀態。
資料型態: String
有效值: 詳見 執行狀態

reviewStatus #

審核狀態。
資料型態: String
有效值: 詳見 審核狀態

note #

備註。
資料型態: String

suggestion #

改善或建議。
資料型態: String

Errors #

Bad Request #

輸入的參數不符合 API 定義的 Pattern。
HTTP Status Code: 400

Error Code Description
40000010 Multiple bad parameters

Unauthorized #

身分認證不通過，請檢查您的 Cookie 或 wssid。
HTTP Status Code: 401

Error Code Description
40100001 Missing or bad authentication
40100002 Invalid cookie
40100003 Missing or bad authentication
40100004 Check wssid failed
40100006 Cookie has expired

Forbidden #

權限驗證不通過，請確認您有權操作更新賣場屬性調整提案，且為您所提案的賣場的擁有者。
HTTP Status Code: 403

Error Code Description
40304001 No permission

Unprocessable Entity #

提案單狀態驗證不通過，請確認提案單狀態。
HTTP Status Code: 422

Error Code Description
42209002 Invalid state flow of proposal review status
42209003 Invalid listing layer

Internal Server Error #

API 端發生錯誤，若持續發生請洽您的業務窗口。
HTTP Status Code: 500

Examples #

更新提案單號為 244077 的提案單

以單層屬性賣場為例

PUT /api/spa/v1/proposal/updateListings/244077 HTTP/1.1
HOST: tw.supplier.yahoo.com
Content-Type: application/json; charset=UTF-8

{
  "applicant": "applicant-name",
  "note": "proposal-note",
  "reviewStatus": "pendingReview",
  "subProposals": [
    {
      "id": 244078,
      "type": "updateImageV2"
    },
    {
      "id": 244079,
      "type": "updateVideo"
    },
    {
      "id": 244080,
      "type": "updateCopy"
    }
  ],
  "listing": {
    "id": 3378720,
    "name": "賣場名稱",
    "brandId": "41166484",
    "model": "商品型號",
    "partNo": "主件商品料號",
    "featureTitle": "新的特色標題",
    "shortDescription": [
      "新的商品特色",
      "新的商品特色2"
    ],
    "syncProductImages": true,
    "shareMediaBetweenModels": true,
    "models": [
      {
        "sku": 6490415,
        "spec": {
          "selectedValue": "白色系"
        },
        "name": "新的屬性商品名稱",
        "partNo": "新的屬性商品料號",
        "videos": [
          {
            "url": "https://s.yimg.com/bp/Files/8a1258ca99cef3d4955353d3503549b41e496fa9.qt",
            "order": 1
          }
        ]
      }
    ],
    "copy": "<p>foo</p>",
    "warranty": {
      "description": "保固說明文字",
      "handler": "official",
      "period": "一個月",
      "scope": "新品瑕疵",
      "productStatus": "new"
    }
  }
}

{
  "applicant": "applicant-name",
  "contactWindow": "contact-windows-id",
  "createdTs": "2019-12-23T10:27:41Z",
  "creator": "creator-id",
  "executeStatus": "idle",
  "expiredTs": "2020-01-06T16:00:00Z",
  "id": 244077,
  "listing": {
    "brandId": "41166484",
    "brandName": "2M2",
    "copy": "<p>foo</p>",
    "featureTitle": "新的特色標題",
    "id": 3378720,
    "model": "商品型號",
    "models": [
      {
        "sku": 6490415,
        "spec": {
          "name": "顏色",
          "selectedValue": "白色系"
        },
        "name": "新的屬性商品名稱",
        "partNo": "新的屬性商品料號",
        "videos": [
          {
            "url": "https://s.yimg.com/bp/Files/8a1258ca99cef3d4955353d3503549b41e496fa9.qt",
            "order": 1
          }
        ]
      }
    ],
    "name": "賣場名稱",
    "partNo": "主件商品料號",
    "shareMediaBetweenModels": true,
    "shortDescription": [
      "新的商品特色",
      "新的商品特色2"
    ],
    "syncProductImages": true,
    "warranty": {
      "description": "保固說明文字",
      "handler": "official",
      "period": "一個月",
      "scope": "新品瑕疵",
      "productStatus": "new"
    }
  },
  "modifiedTimes": 2,
  "modifiedTs": "2019-12-24T10:27:41Z",
  "modifier": "modifier-id",
  "note": "proposal-note",
  "reviewStatus": "pendingReview",
  "subProposals": [
    {
      "id": 244078,
      "type": "updateImageV2"
    },
    {
      "id": 244079,
      "type": "updateVideo"
    },
    {
      "id": 244080,
      "type": "updateCopy"
    }
  ],
  "subStationId": "sub-station-id",
  "subStationName": "sub-station-name",
  "supplierId": 99999
}