Business Management APIs

시작하기

참조 문서

비즈니스 관리자를 사용하려면, 비즈니스에 하나 이상의 페이지, 관리자, 비즈니스 이름 및 유효한 이메일 주소가 필요합니다.

비즈니스 이름은 자신의 비즈니스와 자신이 개체를 공유하기로 선택한 다른 비즈니스에만 사용됩니다. 이 비즈니스를 만들고 나면 페이지, 광고 계정, 앱, 오프사이트 전환 추적 개체, 비즈니스에 속한 기타 광고 관련 자산을 추가할 수 있습니다.

요구 사항

새 비즈니스 관리자 만들기

비즈니스를 대표할 새 비즈니스 관리자를 만듭니다. 자신 또는 고객을 위해 새 비즈니스 관리자를 설정하는 경우에만 새 비즈니스 관리자를 만드세요. 다른 광고 계정이 필요하거나 다른 페이지에 대한 액세스 권한이 필요한 경우, 기존 관리자와 자산 권한을 사용해야 합니다. 비즈니스 관리자는 삭제할 수 없습니다.

예를 들어 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
  • 업종
  • 앱 범위 사용자 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 개체

이 비즈니스 관리자와 연결된 기본 페이지의 개체입니다.

{ "category": "App page", "name": "Sample Primary Page", "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>/"

하나의 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

유형: 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 개체(예: 페이지, 앱)입니다. 관리자는 사용자 또는 비즈니스일 수 있고 앱의 경우에는 개발자나 광고주가 될 수 있습니다. 연결 개체의 유형은 다음과 같습니다.

  • 페이지 및 장소
  • 이벤트
  • 앱
  • 도메인

샘플 쿼리를 확인하고 연결 개체에서 자세한 내용을 알아보세요.

인보이스

참조 문서

Business Manager API를 사용하면 비즈니스와 관련된 크레딧 소스를 확인하고 관리할 수 있습니다. 이 API는 비즈니스 관리자에 보이는 모든 인보이스를 다시 시도합니다. 즉, 개별 비즈니스 ID에 속한 인보이스뿐만 아니라 이 비즈니스 관리자가 관리하는 모든 인보이스를 API를 통해 확인할 수 있습니다.

비즈니스 관리자가 소유한 일반 크레딧 라인

인보이스를 활성화한 마케팅 API 파트너를 위해 비즈니스 관리자가 소유한 일반 크레딧 라인을 활용할 수 있습니다.

크레딧을 위해 비즈니스 관리자를 설정하고자 하는 Facebook 마케팅 파트너(FBMP)인 경우 영업 담당자에게 문의하세요. 비즈니스 관리자가 소유한 일반 크레딧 라인을 요청하세요. 이 설정이 완료되고 나면 광고 계정 생성 API를 사용하여 광고 계정을 만들기 시작할 수 있습니다. 비즈니스 관리자 크레딧 라인에 요금이 청구됩니다.

다음 API를 통해 만든 광고 계정의 경우, Facebook이 계정 전반에 걸쳐 크레딧을 동적으로 분배하고 크레딧 한도에 도달하지 않도록 크레딧 한도 및 지출을 업데이트합니다. 사용 가능한 크레딧 요약 및 각 광고 계정의 크레딧 금액을 확인할 수도 있습니다.

현재는 일반 책임만 지원하며 순차적 책임은 지원하지 않습니다. 이에 대한 설정 프로세스는 변경되지 않습니다.

월말 인보이스

비즈니스에 대해 크레딧 라인이 설정되고 비즈니스가 이를 사용하여 광고를 게재하는 경우, Facebook이 비즈니스 계정에 대해 월말 인보이스를 생성합니다. 비즈니스 인보이스를 확인하려면 재무 역할이 필요합니다. 비즈니스의 일반 관리자 및 직원의 경우, 비즈니스 관리자의 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에서 이 상태를 관리하도록 둘 필요가 없습니다.