Marketplace 合作關係

Marketplace 合作夥伴商品 API

成為 Marketplace 合作夥伴後，您可以在特定國家／地區的 Facebook Marketplace 上架您的商品。

若要上傳、更新或刪除 Facebook Marketplace 上的商品，您需使用圖形 API 介面。

HTTP
POST /v20.0/{product-catalog-id}/items_batch HTTP/1.1

如果想瞭解如何使用圖形 API，請參閱《使用圖形 API》指南。

發佈到此關係連線時，系統會建立一個商品項目。

參數

參數	說明
item_type	設定為 PRODUCT_ITEM
requests	商品陣列中每個商品的方法和欄位。

要求參數可用來定義要求的方法和資料。

欄位	說明
method	您希望指定商品執行的動作。選項包括： CREATE UPDATE DELETE
data	要建立、更新或刪除的商品資訊。

要求參數範例

[
    {
        "method": "CREATE",
        "data": {
            "id": "UniqueProductID",
            "title": "Title",
            "description": "This is the description",
            "price": "100 USD",
            "image_link": "https:\/\/www.facebook.com",
            "brand": "Monster",
            "availability": "in stock",
            "condition": "new",
            "link": "https:\/\/www.facebook.com",
            "return_details": {"return_days": "30", "return_type": "SELLER_PAID_RETURN"},
            "partner_product_checkout_uri": "https:\/\/www.facebook.com",
            "partner_product_location": "San Fransisco, CA",
            "partner_product_expiration_time": "1923181264",
            "partner_delivery_method": ["shipping"],
            "partner_shipping_type": "fixed",
            "partner_shipping_cost": "14.95",
            "partner_shipping_speed": "3:5",
            "partner_attribute_data": {"color": "blue"},
            "partner_seller_id": "MySellerId1",
            "partner_item_country": "US"
        }
    },
    .... {next product}
]

API 限速

若要避免限速，請遵從以下建議：

每分鐘不呼叫超過 30 次，一旦超過便會導致節流。
單次 API 呼叫的批量商品以 300 個為限。

商品項目欄位

