（合約）合作夥伴廣告：API 參考資料

其他（合約）合作夥伴廣告 API 包括：

• 賣家管理 API
• 合作夥伴廣告管理 API
• 非同步 API 使用指南

查詢賣家業務 API

使用此 API 可查詢特定賣家的業務編號或 vendor_id。

存取權杖類型

若要呼叫此 API，請使用上層企業管理平台（Marketplace 的企業管理平台）所屬之管理員系統用戶建立的存取權杖。

GET 要求範例

curl -X GET \
  -F "child_business_external_id=<VENDOR_ID>" \
  "https://graph.facebook.com/v<API_VERSION>/<Business_id>/owned_businesses?access_token=<ACCESS_TOKEN>"

回應範例

{
    "child_business_id": 3213232
}

存取賣家業務中繼資料 API

使用此 API 可擷取（合約）合作夥伴廣告賣家子業務的賣家中繼資料。API 回應的中繼資料包括：

• （合約）合作夥伴廣告資產：粉絲專頁、廣告帳號、付款方式
• 賣家的自訂範本資訊
• 賣家業務資訊：名稱

存取權杖類型

若要呼叫此 API，請使用上層企業管理平台（Marketplace 的企業管理平台）所屬之管理員系統用戶建立的存取權杖。

業務編號類型

使用子企業管理平台編號進行 API 呼叫。

GET 要求範例

curl -X GET \
  "https://graph.facebook.com/v<API_VERSION>/<Business_id>/?fields=collaborative_ads_managed_partner_business_info&access_token=<ACCESS_TOKEN>"

回應範例

{
  "collaborative_ads_managed_partner_business_info": {
    "seller_business_status": "ready",
    "seller_business_info": {
      "seller_external_website_url": "https://www.website.com",
      "partner_facebook_page": {
        "id":"9999999"
      }
    },
    "ad_account": {
      "id": "act_11111111",
      "currency": "USD"
    },
    "page": {
      "id": "3333333"
    },
    "catalog_segment": {
      "id": "2222222"
    },
    "extended_credit": {
      "receiving_credit_allocation_config": {
        "partition_type": "FIXED",
        "id":"66666666"
      },
      "max_balance": {
        "amount":"5,000.00",
        "amount_in_hundredths":"500000",
        "currency":"USD",
        "offsetted_amount":"500000"
      },
      "id":"888888888"
    },
    "active_seller_campaign": {
      "status": "ACTIVE",
      "id": "1111111"
    },
    "template": [
      {
        "budget_percentage": 0.5,
        "campaign_template_id": "4444444",
        "adgroup_template_ids": [
          "5555555"
        ],
        "targeting_type": "retargeting"      
      },
      {
        "budget_percentage": 0.5,
        "campaign_template_id": "6666666",
        "adgroup_template_ids": [
          "7777777"
        ],
        "targeting_type": "prospecting"
      } 
    ]
  },
  "id": "<child_business_manager_id>"
}
    

取得子系統用戶權杖

若是已啟用的子企業管理平台，使用此 API 呼叫可分享應用程式並取得其存取權杖。此權杖可用於所有後續呼叫，以建立或管理廣告。

POST 要求範例

curl \
  -F 'id=<CHILD_BUSINESS_MANAGER>' \
  -F 'app_id=<App_ID>' \
  -F 'scope=ads_management,business_management' \
  -F 'access_token=<Parent BM Admin System User Access Token>' \
  -F 'appsecret_proof=<APP_SECRET>' \
  "https://graph.facebook.com/<API_VERSION>/<CHILD_BUSINESS_MANAGER_ID>/access_token"

回應範例

{ 
  "access_token": "<CHILD_BM_ACCESS_TOKEN>"
}

更新賣家業務配置 API

使用此 API 可更新賣家業務資訊。您可以更新賣家的業務資訊（例如外部網站網址或電子郵件地址）和／或其（合約）合作夥伴廣告資產（例如有效的廣告帳號或廣告建立自訂行銷活動範本）。詳情請參閱可用參數。

若要建立和取得賣家的業務，請參閱賣家業務建立 API。若要尋找現有賣家的業務編號，請參閱查詢賣家業務 API。

存取權杖類型

若要呼叫此 API，請使用個別子企業管理平台（賣家的企業管理平台）所屬的存取權杖。

可用參數

POST 要求範例

curl \
  -F "seller_external_website_url='http://shop.com'" \
  -F "ad_account=<SELLER_ACTIVE_AD_ACCOUNT_ID>" \
  "https://graph.facebook.com/v<API_VERSION>/<Child_Business_id>/managed_partner_business_setup?access_token=<ACCESS_TOKEN>"

回應範例

{
    "id": 3213232, // id of child business
    "meta_data": {
        "seller_business_info": {
            "seller_email_address": "goodseller@fb.com"
            "seller_external_website_url": "www.website.com"
        },
        "ad_account": {
            "id": "434343",
            "spend_limit": "500",
        },
        "page": {
            "id": "123412341",
        },
        "template": [
          {
            "budget_percentage": 0.5,
            "campaign_template_id": "4444444",
            "adgroup_template_ids": [
              "5555555"
            ],
            "targeting_type": "retargeting"      
          },
          {
            "budget_percentage": 0.5,
            "campaign_template_id": "6666666",
            "adgroup_template_ids": [
              "7777777"
            ],
            "targeting_type": "prospecting"
          } 
        ]     
    }
}

錯誤代碼

使用範本

範本是 Marketplace 在（合約）合作夥伴廣告服務中配置和使用的資產。範本包含詳細資訊和設定或「元件」，可帶動由 Marketplace 代表賣家所進行的賣家行銷活動。

