Tích hợp người bán

Trang này có hướng dẫn về cách tích hợp người bán vào quảng cáo của đối tác được quản lý (MPA) thông qua API Tạo doanh nghiệp của người bán.

Sau khi xác minh một người bán đủ điều kiện tham gia MPA thông qua API Điều kiện của người bán, bạn sẽ sử dụng API Tạo doanh nghiệp của người bán để tích hợp người bán đó.

Khi bạn gọi API Tạo doanh nghiệp của người bán bằng vendor_id của người bán đủ điều kiện, các hành động sau đây sẽ tự động được thực hiện:

  • Tạo một Trình quản lý kinh doanh phụ, một Trang Facebook và một tài khoản quảng cáo cho người bán
  • Chia sẻ hạn mức tín dụng
  • Thiết lập phân khúc danh mục của người bán với vendor_id=<child_business_external_id> làm bộ lọc

Sau khi bạn tích hợp người bán vào MPA, người bán đó sẽ được xem là đối tác được quản lý.

Quyền bắt buộc

Để gọi API Tạo doanh nghiệp của người bán, bạn sẽ cần có những quyền sau đây:

  • Quản trị viên doanh nghiệp
  • Quản trị viên danh mục
  • Quản lý tín dụng
  • Nhà phát triển ứng dụng

Lệnh gọi API Tạo doanh nghiệp của người bán

Yêu cầu

curl \
  -F 'access_token=<ACCESS_TOKEN>' \
  -F 'asyncbatch=[ 
      { 
        "method": "POST", 
        "relative_url": "<MARKETPLACE_BM_ID>/managed_partner_businesses", 
        "name": "<ASYNC_SESSION_NAME>", 
        "body": "child_business_external_id=<VENDOR_ID>&line_of_credit_id=<LINE_OF_CREDIT_ID>&credit_limit=<CREDIT_LIMIT>&partition_type=<PARTITION_TYPE>&catalog_id=<PARENT_CATALOG_ID>&ad_account_currency=<AD_ACCOUNT_CURRENCY>&seller_targeting_countries=['COUNTRY_CODE1','COUNTRY_CODE2']&timezone_id=<TIMEZONE_ID>&name=<BUSINESS_MANAGER_NAME>&seller_external_website_url=<SELLER_EXTERNAL_WEBSITE_URL>&partner_facebook_page_url=<PARTNER_FACEBOOK_PAGE_&page_profile_image_url=<PROFILE_PIC_URL>&vertical=<VERTICAL>&partner_registration_countries=<PARTNER_REGISTRATION_COUNTRY>"
      } 
  ]' \
  "https://graph.facebook.com/v21.0"
      

Hệ thống sẽ trả về ngay phản hồi cho lệnh gọi API kèm theo ASYNC_SESSION_ID. Trong khi yêu cầu này tiếp tục được xử lý, hệ thống sẽ thăm dò ASYNC_SESSION_ID cho đến khi đạt trạng thái cuối cùng là [COMPLETED|FAILED].

Thông số

TênMô tả

ad_account_currency

chuỗi

Bắt buộc.
Đơn vị tiền tệ của tài khoản quảng cáo sẽ được tạo cho người bán.
Chuỗi đầu vào phải là chữ viết tắt đơn vị tiền tệ. Hãy xem bài viết Những đơn vị tiền tệ được chấp nhận đối với tính năng lập hóa đơn hàng tháng.

catalog_id

chuỗi số

Bắt buộc.
ID danh mục của sàn giao dịch, được gọi là danh mục chính.
Trong quá trình tích hợp, bạn có thể lọc danh mục này bằng vendor_id=<child_business_external_id> để tạo phân khúc danh mục cho người bán.

child_business_external_id

chuỗi

Bắt buộc.
Mỗi sàn giao dịch sẽ chuyển ID duy nhất cho từng người bán. Tên của trường ở phía sàn giao dịch là vendor_id.
Trường này được dùng để tạo phân khúc danh mục với bộ lọc vendor_id = <child_business_external_id>.

credit_limit

chuỗi số

Bắt buộc.
Khoản tín dụng tối đa sẽ được chia sẻ với người bán từ line_of_credit_id chính.

Bạn chỉ nên đặt trường này nếu giá trị partition_type được đặt thành FIXED

Điều kiện: Khoản tín dụng có sẵn trong line_of_credit_id >= credit_limit được yêu cầu.

partition_type

chuỗi enum

Bắt buộc.

Đặt thành một trong những giá trị sau đây:

  • FIXED
  • AUTH

Giá trị mặc định:FIXED

Phân bổ cố định hoặc phân bổ tín dụng không hạn chế. Giá trị đã đặt cho thông số credit_limit sẽ được bỏ qua nếu giá trị partition_type được đặt thành AUTH

line_of_credit_id

chuỗi số

Bắt buộc.
ID của hạn mức tín dụng chính để bạn chia sẻ tín dụng với người bán.
Điều kiện:

  1. Chuyển thông số credit_limitad_account_currency.
  2. Không thể chuyển no_ad_account

