Business Management APIs

開始使用

參考文件

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

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

必備條件

  • 您的應用程式必須具備適當的行銷 API 存取層級，才能使用企業管理平台 API。請注意，在某些情況下，應用程式可能需要 Advanced Access。深入瞭解不同存取權限層級。
  • 您的應用程式也需具備 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 代表您的商家，請建立粉絲專頁。

若要檢視企業管理平台屬性，請使用企業管理平台編號。要求建立企業管理平台所收到的回應中，就會包含這組編號：

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 物件

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

更新企業管理平台

向 https://graph.facebook.com/{API_VERSION}/{BUSINESS_ID} 傳送 POST 要求，即可更新企業管理平台欄位。例如，變更商家名稱：

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>/"

產業別為以下任一字串常數：

  • 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

您可使用以下選項：

名稱 說明

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 要求，擷取各個工作人員群組。若要取得所有企業管理平台相關人員（請注意，須具備 Advanced Access 才能執行這項操作），步驟如下：

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 管理此狀態。