範本的元件包括廣告組合和廣告，其中包括目標設定、廣告創意、格式等資訊。每個行銷活動範本都需要四個元件：

• 開發潛在顧客的廣告組合元件
• 廣告元件
• 再行銷的廣告組合元件
• 廣告元件

範本的類型

範本分為預設預設與自訂兩種類型：

自訂範本的必備條件

建立自訂範本之前，Marketplace 必須先建立製作者企業管理平台，如此可確保用於建立範本的行銷活動符合賣家行銷活動的協作廣告自訂和必備條件。企業管理平台具有製作者身分，可用於範本建立流程的來源廣告。

必須具備再行銷廣告組合、開發潛在顧客廣告組合和廣告元件，才能新增和／或配置賣家的自訂行銷活動範本。

範本建立流程所使用的行銷活動必須與協作廣告廣告帳號相關，並且具有以下設定：

• 行銷活動目標必須為目錄銷售。
• 在廣告管理員中，必須在行銷活動層級開啟預算最佳化，並使用「最低成本」出價策略。
• 廣告格式必須是輪播廣告，不含靜態疊壓文字、圖像或影片。

自訂範本流程

步驟 1：建立自訂行銷活動範本

1. 前往協作中心的資產頁籤。在該頁籤內，庫存範本部分顯示可用於賣家行銷活動的範本和範本元件合集。
2. 點擊建立範本開啟進度列圖卡。
3. 提供廣告組合或廣告編號，搜尋現有的有效來源行銷活動。
4. 若要建立範本元件，請選擇從來源編號擷取的廣告組合和／或廣告。您需要為自訂範本建立所有四個元件（2 個廣告和 2 個廣告組合）。
5. 提供名稱和說明來儲存範本。

在範本建立流程期間，系統將刪除來源行銷活動中賣家特定的詳細資訊（例如目錄子集、商品組合、Facebook 粉絲專頁和目的地網址）。使用範本建立的最終行銷活動包含這些欄位的賣家特定資訊，並具有行銷活動總預算和最低成本出價策略。

步驟 2：將自訂範本套用於賣家

自訂範本可依以下方式使用：

• 在賣家加入時使用，為新的賣家行銷活動指派特定範本。
• 變更賣家的範本，啟動假日或其他特殊行銷活動。

如果您想變更賣家的行銷活動範本，一定要具備範本元件，用於取代現有行銷活動範本中的範本元件 - 您可以取代 1 個或全部。如果您要為沒有自訂範本的賣家建立新範本，則需要準備好所有四個元件（2 個廣告和 2 個廣告組合）以供使用。

使用以下任一方式可將範本套用於賣家：

單一賣家範本應用程式用戶介面流程

1. 前往協作中心的賣家頁籤，選擇要套用自訂範本的賣家。
2. 開啟該賣家的共用資產頁籤。賣家一開始沒有配置自訂行銷活動範本。
3. 點擊新增自訂。此時會彈出一個視窗，您可於其中選擇在範本建立步驟期間所建立的範本元件，以套用於選擇的賣家。
4. 您可以指定開發潛在顧客廣告組合和再行銷廣告組合的花費上限，其會以花費金額佔行銷活動總預算的百分比表示。系統將根據成效，持續即時將這筆預算分配給兩個廣告組合。也就是說，當行銷活動結束時，各廣告組合花費的預算百分比可能會少於你設定的花費上限。系統預設會平均分配兩個廣告組合之間的花費上限，但可以變更。
5. 點擊儲存，系統會將選擇的範本元件套用於賣家。

批量範本應用程式用戶介面流程

此功能的用途是讓 Marketplace 能夠將範本元件同時套用於多個賣家，以提供可擴充性。

1. 前往協作中心的賣家頁籤，使用核取方塊欄選擇一組要套用範本的賣家。
2. 點擊套用範本繼續範本應用程式流程。
3. 系統將根據賣家選項顯示一個視窗

• 如果選擇的賣家沒有現有的自訂範本，請選擇四個範本元件，並為開發潛在顧客和再行銷指定花費上限百分比。系統預設會平均分配兩個廣告組合之間的花費上限。
• 如果選擇的賣家之前已套用自訂範本，請為選擇的賣家選擇要替換的所有、一個或部分範本元件。開啟切換開關可為賣家覆寫廣告組合的花費上限百分比。
• 如果選擇的賣家是具有自訂範本和不具自訂範本的賣家組合，系統會顯示一個視窗，用於選擇「不具自訂範本的賣家」或「具有自訂範本的賣家」以進行下一步。根據選擇的選項，系統將顯示前兩個選項的視窗。

最後點擊儲存。系統會將選擇的範本元件套用於選擇的賣家。

更新賣家業務配置 API

使用更新賣家業務配置 API 可將自訂範本套用於具有輸入參數 template 的賣家。

"template":[
  {
    "budget_percentage":0.5,
    "campaign_template_id":"160235235998069",
    "adgroup_template_ids":[
      "447963739637509"
    ],
    "targeting_type":"retargeting"
  },
  {
    "budget_percentage":0.5,
    "campaign_template_id":"278452090413983",
    "adgroup_template_ids":[
      "458654975391261"
    ],
    "targeting_type":"prospecting"
  }
]

步驟 3：建立行銷活動

使用主要行銷活動建立流程指示，透過指定的參數和之前套用的自訂範本建立和刊登賣家的廣告。若要使用套用於該賣家的自訂行銷活動範本，請將 use_seller_template 設為 true。