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 对象

创建此商务管理平台的用户的账号和编号

更新商务管理平台

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

您有以下选项：

名称 描述

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 会向您指定的工作邮箱发送邮件邀请。受邀者必须查看电子邮件并按照注册流程操作。当他们完成该流程后，您就可以在用户列表中看到他们。

商务管理平台用户

从 v2.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 Pixel 像素代码

请参阅业务资产，查看查询示例并了解详情。

结算单

参考文档

您可通过商务管理平台 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 管理此状态。