marketplace_bm_id

chuỗi

Bắt buộc.
ID Trình quản lý kinh doanh của sàn giao dịch.
Hãy xem bài viết Tìm ID doanh nghiệp của bạn trong Trình quản lý kinh doanh của Meta để biết thêm thông tin.

name

chuỗi

Bắt buộc.
Tên Trình quản lý kinh doanh duy nhất được tạo cho người bán.

skip_partner_page_creation

bool

Không bắt buộc.
Đặt là true để bỏ qua bước tạo trang cho người bán.

Giá trị mặc định:false

page_name

chuỗi

Không bắt buộc.

Tên sẽ chỉ định cho trang đã tạo cho người bán.

Bỏ qua đặt thông số này khi skip_partner_page_creation được đặt là true.


Điều kiện: Tên trang phải đáp ứng yêu cầu của Facebook về tên trang.

Giá trị mặc định: Tên trang Facebook của Đối tác được đặt cấu hình trong quá trình tích hợp API Quảng cáo của đối tác được quản lý trong Trung tâm cộng tác.

page_profile_image_url

chuỗi

Không bắt buộc
URL để tìm nạp hình ảnh cho ảnh đại diện trên trang người bán.

Bỏ qua đặt thông số này khi skip_partner_page_creation được đặt là true.

Điều kiện:

  1. Kích thước hình ảnh >= 180 * 180 pixel
  2. Kích thước hình ảnh < 1MB

Giá trị mặc định: Ảnh đại diện trên trang Facebook của Đối tác được đặt cấu hình trong quá trình tích hợp API Quảng cáo của đối tác được quản lý trong Trung tâm cộng tác.

seller_external_website_url

chuỗi

Bắt buộc.
URL trang web của người bán.

seller_targeting_countries

danh sách<string>

Bắt buộc.
Mảng chuỗi chứa quốc gia nhắm mục tiêu của người bán.
Giá trị là mã quốc gia thay vì tên quốc gia. Trong quá trình tạo quảng cáo, quốc gia này sẽ được dùng làm quốc gia nhắm mục tiêu mặc định trong nhóm quảng cáo. Hãy tham khảo bài viết Mã quốc gia.

partner_facebook_page_url

chuỗi

Không bắt buộc.
URL Trang Facebook của người bán.

partner_registration_countries

chuỗi

Bắt buộc.
Quốc gia đăng ký kinh doanh của người bán.
Giá trị là mã quốc gia thay vì tên quốc gia. Hãy tham khảo bài viết Mã quốc gia.

timezone_id

chuỗi số

Bắt buộc.
ID múi giờ của tài khoản kinh doanh/quảng cáo.
Hãy tham khảo bài viết ID múi giờ.

vertical

chuỗi enum

Bắt buộc.
Đặt thành một trong những giá trị sau đây:

  • 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

Phản hồi

{
  "async_sessions": [
    {
      "id": "<ASYNC_SESSION_ID>",
      "name": "<ASYNC_SESSION_NAME>"
    }
  ]
}
    

Sử dụng ASYNC_SESSION_ID để lấy ID tương ứng của người bán được tích hợp vào quảng cáo của đối tác được quản lý.

Xem phần Cách thăm dò phiên không đồng bộ cho phản hồi để biết thêm thông tin.

Phản hồi thành công

Nếu trạng thái là COMPLETED, dữ liệu thu được khi thăm dò phiên không đồng bộ sẽ có dạng như sau:

{
  "result": "{\"id\":\"<NEWLY_CREATED_MANAGED_PARTNER_BM_ID>\"}",
  "status": "COMPLETED",
  "id": "<ASYNC_SESSION_ID>"
}
    

Phản hồi không thành công

Nếu trạng thái là FAILED, dữ liệu thu được khi thăm dò phiên không đồng bộ sẽ có dạng như sau:

Mã lỗi

Khi gửi yêu cầu đến API tích hợp người bán, bạn có thể nhận được một số phản hồi lỗi khác nhau. Hãy xem bài viết Cách xử lý lỗi để biết thêm thông tin.

Mã lỗiMã lỗi phụThông báo lỗi

1800000

2310114

Hoàn tất quy trình tích hợp quảng cáo của đối tác được quản lý trong Trung tâm cộng tác

1800001

2310118

ID nhà cung cấp {vendor_id} đã được sử dụng. Hãy nhập ID nhà cung cấp duy nhất chưa được sử dụng ở bất cứ nơi nào khác.

1800002

2310138

Tên doanh nghiệp {invalid_business_name} không phải là tên hợp lệ. Thay vào đó, hãy cân nhắc sử dụng {suggested_business_name}. Tên doanh nghiệp phải đáp ứng yêu cầu của Facebook về tên doanh nghiệp.

1800002

2310139

Tên doanh nghiệp {invalid_business_name} không phải là tên hợp lệ. Tên doanh nghiệp phải đáp ứng yêu cầu của Facebook về tên doanh nghiệp.

1800003

