Business Management APIs

開始使用

參考文件

若要使用企業管理平台，商家至少需要一個粉絲專頁、管理員、商家名稱和有效的電子郵件地址。

商家名稱僅用於您的商家以及您選擇與之共享物件的任何其他商家。建立此商家後，您可以新增屬於商家的粉絲專頁、廣告帳號、應用程式、離站轉換追蹤物件，以及其他與廣告相關的資產。

需求

  • 您的應用程式需要適當的行銷 API 存取層級，才能使用企業管理平台 API。請注意，在某些情況下，您的應用程式可能需要進階存取權限。深入瞭解不同的存取權限層級。
  • 您的應用程式也需要 business_management 權限。
  • 您的用戶也需要 business_management 權限。

建立新的企業管理平台

建立新的企業管理平台來代表您的商家。僅限在為您自己或客戶設定新的企業管理平台時，才能建立新的企業管理平台。如果您需要另一個廣告帳號或另一個粉絲專頁的存取權限，應使用現有的企業管理平台和資產權限。不允許刪除企業管理平台。

例如，使用 POST 建立新的企業管理平台：

curl \
  -F "name=Pomni Media" \
  -F "vertical=ADVERTISING" \
  -F "primary_page=<PAGE_ID>" \
  -F "timezone_id=1" \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<USER_ID>/businesses"

需求

若要建立商家，您需要：

  • 存取權杖
  • 粉絲專頁編號
  • 產業
  • 應用程式範圍用戶編號

您提供的粉絲專頁編號應該是您商家的主要粉絲專頁。此粉絲專頁在 Facebook 上公開代表您的商家。建立商家的人就是此粉絲專頁的管理員。如果您在 Facebook 上沒有代表自己商家的粉絲專頁，請建立粉絲專頁。

產業為下列其中一個字串常數：

ADVERTISING , AUTOMOTIVE , CONSUMER_PACKAGED_GOODS , ECOMMERCE , EDUCATION , ENERGY_AND_UTILITIES , ENTERTAINMENT_AND_MEDIA , FINANCIAL_SERVICES , GAMING , GOVERNMENT_AND_POLITICS ,MARKETING , ORGANIZATIONS_AND_ASSOCIATIONS , PROFESSIONAL_SERVICES , RETAIL , TECHNOLOGY , TELECOM , TRAVEL , OTHER

若要檢視商家的屬性，請使用其編號。該編號是建立企業管理平台要求中，所得到回應的一部分：

curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>?access_token=<ACCESS_TOKEN>"

您也可以查看可存取的企業管理平台清單：

curl "https://graph.facebook.com/<API_VERSION>/me/businesses?access_token=<ACCESS_TOKEN>"

回應欄位包括：

名稱 說明

name

類型：字串

商家的名稱

timezone_id

類型：整數

商家的時區編號

primary_page

類型：JSON 物件

與此企業管理平台相關聯的主要粉絲專頁物件。

{ "category": "App page", "name": "Sample Primary Page", "id": "123456789" }

id

類型：長整數

企業管理平台編號

update_time

類型：字串

此企業管理平台上次更新的時間

updated_by

類型：JSON 物件

上次更新此企業管理平台的用戶（依名稱和編號）

creation_time

類型：字串

此商家建立的時間

created_by

類型：JSON 物件

建立此企業管理平台的用戶名稱和編號

更新企業管理平台

若要更新企業管理平台中的欄位，請發出 POST 要求至 https://graph.facebook.com/{API_VERSION}/{BUSINESS_ID}。例如，變更商家名稱：

curl \
-F "name=My Actual Business Name" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/"

若要變更商家產業，請發出以下 POST 要求：

curl \
-F "vertical=RETAIL" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/"

您有以下選項：

名稱 說明

name

必要項目。

商家的名稱

primary_page

與此企業管理平台相關聯的主要粉絲專頁編號。

您可以發出以下 POST 要求來更新主要粉絲專頁。主要粉絲專頁必須為企業管理平台所擁有。

curl \
  -F "primary_page=<PAGE_ID>" \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/"

您也可以在一個 POST 要求中更新上述所有內容：

curl \
  -F "name=My Actual Business Name" \
  -F "vertical=RETAIL" \
  -F "primary_page=<PAGE_ID>" \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/"

管理用戶和角色

企業管理平台中有兩種角色類型：

名稱 API 常數 說明

管理員

ADMIN

  • 可控制商家的所有層面，包括修改或刪除帳號，以及新增或移除員工名單中的人員。
  • 具有企業管理平台連結之所有資產的 READ 和 WRITE 存取權限。

員工

EMPLOYEE

  • 可以查看企業管理平台設定中的所有資訊，並可由企業管理平台管理員指派角色。無法進行任何變更，除非此用戶本身是粉絲專頁或廣告帳號的管理員，才能將該粉絲專頁或廣告帳號新增至商家。
  • 具有企業管理平台連結之所有資產的 READ 存取權限。

