Business Management APIs

Chức năng giữa các doanh nghiệp

Kể từ ngày 08/06/2021, chúng tôi giới hạn quyền truy cập vào các điểm cuối sau đây. Ứng dụng không có quyền truy cập sẽ gặp lỗi.

Yêu cầu quyền truy cập vào tài sản

Trình quản lý kinh doanh có thể yêu cầu quyền truy cập vào tài khoản quảng cáo hoặc Trang do Trình quản lý kinh doanh khác sở hữu. Họ phải nêu rõ nhiệm vụ mình muốn chỉ định trong yêu cầu.

Để chỉ định doanh nghiệp cho Trang, bạn phải có mã truy cập trang. Ví dụ:

curl 
  -F "business=<BUSINESS_ID>"
  -F "permitted_tasks=['MODERATE', 'ADVERTISE', 'ANALYZE']"   
  "https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/agencies?access_token=<ACCESS_TOKEN>"

Để yêu cầu quyền truy cập AGENCY, bạn phải cung cấp permitted_tasks trong yêu cầu. Bạn chỉ có thể gửi yêu cầu quyền truy cập vào tài sản cho Trình quản lý kinh doanh mà bạn định phê duyệt và họ phải biết đến doanh nghiệp của bạn rồi.

Ví dụ: một doanh nghiệp cần quyền truy cập vào adaccount_id và muốn có khả năng chỉ định nhân viên của mình làm ['ADVERTISE', 'ANALYZE'], doanh nghiệp đó sẽ phải thực hiện lệnh gọi POST sau đây:

curl \
  -F "adaccount_id=act_<AD_ACCOUNT_ID>" \
  -F "permitted_tasks=['ADVERTISE','ANALYZE']" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/client_ad_accounts?access_token=<ACCESS_TOKEN>"

Tương tự như đối với Trang, nếu bạn muốn chỉ định nhiệm vụ ['ADVERTISE', 'ANALYZE'] cho Trang mà ai đó không sở hữu:

curl \
  -F "page_id=<PAGE_ID>" \
  -F "permitted_tasks=['ADVERTISE','ANALYZE']" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/client_pages?access_token=<ACCESS_TOKEN>"

Các lệnh gọi này sẽ gửi thông báo cho quản trị viên tương ứng của tài khoản quảng cáo hoặc Trang để đề nghị chấp nhận yêu cầu quyền truy cập. Quản trị viên tương ứng sẽ nhìn thấy thông báo trong Trình quản lý quảng cáo hoặc Trình quản lý Trang. Họ cũng có thể chấp nhận yêu cầu đó trên giao diện người dùng. Nếu bạn muốn xem các yêu cầu chưa xử lý qua API, hãy gửi yêu cầu GET rồi tích vào PENDING đối với trường access_status.

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

Phản hồi:

"data": [
 {
    "name": "Random Page", 
    "page_permissions": [
    {
    "id": "1900952844321", 
    "permitted_tasks": [
        'MANAGE',
        'CREATE_CONTENT', 
        'MODERATE',  
        'ADVERTISE', 
        'ANALYZE',
    ], 
    "access_status": "CLIENT_RESPONSE_PENDING", 
    "access_requested_time": "2014-01-07T23:26:09+0000", 
    "access_updated_time": "2014-01-07T23:26:09+0000"
    }
    ], 
    "id": "190137931178903"
 },

Cấp quyền truy cập vào tài sản cho Trình quản lý kinh doanh khác

Đây còn được gọi là thêm Agency vào đối tượng của bạn.

Để chấp nhận yêu cầu quyền truy cập của một đối tượng mà bạn sở hữu từ trình quản lý kinh doanh khác hoặc để cấp quyền truy cập của một trong các đối tượng mà bạn sở hữu cho trình quản lý kinh doanh khác, bạn phải chỉ định doanh nghiệp và danh sách các nhiệm vụ mà họ cần có quyền truy cập.

Nếu mã truy cập dùng để thực hiện lệnh gọi API thuộc về người dùng hoặc người dùng hệ thống có quyền truy cập vào tài sản được yêu cầu thông qua doanh nghiệp, bạn chỉ có thể cấp quyền truy cập vào tài sản đó nếu doanh nghiệp này là OWNER của tài sản. Bạn không thể cấp quyền truy cập vào tài sản mà bạn chỉ là AGENCY của tài sản.

Ví dụ: để cấp cho ai đó quyền truy cập vào tài khoản quảng cáo bằng nhiệm vụ [ADVERTISE,ANALYZE], hãy sử dụng yêu cầu POST sau đây:

curl \
  -F "business=<BUSINESS_ID>" \
  -F "permitted_tasks=['ADVERTISE', 'ANALYZE']" \
  "https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/agencies?access_token=<ACCESS_TOKEN>"

Cách cấp cho doanh nghiệp quyền truy cập vào trang bằng nhiệm vụ [ADVERTISE], [MODERATE] và [ANALYZE]:

curl \
  -F "business=<BUSINESS_ID>" \
  -F "permitted_tasks=['MODERATE', 'ADVERTISE', 'ANALYZE']" \
  "https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/agencies?access_token=<ACCESS_TOKEN>"

Trong trường hợp cấp quyền truy cập vào tài khoản quảng cáo, đôi khi một quản trị viên doanh nghiệp khác cần phải xét duyệt như một biện pháp bảo mật. Có thể truy cập vào https://business.facebook.com/settings/requests/admin_reviews để phê duyệt quy trình xét duyệt này. Trong trường hợp này, phản hồi sẽ có thêm một trường cho biết việc xét duyệt là bắt buộc.

{
  "success": true,
  "requires_admin_approval": true
}

Quản trị viên Trang cũng có thể chấp nhận yêu cầu quyền truy cập của agency trong tab Manage Admin Roles thuộc phần Cài đặt Trang trên facebook.com.

Gỡ quyền truy cập vào tài sản

Đây còn được gọi là xóa agency khỏi doanh nghiệp của bạn. Cách gỡ quyền truy cập của trình quản lý kinh doanh vào tài khoản quảng cáo của bạn:

curl \
  -X DELETE \
  -F "business=<BUSINESS_ID>" \
  "https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/agencies?access_token=<ACCESS_TOKEN>"

Tương tự, sau đây là cách gỡ quyền truy cập của Doanh nghiệp vào Trang của bạn:

curl \
  -X DELETE \
  -F "business=<BUSINESS_ID>" \
  "https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/agencies?access_token=<ACCESS_TOKEN>"

Xem quyền truy cập của agency

Để xem tất cả doanh nghiệp có quyền truy cập vào tài khoản quảng cáo của bạn, hãy thực hiện lệnh gọi GET sau đây:

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

Cách xem tất cả doanh nghiệp có quyền truy cập vào trang của bạn:

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

Cách xem tất cả doanh nghiệp có quyền truy cập vào tài sản doanh nghiệp của bạn:

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

Xem quyền truy cập của khách hàng

Để xem tất cả doanh nghiệp đã cấp cho bạn quyền truy cập vào một hoặc nhiều tài khoản quảng cáo hoặc trang của họ, hãy sử dụng lệnh gọi GET sau đây:

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

Managing Your Relationship as an Ad Agency Acting on Behalf of Another Business

These APIs allow you to manage the relationship between your Ad Accounts and the businesses for which you are acting on behalf of (OBO). Creating these relationships allows you to access custom audiences for the business and use of the audience overlap tool.

View OBO Request Details

To view the details of an OBO request, make this GET request:

curl -G \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<OBO_REQUEST_ID>?fields=id,receiving_business,requesting_business,status,business_owned_object"

The response contains the details of the OBO request and looks like this:

{
  "id": "1111111111",
  "receiving_business": {
    "id": "2222222222",
    "name": "Example Business Name"
  },
  "requesting_business": {
    "id": "3333333333",
    "name": "Example Business Name"
  },
  "status": "IN_PROGRESS",
  "business_owned_object": "1111111111"
}

Delete OBO Request

To cancel a pending request to act OBO another business, make this DELETE request:

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

The response, indicating success or failure, looks like this:

{
  "success": "true" 
}

View the Status of OBO Requests for an Ad Account

To view the status of requests to act OBO another business for an Ad account, make this GET request:

curl -G \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/onbehalf_requests?
    fields=id,status,receiving_business,requesting_business&status=<STATUS>"

The status parameter in the request must be APPROVE, DECLINE, or IN_PROGRESS.

The response contains an array with the OBO request objects for an Ad account matching the requested status.

Example response:

{
  "data": [
    {
      "id": "1111111111",
      "status": "IN_PROGRESS",
      "receiving_business": {
        "id": "2222222222",
        "name": "Example Business Name"
      },
      "requesting_business": {
        "id": "3333333333",
        "name": "Example Business Name"
      }
    }
  ]
}

View OBO Requests Received From Other Businesses

To view requests of IN_PROGRESS OBO requests sent to your business, make this GET request:

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

The response contains the IN_PROGRESS OBO request IDs and looks like this:

{
  "data": [
    {
      "id": "1111111111"
    },
    {
      "id": "2222222222"
    },
    {
      "id": "3333333333"
    }
  ]
}

View Pending OBO Requests Sent by Your Business

To view OBO requests that were sent by your business that are still in the IN_PROGRESS state, make this GET request:

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

The response contains the IN_PROGRESS OBO request IDs and looks like this:

{
  "data": [
    {
      "id": "1111111111"
    },
    {
      "id": "2222222222"
    },
    {
      "id": "3333333333"
    }
  ]
}

Tìm hiểu thêm