參數	類型	必要／選用	說明
`id`	字串（字元數上限：100）	必要	商品的不重複內容編號。如果可能的話，請使用商品的 SKU。每組內容編號只能在您的目錄中出現一次。如果相同編號出現多次，我們會全部忽略。如果商品在多個國家／地區上架，您必須在所有目錄中重複使用同一組編號。請務必將價格更新為該國家／地區的幣別（請見價格欄位）。
`title`	字串（字元上限：200）	必要	顯示在 Marketplace 商品資訊的商品項目標題。此文字會顯示於 Marketplace。請勿加入 HTML 標籤。
`description`	字串（字元上限：9999）	必要	商品說明。雖然本欄位的字元上限為 9999，但 Facebook Marketplace 商品資訊中只會顯示前 256 個字元。此文字會顯示於 Marketplace。請勿加入 HTML 標籤。範例：使用有機棉的舒適皇家藍女版 T 恤。蓋肩袖和寬版設計，非常適合溫暖夏日。
`condition`	列舉 {new, refurbished, used, used_like_new, used_good, used_fair, cpo, open_box_new}	必要	商品項目的狀況。
`partner_listing_type`	列舉 {fixed_price, auction, vehicle, rental, real_estate}	選用	這會決定商品資訊類型。若未選擇，則會預設為「fixed_price」。若設為「auction」、「vehicle」、「rental」或「real_estate」，系統會為 Marketplace 買家提供指定合作夥伴的商品資訊類型體驗。
`partner_product_condition`	列舉 {acceptable, brand_new, certified_pre_owned, certified_refurbished, damaged, digital_good, excellent_refurbished, for_parts_or_not_working, good, good_refurbished, graded, like_new, new, new_other, new_other_see_details, new_with_box, new_with_defects, new_with_tags, open_box, others, pre_owned, remanufactured, retread, seller_refurbished, ungraded, used, very_good, very_good_refurbished, new_open_box, open_box_used, new_factory_sealed, unknown}	選用	商品狀況。覆寫狀況欄位的選填欄位。如果需說明更具體的商品狀況，請使用此欄位。
`brand`	字串	必要	商品的品牌。如果沒有品牌，請設為「N/A」。
`price`	字串（字元上限：9999）	必要	價格的格式為數字後空一格，加上 3 個字母的 ISO 4217 幣別代碼。例如：10.99 EUR 如果商品類型為「auction」，這是商品的出價價格。價格的格式為數字後空一格，加上 3 個字母的 ISO 4217 幣別代碼。
`availability`	列舉 {in stock, out of stock}	必要	商品項目的供應狀況。
`link`	字串	必要	行動裝置可用的商品詳情頁面連結網址。
`partner_product_checkout_uri`	字串	選用	當用戶於商品資訊上點按「購買」時，我們會將用戶傳送至結帳網址連結。我們會將 click_id 附加到參數中。如果缺少連結，我們會預設使用「link」欄位的網址。
`partner_product_html_desc_uri`	字串	選用	包含商品完整說明的網站網址連結。如果商品說明的內容超出文字欄位「description」所能容納的字數，便使用此欄位。Marketplace 將會選擇性提供完整說明的連結。
`image_link`	字串	必要	商品主要圖像的網址。圖像必須為 JPEG 或 PNG 格式，至少 500 x 500 像素，大小不得超過 8 MB。查看商品圖像規格。
`partner_seller_id`	字串（字元上限：100）	必要	賣家的唯一識別碼。需要與賣家資訊中的 partner_seller_id 相符。範例：「partner_seller_id」：「great_seller_inc」
`partner_item_country`	列舉 {AT, BE, BG, CY, CZ, DE, DK, EE, ES, FI, FR, GR, HR, HU, IE, IS, IT, LI, LT, LU, LV, MT, NL, NO, PL, PT, RO, SE, SI, SK}	必要	這是銷售商品或提供配送服務（如適用）的國家／地區。目錄的國家／地區必須與 partner_item_country 相符。若商品可以跨境配送，您必須為支援配送服務且合作夥伴願意送貨的每個國家／地區目錄建立商品。
`fb_product_category`	字串	選用	商品的 Facebook 商品類別。以下清單提供最明確的 Facebook 商品類別：試算表（.csv）或純文字（.txt）。
`status`	列舉 {active, archived}	選用	商品目前的狀態。
`sale_price`	字串	選用	價格的格式為數字後空一格，加上 3 個字母的 ISO 4217 幣別代碼。例如：10.99 EUR。此欄位與價格欄位的格式相同。與價格欄位搭配使用以顯示折扣。
`sale_price_effective_date`	字串	選用	促銷活動開始及結束的日期和時間（以斜線分隔）。請以 YYYY-MM-DD 的格式輸入開始和結束日期。在每個日期後面加一個「T」，然後再加上時間。以 24 小時格式（0:00 至 23:59）輸入時間。範例：2014-11-01T12:00-0300/2014-12-01T00:00-0300。
`additional_image_link`	字串（字元上限：2000）	選用	最多可為商品提供 20 個圖像網址，請使用逗號（,）分號（;）、空格（）或豎線（\|）區隔。請遵循與 image_link 相同的圖像規格。
`return_details`	可為空的 JSON 物件（例如：map）{ "return_days": 30, "return_type": enum } 列舉：FINAL_SALE NO_RETURNS_WITH_EXCEPTION NO_RETURNS SELLER_PAID_RETURN BUYER_PAID_RETURN 或者，如果不提供退貨「return_details」：null	選用	return_days 表示買家必須在多少天內開始產品退貨。針對 NO_RETURNS 和 FINAL_SALE，return_days 應設定為 -1 return_type 表示產品支援的退貨方式。可用選項包含：FINAL_SALE、NO_RETURNS_WITH_EXCEPTION、NO_RETURNS、SELLER_PAID_RETURN、BUYER_PAID_RETURN 如果留空，則不會顯示退貨詳情。
`partner_attribute_data`	可為空的 JSON 物件 { “color”: “blue” } 可用鍵：aspect_ratio, band_material、bike_type、brand、break_type、cable_length、capacity、case_size、certification、character、circulated_uncirculated、closure、color、compatible_bike_type、compatible_brand、compatible_model、compatible_operating_system、compatible_product、connectivity、credit_included、denomination、department、display_technology、dress_length、exterior_color、exterior_material、fabric_type、features、film_format、fit、focal_length、focus_type、form_factor、format、frame_color、game_name、game、gauge、golf_club_type、handedness、inseam、internet_connectivity、item_height、item_length、item_weight、item_width、items_included、main_stone、manufacturer_part_number、manufacturer、material、maximum_aperture、maximum_magnification、maximum_resolution、memory_cards_supported、metal_purity、metal、model、mount、mpn、network、number_of_items、occasion、outer_shell_material、package_quantity、part_type、pattern、performance_activity、platform、processor、publication_name、quantity、rack_type、rim_diameter、rim_width、ring_size、screen_size、section_width、series、set_includes、set、size_type、size、skirt_length、sleeve_length、sport_activity、sport、storage_capacity、style、type、unit_quantity、unit_type、upper_material、us_shoe_size、vintage、voltage、volume、waist_size、wheel_diameter、year	選用	將顯示於產品詳細資訊區塊的屬性的鍵／值清單。值為字串格式。適用於租屋／房地產的鍵：property_type（必要）、sale_type、bed_bath、area_size、pet_friendly、ac_type、heating_type、laundry_type、parking_type、parkingSpace、furnishing_type、garden_type、tenure_type、listed_by、property_tax_and_condo_fee、construction_status、lease_duration、energy_rating_eu、co2_emission_rating 適用於車輛的鍵：vehicle_type、year、make、model、number_of_owners、trim、body_style、exterior_color、interior_color、transmission、fuel_type、mileage、money_still_owed、motorcycle_type、engine_size
`partner_product_creation_time`	以秒為單位的 UNIX 時間戳記（世界協調時間）（數字）	選用	商品建立或更新時的 UNIX 時間戳記。範例：「partner_product_creation_time」：1713917255
`partner_product_location`	字串	選用	要顯示商品的位置（以字串表示）。範例：「法國巴黎」。此欄位沒有範圍限制。
`partner_product_expiration_time`	以秒為單位的 UNIX 時間戳記（世界協調時間）（數字）	選用	商品將從 Marketplace 移除的時間。此欄位必須填入未來的時間。
`partner_delivery_method`	字串列舉陣列 {shipping, in_person}	選用	此欄位說明商品如何交付給買家。如果商品可以運送，也可以親自取貨，請同時註明。範例：[“shipping”,”in_person”] 預設值：[“shipping”]
`partner_item_latitude`	浮點	選用	商品的緯度。若送貨方式包含「in_person」，此為必填欄位。
`partner_item_longitude`	浮點	選用	商品的經度。若送貨方式包含「in_person」，此為必填欄位。
`partner_shipping_type`	列舉 {free, fixed, dynamic}	選用	商品的配送價格策略。若為免運費，請使用「free」。如果無論地點為何，運費都是固定價格，請使用「fixed」，並在 partner_shipping_cost 中設定費用。如果運費根據買家地點、款式選擇等項目而有所不同，請選擇「dynamic」。如果選擇「dynamic」，系統便不會顯示運費，而是告知買家可以在結帳時看到運費。預設值：「dynamic」
`partner_shipping_cost`	浮點	選用	如果 partner_shipping_type 為「fixed」，此為必填欄位。範例：「14.95」
`partner_shipping_speed`	字串 ‘MIN_DELIVERY_SPEED_IN_DAYS:MAX_DELIVERY_SPEED_IN_DAYS’	選用	預計運送商品的最短和最長工作天數。範例：「3:5」
`partner_auction_bid_close_time`	以秒為單位的 UNIX 時間戳記（世界協調時間）（數字）	選用	如果 partner_listing_type 為「auction」，則為必填欄位。此為該商品的出價結束時間。範例：「partner_auction_bid_close_time」：1713917255
`partner_auction_bid_count`	數字	選用	partner_listing_type 為「auction」時才適用。此為目前對商品的出價次數。
`additional_fields`	可為空的 JSON 物件任意形式（沒有設定列舉／鍵） { “revised_title”: “Premium Blue T-Shirt” }	選用	適合合作夥伴傳送任何其他欄位的任意形式 JSON 欄位。

查看上傳狀態

提交建立、更新或刪除要求後，系統會傳回控制代碼。然後，您可以透過另一個要求來檢查提交的結果。

資料的狀態將在完成時設定為「finished」，並且會顯示錯誤和警告。

HTTP
GET /v20.0/{product-catalog-id}/check_batch_request_status?handle={your handle}

傳回範例

{
  "data": [
    {
      "handle": "Acy3FUJwzE10XnWrYr4ttrjOAfs-h6BUg-Wtg6sWGeV7qZZaErX15XPfqT_KWeyC6T4-nTbng9r1BJuScb6hgO1B",
      "status": "finished",
      "errors_total_count": 0,
      "errors": [
      ],
      "warnings": [
        {
          "line": 1,
          "id": "YourItemID",
          "message": "These attributes are invalid and need to be updated in the feed file: The product_tags information under  is invalid. Review for more details"
        }
      ],
      "ids_of_invalid_requests": [
      ]
    }
  ],
  "__www_request_id__": "Az3ghYsDh-101IH2t6DXKuP"
}

檢視和管理商品

請前往商務管理工具檢視或管理上傳的商品。商務管理工具將會顯示所有商品問題，並可使用該工具解決問題。