Business Management APIs

利用を開始する

参照資料

ビジネスマネージャを使うには、各ビジネスで少なくとも1つのページが必要であり、さらに、管理者、ビジネス名、有効なメールアドレスが必要です。

ビジネス名は、該当ビジネスについて、またさまざまなオブジェクトを共有する相手となる他のビジネスについてのみ使われます。このビジネスを作成したら、ページ、広告アカウント、アプリ、オフサイトコンバージョントラッキングオブジェクト、その他の広告関連アセットを追加できるようになります。

要件

新しいビジネスマネージャを作成する

自分のビジネスを表すビジネスマネージャを作成します。新しいビジネスマネージャを作成するのは、自分や顧客のために新しいビジネスマネージャを設定する場合だけにしてください。別の広告アカウントや別のページへのアクセスが必要な場合は、既存のマネージャとアセットアクセス許可を使う必要があります。ビジネスマネージャを削除することは許可されていません。

例えば、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"

要件

ビジネスを作成するには、以下のものが必要です。

  • アクセストークン
  • ページID
  • バーティカル
  • app-scopedユーザーID

指定するページIDは、ビジネスのメインページでなければなりません。このページは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

ビジネスのプロパティを確認するには、そのIDを使います。

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

型: 整数

ビジネスのタイムゾーンのID

primary_page

型: JSONオブジェクト

このビジネスマネージャに関連付けられているメインページのオブジェクト。

{ "カテゴリ": "アプリページ", "名前": "サンプルメインページ", "id": "123456789" }

id

型: long

ビジネスマネージャのID

update_time

型: 文字列

このビジネスマネージャの最終更新時刻

updated_by

型: JSONオブジェクト

このマネージャを最後に更新したユーザーの名前とID

creation_time

型: 文字列

このビジネスの作成時刻

created_by

型: JSONオブジェクト

このマネージャを作成したユーザー名とID

ビジネスマネージャを更新する

ビジネスマネージャのフィールドを更新するには、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

このビジネスマネージャに関連付けられているメインページのID。

次のPOSTリクエストを発行することにより、メインページを更新することができます。メインページは、ビジネスマネージャ所有のものでなければなりません。

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

上記のすべてを1回の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>/"

ユーザーと役割を管理する

ビジネスマネージャには、2種類の役割があります。

名前 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

型: long

このビジネスをスコープとするこのユーザーのID。

name

型: 文字列

このビジネスでのこのユーザーの名前

business

型: JSONオブジェクト

このユーザーが所属するビジネスマネージャ

first_name

型: 文字列

このビジネスでのこのユーザーの名

last_name

型: 文字列

このビジネスでのユーザーの姓

title

型: 文字列

このビジネスでのユーザーの肩書

role

型: 文字列

このビジネスにおけるこのユーザーの役割。EMPLOYEEまたはADMIN

email

型: 文字列

ユーザーのメールアドレス

役割を変更する

該当ビジネスにおけるアクティブユーザーの役割を変更するには、そのユーザーのユーザーIDを指定します。例えば、以下の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オブジェクトのことです(ページやアプリなど)。管理者となるのが可能なのは、ユーザーまたはビジネス、そしてアプリの場合は開発者または広告主です。コネクションオブジェクトには、次の種類があります。

  • ページとスポット
  • イベント
  • アプリ
  • ドメイン

コネクションオブジェクトにあるサンプルクエリやその他の詳細をご覧ください。

請求書

参照資料

ビジネスマネージャAPIを利用すれば、ビジネスに関連付けられているクレジットソースを確認したり管理したりできます。このAPIでは、ビジネスマネージャで表示可能なすべての請求書が取得されます。つまり、個々のビジネスIDに属する請求書だけでなく、このビジネスマネージャが担当するすべての請求書が、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)は、広告アカウントごとに利用可能なクレジットを定期的に調整するための、Metaクレジット配分システムです。自動化スクリプトが約30分ごとに実行され、利用可能なクレジットを獲得し、それを、DCAFで有効になっているアクティブアカウントすべてに均等に配分します。利用可能クレジットに含まれるのは、承認済みクレジット合計額から未払い残高を差し引いたものです。これは、広告アカウントレベルでの支出を管理したり、各広告アカウントに資金調達を配分したりする上で役立ちます。

またビジネスは、請求対象の広告アカウントを「無効化」し、クレジットの割り当てが必要な広告アカウントをリストから削除することもできます。このステータスの管理作業をビジネスからFacebookに依頼する必要はなくなりました。