如需有關角色的詳細資訊，請參閱在企業管理平台中設定目錄角色。

一開始，商家的建立者是該商家的唯一用戶，也是管理員。

邀請成員

若要將同事加入您的商家，您必須邀請他們。若要邀請某人，請提供他們有權存取的有效電子郵件地址。傳送要求來新增員工至企業管理平台的數量有限。達到此限制時，您會收到錯誤代碼 17，24 小時後應該會恢復。

若要邀請某人做為管理員，請傳送 POST 要求：

curl \
-F "email=some@email.com" \
-F "role=ADMIN" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/business_users"

若要邀請某人做為員工，請傳送 POST 要求：

curl \
-F "email=some@email.com" \
-F "role=EMPLOYEE" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/business_users"

Facebook 會傳送電子郵件邀請函至您指定的工作電子郵件地址。受邀者必須查看電子郵件並遵循註冊程序操作。完成後，您可以在「用戶」清單中看到他們。

企業管理平台上的人員

從 2.11 版開始，我們設有個別的端點，可根據用戶的狀態來取得用戶。您可以發出 GET 要求來擷取每個用戶群組。若要取得所有商家用戶（請注意，這需要進階存取權限）：

curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/business_users?access_token=<ACCESS_TOKEN>"

若要取得系統用戶（具有系統層級存取權限）：

curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/system_users?access_token=<ACCESS_TOKEN>"

若要取得待回覆的用戶（受邀存取商家，但尚未接受邀請）：

curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/pending_users?access_token=<ACCESS_TOKEN>"

端點會傳回商家的有效用戶、待回覆用戶或系統用戶。例如：

{
  "data": [
    {
      "id": "<BUSINESS_ID>",
      "name": "Alpha MK",
      "email": "some@email.com",
      "role": "EMPLOYEE",
    }
  ]
}

待回覆用戶的結果如下所示：

{
  "data": [
    {
      "id": "<BUSINESS_ID>",
      "email": "some@email.com",
      "role": "EMPLOYEE",
      "status": "PENDING",
      "owner": {
        "id": "USER_ID",
        "name": "Generic Emporium"
      }
    }
  ]
}

傳回欄位的定義如下：

名稱 說明

id

類型：長整數

此用戶在此商家範圍內的編號。

name

類型：字串

隸屬此商家的用戶名稱

business

類型：JSON 物件

此用戶所屬的企業管理平台

first_name

類型：字串

隸屬此商家的用戶名字

last_name

類型：字串

隸屬此商家的用戶姓氏

title

類型：字串

隸屬此商家的用戶職稱

role

類型：字串

此用戶在此商家擔任的角色：EMPLOYEE 或 ADMIN

email

類型：字串

用戶的電子郵件地址

變更角色

若要變更有效用戶在商家中的角色，請提供該用戶的用戶編號。例如，您可以使用以下 POST 要求，將「員工」升級為「管理員」角色：

curl \
  -F "role=ADMIN" \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_SCOPED_USER_ID>"

若要將某人從「管理員」變更為「員工」角色，請發出 POST 要求：

curl \
  -F "role=EMPLOYEE" \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_SCOPED_USER_ID>"

您可以使用以下 POST 要求，變更待回覆用戶的角色：

curl \
  -F "role=EMPLOYEE" \
    -F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PENDING_USER_ID>"

移除用戶

移除根據企業管理平台成員資格授予某人的權限。限制對廣告帳號和粉絲專頁的存取權限。如果該用戶在您的企業管理平台之外，具有其他廣告帳號和粉絲專頁的存取權限，那些權限不會變更。例如，某用戶可能已將自己加入其他企業管理平台，或具有其他企業管理平台的存取權限。

若要從您的商家移除有效用戶，請發出 DELETE 呼叫：

curl \
  -X DELETE \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_SCOPED_USER_ID>"

若要使用 DELETE 要求來取消待回覆的用戶：

curl \
  -X DELETE \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<PENDING_USER_ID>"

這會將用戶從您的商家移除，並移除對商家資產的存取權限。

管理商家資產

參考文件

商家資產是管理員所管理的 Facebook 物件（例如粉絲專頁、應用程式等等）。管理員可以是用戶或商家，或是應用程式的開發人員或廣告商。商家資產的類型如下：

  • 粉絲專頁
  • 帳號
  • 應用程式
  • 目錄
  • Facebook 像素

請參閱查詢範例，並深入瞭解商家資產

帳單

參考文件

企業管理平台 API 可讓您檢視及管理與商家相關聯的帳號額度來源。此 API 會重試企業管理平台可見的所有帳單。這表示此企業管理平台負責的所有帳單都可以透過此 API 來查看，而不只是屬於個別商家編號的帳單。