2310133

Nhập mã quốc gia đăng ký hợp lệ cho doanh nghiệp của đối tác này

1800004

2310127

Gỡ hoặc cập nhật các mã quốc gia không hợp lệ sau đây được liệt kê cho quốc gia đăng ký của đối tác: [{invalid_registration_country_codes}]

1800006

2310141

Gỡ hoặc cập nhật các mã quốc gia không hợp lệ sau đây mà bạn đã nhập: [{invalid_targeting_country_codes}]

1800100

2310117

Không thể sử dụng ID danh mục {catalog_id} mà bạn đã nhập để tạo phân khúc danh mục. Bạn có thể đi đến Công cụ quản lý thương mại để tìm đúng số ID danh mục có chứa mặt hàng của đối tác này. Hãy thử tích hợp lại đối tác bằng ID danh mục chính xác.

1800101

2310116

{business_id} của doanh nghiệp bạn không quản lý ID danh mục {catalog_id} mà bạn đã nhập. Hãy nhập ID danh mục mà doanh nghiệp của bạn quản lý.

1800102

2310115

Kiểm tra ID danh mục {catalog_id} mà bạn đã nhập. Nếu ID này chính xác và bạn cần có quyền truy cập vào danh mục này, hãy yêu cầu ai đó có toàn quyền kiểm soát truy cập vào phần Cài đặt cho doanh nghiệp trong Trình quản lý kinh doanh để cấp cho bạn quyền truy cập. Sau khi bạn chỉ định, hãy thử tích hợp lại đối tác.

1800200

2310119

Nhập ID hạn mức tín dụng mà bạn sẽ dùng để chia sẻ tín dụng với đối tác

1800201

2310144

ID hạn mức tín dụng {line_of_credit_id} mà bạn đã nhập không phải là ID hạn mức tín dụng hoặc tài khoản lập hóa đơn. Hãy nhập ID hạn mức tín dụng được liên kết với ID doanh nghiệp {marketplace_business_id}. Đây phải là hạn mức tín dụng mà doanh nghiệp của bạn dùng để chia sẻ tín dụng với đối tác.

1800202

2310122

Kiểm tra ID hạn mức tín dụng {line_of_credit_id} mà bạn đã nhập. Nếu ID này chính xác và bạn cần có quyền truy cập, hãy yêu cầu ai đó có toàn quyền kiểm soát truy cập vào phần Cài đặt cho doanh nghiệp trong Trình quản lý kinh doanh để cấp cho bạn quyền truy cập để quản lý tài chính. Hãy thử tích hợp lại đối tác sau khi bạn có quyền truy cập để quản lý tài chính.

1800203

2310123

Doanh nghiệp {business_id} của bạn không quản lý hạn mức tín dụng đã nhập {line_of_credit_id}. Hãy cung cấp ID hạn mức tín dụng hoặc tài khoản lập hóa đơn do doanh nghiệp của bạn quản lý.

1800204

2310120

Nhập đơn vị tiền tệ cho tài khoản quảng cáo. Bạn không thể thay đổi cài đặt này sau đó.

1800205

2310145

ID hạn mức tín dụng {line_of_credit_id} không hỗ trợ đơn vị tiền tệ đã nhập {ad_account_currency}. Hãy cập nhật đơn vị tiền tệ cho tài khoản quảng cáo của đối tác thành đơn vị tiền tệ mà hạn mức tín dụng hỗ trợ.

1800206

2310121

Nhập một giá trị hạn mức tín dụng lớn hơn 0

1800207

2310143

Hạn mức tín dụng ${credit_limit} mà bạn đã nhập lớn hơn số dư tín dụng khả dụng là ${available_credit}. Hãy giảm hạn mức tín dụng đã chỉ định hoặc sử dụng ID hạn mức tín dụng khác có số dư cao hơn.

1800305

2310149

Nhập URL hình ảnh cho ảnh đại diện của đối tác. Hình ảnh phải có kích thước từ 180 x 180 pixel trở lên và nhỏ hơn 1MB.

1800306

2310150

Hình ảnh phải có kích thước từ 180 x 180 pixel trở lên và nhỏ hơn 1MB. Kiểm tra kích thước hình ảnh và URL {page_profile_image_url} rồi thử lại hoặc nhập URL hình ảnh mới.

1800306

2310151

Kiểm tra liên kết {page_profile_image_url} hoặc nhập liên kết mới

1800307

2310148

Hệ thống đã hết thời gian chờ xử lý URL hình ảnh {page_profile_image_url}. Hãy kiểm tra URL hình ảnh, thử yêu cầu lại hoặc nhập URL hình ảnh mới.

1800311

2310181

Tên trang {invalid_page_name} không hợp lệ. Thay vào đó, hãy cân nhắc sử dụng {suggested_page_name}. Tên trang phải đáp ứng yêu cầu của Facebook về tên trang.

1800311

2310182

Tên trang {invalid_page_name} không hợp lệ. Tên trang phải đáp ứng yêu cầu của Facebook về tên trang.