企業管理平台擁有的一般帳號額度

對於已啟用帳單功能的行銷 API 合作夥伴，您可以利用「企業管理平台擁有的一般帳號額度」。

Facebook 行銷合作夥伴（FBMP）需要聯絡其業務代表，協助設定企業管理平台的帳號額度。請務必要求設定「企業管理平台擁有的一般帳號額度」。設定完成後，您就可以開始使用廣告帳號建立 API 來建立廣告帳號。費用將從您的企業管理平台帳號額度中扣除。

對於透過以下 API 建立的廣告帳號，我們會將額度動態分配至各個帳號，並更新額度限制和花費，以避免達到額度限制。您也可以查看總結的可用額度，以及每個廣告帳號額度的金額。

我們現在只支援一般責任，不支援連帶責任。此設定程序將保持不變。

月底帳單

一旦商家的帳號額度設定完成，且商家使用該帳號額度來投放廣告，我們就會為商業帳號產生月底帳單。若要查看商家帳單，您需要有財務角色。若為商家的一般管理員和員工，您可以在企業管理平台中的 People 之下指派權限。您也可以使用企業管理平台指派財務權限給系統用戶。

若要使用 API 來擷取商業帳號下的帳單，請傳送 GET 要求：

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/business_invoices?start_date=2017-01-01&end_date=2017-04-01"

結果範例如下所示：

{
  "business_invoices": {
    "data": [
      {
        "id": "1659175694099710",
        "billing_period": "2017-03-01"
      },
      {
        "id": "1303851778395619",
        "billing_period": "2017-01-01"
      },
      {
        "id": "1415846861611329",
        "billing_period": "2017-02-01"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MgZDZD"
      }
    }
  },
  "id": "249554531892085"
}

您可以使用以下要求來取得行銷活動層級的帳單詳細資料：

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/business_invoices?fields=billed_amount_details,billing_period,entity,id,invoice_id,payment_term,type,campaigns&start_date=2019-06-01&end_date=2019-07-01"

回應如下所示：

{
  "business_invoices": {
    "data": [
      {
        "billed_amount_details": {
          "currency": "USD",
          "net_amount": "387.70",
          "tax_amount": "0.00",
          "total_amount": "387.70"
        },
        "billing_period": "2017-03-01",
        "entity": "FBUS",
        "id": "1659175694099710",
        "invoice_id": "22736800",
        "liability_type": "Normal",
        "invoice_type": "Invoice",
        "payment_term": "CUSTOMER",
        "type": "Invoice",
        "campaigns": {
          "data": [
            {
              "campaign_id": "6056967798500",
              "campaign_name": "Nhận ưu đãi",
              "tags": [
                "hello2"
              ],
              "billed_amount_details": {
                "currency": "USD",
                "net_amount": "207.62",
                "tax_amount": "0.00",
                "total_amount": "207.62"
              }
            },
            {
              "campaign_id": "6056958052500",
              "campaign_name": "Nhận ưu đãi",
              "billed_amount_details": {
                "currency": "USD",
                "net_amount": "180.08",
                "tax_amount": "0.00",
                "total_amount": "180.08"
              }
              "impressions": 100,
              "clicks": 50,
              "conversions": 30
            }
          ]
        }
      },
      {
        "billed_amount_details": {
          "currency": "USD",
          "net_amount": "382.99",
          "tax_amount": "0.00",
          "total_amount": "382.99"
        },
        ......
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MgZDZD"
      }
    }
  },
  "id": "1515766328651000"
}

您也可以擷取其他帳單欄位：

  • invoice_date - Facebook 產生帳單的日期
  • due_date - 帳單到期日
  • payment_status - 顯示帳單為 Paid、Unpaid 或 Partially Paid
  • amount_due - 帳單上目前的應付帳款和未付帳款是多少
  • download_uri - 在此 URI 下載帳單的 PDF

支付方式 API

若要擷取與企業管理平台相關聯的共用帳號額度支付方式，請傳送此 GET 要求。

curl "https://www.graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/extendedcredits"

若要為商家設定支付方式，請在企業管理平台上，前往商家的設定區塊。

動態帳號額度分配

動態帳號額度分配（DCAF）是我們的帳號額度分配系統，可依據每個廣告帳號定期調整可用額度。我們的自動化指令碼大約每 30 分鐘執行一次，取得您的可用額度，並平均分配至已啟用 DCAF 的所有有效帳號。可用額度包含核准的總額度減去未付款項總額。這有助於管理廣告帳號層級的花費，並為每個廣告帳號分配資金。

商家也可以「停用」已開立帳單的廣告帳號，並將該廣告帳號從需要分配額度的清單中移除。商家不再需要由 Facebook 管理此狀態。