CPAlead Full Campaign API: Tạo và quản lý ưu đãi

Full Campaign API của CPAlead cho phép một nhà quảng cáo tự phục vụ đã được xác minh dùng mã, tác nhân AI có khả năng dùng API, MCP server, GPT Action hoặc plugin để làm việc với các chiến dịch CPA, CPI và CPC. Tùy thuộc vào quyền được cấp, một ứng dụng khách được ủy quyền có thể đọc các yêu cầu hiện tại, xác thực một chiến dịch đầy đủ trước khi lưu, tải nội dung sáng tạo lên, tạo chiến dịch, liệt kê và truy xuất chiến dịch, chỉnh sửa chiến dịch với cơ chế bảo vệ phiên bản, đồng thời bắt đầu hoặc tạm dừng rõ ràng một chiến dịch đủ điều kiện.

Đây là người bạn đồng hành tự động hóa cho dashboard advertiser thông thường. Nếu trước tiên bạn muốn một giải thích từng trường về loại chiến dịch, tracking, nhắm mục tiêu, payout, cap, funding, review, và launch, hãy đọc Cách Quảng Cáo trên CPAlead năm 2026: Thêm và Khởi chạy Offer Đầu tiên của Bạn. Hãy dùng bài viết này khi bạn đã sẵn sàng biểu diễn thiết lập đó dưới dạng JSON có cấu trúc và các hành động API được kiểm soát.

Full Campaign API có thể làm gì

API hiện tại không cung cấp thao tác archive, delete, bulk-create, hoặc toggle chung. Công việc archive hoặc delete vẫn là một quy trình trong dashboard. Start và pause là các hành động riêng biệt để một người hoặc client AI có thể yêu cầu xác nhận rõ ràng trước khi thay đổi phân phối.

Chọn giữa Temporary AI Campaign Draft Access, Full Campaign API và Offer API Import

• Temporary AI Campaign Draft Access: Dành cho ChatGPT thông thường và các ứng dụng trò chuyện AI tương tự. Trước khoản nạp tiền thành công đầu tiên của nhà quảng cáo, liên kết riêng tư dùng trong bốn giờ có thể xác thực và lưu tối đa ba bản nháp chiến dịch chưa hoạt động. Sau khi nạp tiền thành công, liên kết không còn giới hạn tổng số bản nháp chiến dịch. Mọi tài khoản có thể có tối đa 10 bản nháp chiến dịch chưa hoàn tất đang chờ xử lý cùng lúc. Quyền này không thể xem hoặc quản lý các chiến dịch hiện có, tải lên, chấp nhận điều khoản hoặc gói khởi chạy, chi tiêu tiền, gửi, bắt đầu, tạm dừng hoặc kích hoạt. Mở Temporary AI Campaign Draft Access.
• Full Campaign API: Dành cho tác nhân có khả năng dùng API, GPT Action, MCP server, plugin hoặc giải pháp tích hợp có thể bảo vệ bearer token. Các phạm vi được cấp có thể xác thực dữ liệu, tải lên, tạo, đọc, chỉnh sửa, bắt đầu và tạm dừng chiến dịch. Mở Full Campaign API.
• Offer API Import: Một quy trình riêng trong bảng điều khiển nhà quảng cáo, lấy ưu đãi từ nguồn cấp dữ liệu bên ngoài tương thích và ánh xạ các trường của nguồn đó vào CPAlead. Mở Offer API Import.

Dùng tùy chọn bản nháp chiến dịch được bảo vệ khi một cuộc trò chuyện AI thông thường giúp bạn chuẩn bị ưu đãi mới. Dùng Full Campaign API khi một ứng dụng khách đã xác thực cần các khả năng quản lý chiến dịch có cấu trúc. Dùng Offer API Import khi CPAlead cần lấy nguồn cấp dữ liệu tương thích. Không cấp cho bất kỳ công cụ nào quyền truy cập rộng hơn mức công việc của nó yêu cầu.

Tạo một token Campaign API

1. Đăng nhập vào tài khoản advertiser tự phục vụ đã được xác minh.
2. Mở Setup → API, rồi chọn Campaign API.
3. Đặt cho token một tên dễ nhận biết, chẳng hạn “Campaign validator” hoặc “My MCP agent.”
4. Chọn thời hạn. Tùy chọn 48 giờ được khuyến nghị cho thiết lập AI; cũng có các tùy chọn 30 ngày, 90 ngày, và 365 ngày.
5. Chỉ chọn những quyền mà client cần.
6. Tạo token và sao chép nó ngay lập tức. CPAlead không thể hiển thị lại toàn bộ token sau khi trang được tải lại.
7. Lưu nó trong cấu hình bí mật của client đáng tin cậy và thu hồi nó khi tác vụ kết thúc.

Một advertiser có thể có tối đa 10 token Campaign API đang hoạt động. Hãy dùng các token riêng cho từng tích hợp riêng biệt để bạn có thể giới hạn quyền, xem xét việc sử dụng, và thu hồi một tích hợp mà không làm gián đoạn tích hợp khác.

Nơi tạo token Campaign API của bạn

Token Campaign API là thông tin xác thực API riêng tư được gửi trong header Authorization. Nó không phải là mật khẩu CPAlead của bạn, và không thể dùng để đăng nhập vào dashboard CPAlead. Sau khi đăng nhập, mở Setup → API, chọn Campaign API, và sử dụng biểu mẫu Create a token.

URL cơ sở, xác thực và định dạng phản hồi

Các yêu cầu đã xác thực gửi token một lần trong header HTTP authorization. Đừng bao giờ đặt nó trong URL hoặc chuỗi truy vấn.

Authorization: Bearer YOUR_TOKEN
Accept: application/json

Đối với các ví dụ curl bên dưới, một thiết lập an toàn hơn là lưu header authorization trong một file cấu hình curl cục bộ, file này bị loại khỏi kiểm soát mã nguồn và chỉ bạn đọc được:

# cpalead-auth.cfg
header = "Authorization: Bearer YOUR_TOKEN"
header = "Accept: application/json"

# Restrict the file before using it:
chmod 600 cpalead-auth.cfg

Một phản hồi thành công có một đối tượng hoặc danh sách data cùng với meta. Metadata bao gồm request_id và phiên bản lược đồ hiện tại, và có thể bao gồm phân trang, phiên bản tài nguyên, hoặc cờ phát lại idempotent. Một phản hồi lỗi có một đối tượng error cùng với meta. Lưu request_id công khai khi khắc phục sự cố với hỗ trợ, nhưng không bao giờ gửi bearer token của bạn cho hỗ trợ.

Bước 1: Đọc yêu cầu trực tiếp

Yêu cầu là nguồn sự thật về những gì tài khoản hiện có thể gửi. Chúng bao gồm phiên bản lược đồ và điều khoản hiện tại, điều kiện đủ điều kiện tạo tài khoản, các quốc gia và thiết bị được hỗ trợ, giới hạn trường, quy tắc loại chiến dịch, phạm vi giá, lịch, gói launch, yêu cầu tracking, quy tắc ảnh, và quy trình được khuyến nghị.

curl --config cpalead-auth.cfg \
  "https://www.cpalead.com/api/v1/advertiser/requirements?type=CPA"

Dùng type=CPA, type=CPI, hoặc type=CPC để giới hạn phản hồi. Đừng hard-code phiên bản lược đồ, phiên bản điều khoản, giới hạn payout, bid, ngân sách, gói launch, quốc gia, thiết bị, hoặc phiên bản ứng dụng tối thiểu từ một ví dụ cũ. Hãy lấy lại yêu cầu khi máy chủ báo rằng một giá trị hoặc phiên bản đã lỗi thời.

Ba loại chiến dịch

• CPA: Trả tiền cho một hành động hoặc nhiều sự kiện có thưởng. URL theo dõi phải chứa {CLICK_ID}. URL xem trước, giới hạn hằng ngày và gói khởi chạy là các phần trong dữ liệu tạo chiến dịch. Chiến dịch trả tiền một lần cần có mục tiêu chuyển đổi; chiến dịch sự kiện xác định từng hành động có thưởng trong danh sách sự kiện.
• CPI: Trả tiền cho một lượt cài đặt hoặc hành động trong ứng dụng, hoặc nhiều sự kiện có thưởng. Loại này sử dụng {CLICK_ID} và có thêm các lựa chọn dành cho ứng dụng như nền tảng thiết bị, phương thức theo dõi, phiên bản hệ điều hành được hỗ trợ và cách xử lý proxy. Thêm một sự kiện cài đặt riêng nếu bạn muốn trả tiền cho lượt cài đặt trong chiến dịch sự kiện.
• CPC: Trả tiền cho một click hợp lệ. Nó dùng bid và ngân sách hàng ngày thay vì payout chuyển đổi, daily cap, và launch package.

Tất cả giá trị tiền tệ trong Campaign API đều tính bằng USD và lịch chạy qua API sử dụng UTC. Với CPA và CPI, mức trả dưới $10.00 yêu cầu giới hạn hằng ngày ít nhất là 20. Mức trả từ $10.00 trở lên cho phép giới hạn hằng ngày thấp nhất là 5. Với chiến dịch sự kiện, hãy dùng tổng tiền trả cho tất cả sự kiện để áp dụng các quy tắc về giới hạn tối thiểu này. Đọc yêu cầu hiện tại trước khi chọn mức trả và giới hạn.

Bước 2: Tải ảnh chiến dịch lên

Các yêu cầu create không chấp nhận URL ảnh từ xa. Hãy tải tệp lên trước dưới dạng multipart form data, rồi đặt ID ảnh tạm thời trả về vào image_upload_id.

curl --config cpalead-auth.cfg \
  --request POST \
  --form "[email protected]" \
  "https://www.cpalead.com/api/v1/advertiser/images"

• Nguồn được chấp nhận: JPG, JPEG, PNG, GIF, BMP, và WebP.
• Kích thước tệp tối đa: 2 MiB.
• Chiều rộng và chiều cao nguồn: mỗi chiều phải nằm trong khoảng 200 đến 4096 pixel.
• Kết quả được lưu: một ảnh crop WebP 200×200 không động, không có metadata.
• Thời gian tồn tại của upload chưa dùng: 24 giờ.
• Giới hạn upload đang chờ: tối đa 25 upload ảnh chưa dùng hiện tại.
• Sử dụng: một lần tạo chiến dịch hoặc cập nhật ảnh. Hãy upload lại cho một chiến dịch khác.

Validation có thể kiểm tra rằng một ID ảnh thuộc về tài khoản của bạn và vẫn có thể dùng mà không tiêu thụ nó. Lần ghi chiến dịch thành công sẽ tiêu thụ nó. Việc phát lại cùng một lệnh create đã hoàn tất với cùng idempotency key sẽ trả về kết quả đã lưu; nó không tạo chiến dịch thứ hai từ ảnh đã được tiêu thụ.

Bước 3: Xây dựng JSON chiến dịch hoàn chỉnh

API sử dụng các đối tượng JSON nghiêm ngặt. Các trường không xác định sẽ bị từ chối thay vì bị bỏ qua âm thầm. Điều đó làm cho tích hợp AI an toàn hơn: một thuộc tính viết sai chính tả hoặc được bịa ra sẽ trở thành một vấn đề xác thực rõ ràng thay vì một cài đặt chiến dịch ngoài ý muốn.

Ví dụ CPA sau đây là một mẫu, không phải một chiến dịch sẵn sàng gửi. Hãy thay mọi giá trị COPY_FROM_REQUIREMENTS, ID ảnh, URL, payout, quốc gia, cap, và mô tả công khai bằng các giá trị đã được xem xét cho offer thực của bạn.

{
  "schema_version": "COPY_FROM_REQUIREMENTS",
  "external_id": "signup-campaign-us-001",
  "type": "CPA",
  "name": "US Account Signup",
  "creative": {
    "title": "Create Your Free Account",
    "description": "Register and confirm your email",
    "conversion_goal": "Create an account"
  },
  "tracking": {
    "url": "https://tracker.example.com/click?click_id={CLICK_ID}",
    "preview_url": "https://www.example.com/signup",
    "gaid_idfa_filler": false
  },
  "targeting": {
    "countries": ["US"],
    "device": "all_devices",
    "tools_only": false
  },
  "pricing": {
    "payout": "0.50",
    "daily_cap": 20,
    "currency": "USD"
  },
  "schedule": {
    "mode": "always",
    "start_time": "00:00",
    "end_time": "23:59",
    "timezone": "UTC"
  },
  "publisher_access": {
    "mode": "all",
    "publisher_ids": []
  },
  "launch_package": {
    "amount": "COPY_FROM_REQUIREMENTS"
  },
  "image_upload_id": "cimg_COPY_FROM_IMAGE_UPLOAD",
  "terms": {
    "version": "COPY_FROM_REQUIREMENTS",
    "accepted": true
  }
}

Quy tắc tracking quan trọng cho CPA và CPI

URL theo dõi phải chứa macro chính xác {CLICK_ID}. Tracker hoặc nền tảng affiliate của bạn phải lưu giá trị số mà CPAlead chèn vào đó và trả lại click ID đã lưu này cho postback advertiser của CPAlead sau khi chuyển đổi xảy ra. Không đặt URL postback của CPAlead trong URL theo dõi chiến dịch. Để có giải thích đầy đủ từ click đến postback, hãy dùng hướng dẫn public advertiser postback.

Chọn một lần trả tiền hoặc nhiều sự kiện có thưởng

CPA và CPI hỗ trợ conversion_mode với các giá trị single và events. Đọc conversion_modes và event_rules trong phần yêu cầu trước khi chọn. CPC trả tiền cho lượt nhấp và không hỗ trợ phần thưởng theo sự kiện.

Với một hành động được trả tiền, người tham gia nhận một khoản thanh toán chuyển đổi. Với nhiều sự kiện có thưởng, bạn đặt một khoản trả cố định bằng USD cho từng hành động. Ví dụ, trả $0.50 khi tạo tài khoản và $1.25 khi hoàn thành hướng dẫn. Tổng tối đa là $1.75 cho mỗi người tham gia; đây không phải là khoản trả thêm.

Với một yêu cầu CPA đầy đủ như ví dụ ở trên, hãy sử dụng các trường sự kiện và mức trả dưới đây. Giữ các trường chiến dịch bắt buộc khác. Với CPI, hãy chọn thêm nền tảng ứng dụng và phương thức theo dõi được hỗ trợ. Thay tất cả hành động, mức trả và lựa chọn nhắm mục tiêu trong ví dụ bằng các lựa chọn của bạn đã được xem xét.

{
  "conversion_mode": "events",
  "events": [
    {"id": 1, "name": "Create an account", "description": "Finish registration.", "payout": "0.50"},
    {"id": 2, "name": "Complete the tutorial", "description": "Finish all tutorial steps.", "payout": "1.25"}
  ],
  "pricing": {"currency": "USD", "payout": "1.75", "daily_cap": 20}
}

Một danh sách gồm 1–10 sự kiện. Mỗi sự kiện cần có tên và khoản trả lớn hơn không, với tối đa hai chữ số thập phân; hướng dẫn hoàn thành là tùy chọn. Có thể bỏ qua ID sự kiện mới để CPAlead tự gán. Giữ các ID dạng số được trả về để dùng cho các lần cập nhật và postback sau này. Khi ghi sự kiện, có thể bỏ qua pricing.payout; nếu cung cấp, giá trị này phải bằng tổng tiền trả cho tất cả sự kiện. creative.conversion_goal là tùy chọn với chiến dịch sự kiện và targeting.tools_only phải là false.

Mỗi sự kiện chỉ được trả tiền một lần cho mỗi người tham gia, theo bất kỳ thứ tự nào, trong vòng 30 ngày kể từ lượt nhấp ban đầu. Giới hạn hằng ngày tính người tham gia tại sự kiện được trả tiền đầu tiên của họ. Các sự kiện sau không được tính thêm lần nữa. Tạm dừng hoặc đạt giới hạn sẽ ngừng lưu lượng mới nhưng không hủy các phần thưởng còn chờ và đủ điều kiện. Hãy duy trì đủ tiền để trả các phần thưởng đó; những lượt hoàn thành đang chờ có thể vượt giới hạn lưu lượng của một ngày.

Theo dõi và cập nhật chiến dịch sự kiện

Với postback tiêu chuẩn, gửi ID postback của bạn, click_id gốc đã lưu và giá trị xác định phần thưởng đã hoàn thành. Thêm campaign_id để tăng bảo vệ; giá trị này phải khớp với chiến dịch của lượt nhấp ban đầu. Dùng URL được tạo cho tài khoản và không tự đặt ID.

Số dư thấp sẽ trả HTTP 503 với low_balance. Nạp tiền rồi thử lại cùng sự kiện sau thời gian Retry-After. Dùng Guided Test trước khi gửi lưu lượng.

Với hệ thống theo dõi tiêu chuẩn, Full Campaign API và Temporary AI Campaign Draft Access chấp nhận trường sự kiện tùy chọn postback_event_value khi trường này có trong event_rules.event_fields. Ví dụ, "postback_event_value": "tutorial_complete" thêm mã theo dõi cho phần thưởng đó. Tên sự kiện vẫn hoạt động. AppsFlyer tiếp tục dùng trường riêng appsflyer_event_name.

AppsFlyer CPI sử dụng thiết lập Integrated Partner của CPAlead. Không dán postback tiêu chuẩn dành cho nhà quảng cáo vào AppsFlyer. Ánh xạ từng ID sự kiện dạng số đã lưu làm mã định danh sự kiện của đối tác. Trường tùy chọn appsflyer_event_name phải khớp chính xác với tên SDK; các tên trùng nhau cần có ID đối tác để xác định phần thưởng. Chỉ một phần thưởng được dùng install và callback của nó phải gửi rõ event_type=install. Xem các mẫu riêng trong Postback Setup. Lưu chiến dịch qua API không cấu hình AppsFlyer.

PATCH có events sẽ thay toàn bộ danh sách; bỏ trường này sẽ giữ danh sách cũ. Giữ mọi ID sự kiện đã lưu, lấy ETag hiện tại và gửi If-Match. Sau khi có người tham gia thật hoặc có chuyển đổi, chế độ thanh toán, phương thức theo dõi, danh tính ứng dụng AppsFlyer và chi tiết phần thưởng vẫn bị khóa. Chỉ giá trị theo dõi tiêu chuẩn bổ sung được sửa; thay đổi này được ghi lại và không thay đổi phần thưởng. Sao chép chiến dịch để đổi phần thưởng. Chỉ các lượt nhấp Guided Test thì chưa làm khóa cấu hình sự kiện.

Chiến dịch sự kiện có thể chạy qua Offerwall V2, Publisher Offers API và liên kết trực tiếp. Offerwall V2 cần ID người dùng của nhà xuất bản ổn định trong subid. Người tham gia quay lại vẫn giữ lượt nhấp và thời hạn ban đầu. Offerwall cổ điển, locker và pixel theo dõi không hỗ trợ các chiến dịch sự kiện này.

Chuẩn bị chiến dịch sự kiện bằng AI hoặc nguồn cấp ưu đãi

Temporary AI Campaign Draft Access có thể chuẩn bị danh sách sự kiện đầy đủ để bạn xem lại trong biểu mẫu CPA/CPI thông thường. Quyền truy cập này không thể tạo chiến dịch đang chạy, cấu hình theo dõi, chấp nhận điều khoản hoặc gói khởi chạy, tải hình ảnh lên hay tiêu tiền. Liên kết riêng có hiệu lực trong bốn giờ. Trước khi nhà quảng cáo nạp tiền thành công, liên kết có thể lưu tối đa ba bản nháp chiến dịch; sau khi nạp tiền thành công, không còn giới hạn tổng số theo từng liên kết. Mỗi tài khoản có thể có tối đa 10 bản nháp chiến dịch chưa hoàn tất đang chờ, và các bản nháp chiến dịch chưa hoàn tất sẽ hết hạn sau bảy ngày.

Offer API Import có thể chuẩn bị danh sách từ events, event_payouts hoặc goals; ánh xạ tùy chỉnh hỗ trợ đường dẫn khác. ID dạng số hợp lệ của nguồn được giữ nguyên. Nguồn dùng văn bản hoặc tên cần giá trị theo dõi đã lưu và ID sự kiện dạng số do CPAlead cấp. Mỗi phần thưởng cần tên và khoản thanh toán USD cố định. Kiểm tra ID, giá trị theo dõi và toàn bộ danh sách phần thưởng trong bản xem trước. Nếu bản xem trước không chuẩn bị được cả danh sách, hãy sửa ánh xạ trước khi tiếp tục. Tải nguồn dữ liệu sẽ chuẩn bị biểu mẫu mới, không cập nhật chiến dịch hiện có.

Bước 4: Xác thực trước khi tạo

curl --config cpalead-auth.cfg \
  --request POST \
  --header "Content-Type: application/json" \
  --data-binary @campaign.json \
  "https://www.cpalead.com/api/v1/advertiser/campaigns/validate"

Validation trả về HTTP 200 với data.valid, một danh sách errors, và một danh sách warnings. Phản hồi 200 vẫn có thể chứa valid: false, vì vậy client phải kiểm tra giá trị đó thay vì coi riêng trạng thái HTTP là sự chấp thuận. Mỗi vấn đề sử dụng một đường dẫn JSON Pointer như /tracking/url, /pricing/payout, hoặc /image_upload_id. Một tác nhân AI nên chỉ sửa trường được chỉ ra, xác thực lại, và hiển thị JSON cuối cùng cho chủ tài khoản trước khi yêu cầu quyền create.

Một phản hồi hợp lệ có nghĩa là payload vượt qua validation hiện tại và kiểm tra trước khi lưu. Nó không phải là lời hứa về việc được phê duyệt, kích hoạt, traffic, conversions, hoặc đủ điều kiện trong tương lai. Các kiểm tra review, funding, quyền truy cập tài khoản, holds, lịch, cap, và trạng thái theo thời gian thực vẫn áp dụng cho các thao tác ghi và hành động vòng đời.

Bước 5: Tạo an toàn với idempotency

curl --config cpalead-auth.cfg \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: create-signup-campaign-us-001" \
  --data-binary @campaign.json \
  "https://www.cpalead.com/api/v1/advertiser/campaigns"

Create, start, và pause yêu cầu một Idempotency-Key chứa từ 8 đến 200 ký tự ASCII hiển thị. Dùng một key mới cho mỗi hành động dự định. Nếu kết nối thất bại và bạn không biết liệu hành động đã hoàn tất hay chưa, hãy thử lại cùng hành động y hệt với cùng key. CPAlead có thể phát lại phản hồi đã hoàn tất thay vì tạo hoặc tính phí hai lần.

• Cùng key và cùng mục đích: Phản hồi đã hoàn tất có thể được phát lại với meta.idempotent_replay=true.
• Cùng key nhưng chi tiết thay đổi: API trả về xung đột idempotency.
• Cùng external ID nhưng chi tiết thay đổi: API cũng trả về xung đột.
• Yêu cầu trước đó vẫn đang xử lý: Hãy chờ khoảng thời gian được báo cáo, rồi thử lại cùng mục đích với cùng key.

external_id tùy chọn là tham chiếu ổn định riêng của bạn cho thao tác create. Nó có thể giúp đối soát dễ hơn, nhưng không được tái sử dụng cho một chiến dịch dự định khác.

Ba chiến dịch trước khi nạp tiền

Một tài khoản advertiser có thể tạo tối đa ba chiến dịch self-serve CPA, CPI, hoặc CPC tổng cộng trước khoản nạp tiền advertiser thành công đầu tiên. Các chiến dịch bị tạm dừng, từ chối, và lưu trữ vẫn được tính vì việc tạo và lưu trữ các chiến dịch bỏ đi không được phép vượt qua giới hạn. Sau một khoản nạp tiền thành công, giới hạn tạo cụ thể này không còn áp dụng nữa; các quy tắc review, số dư, payout, ngân sách, và kích hoạt thông thường vẫn áp dụng.

Đọc và lọc chiến dịch

curl --config cpalead-auth.cfg \
  "https://www.cpalead.com/api/v1/advertiser/campaigns?type=CPA&state=paused&page=1&per_page=25"

Điểm cuối danh sách hỗ trợ loại chiến dịch, trạng thái công khai, dấu thời gian updated_since, trang, và bộ lọc per-page. Phân trang mặc định là 25 chiến dịch và cho phép tối đa 100 mỗi trang. Các lựa chọn trạng thái công khai là active, paused, pending_review, paused_for_funding, cap_reached, outside_schedule, denied, archived, và unavailable. Các chiến dịch đã lưu trữ chỉ xuất hiện khi bạn lọc rõ ràng state=archived.

Một tài nguyên chiến dịch bao gồm ID, external ID tùy chọn, phiên bản, loại, tên, creative, tracking, targeting, pricing, schedule, thiết lập quyền truy cập publisher, URL ảnh, dấu thời gian, và trạng thái công khai. Trạng thái cũng bao gồm các gợi ý review, desired-delivery, delivery-reason, và capability. Các gợi ý capability chỉ mang tính khuyến nghị: hãy truy xuất chiến dịch mới nhất và xử lý phản hồi thao tác thực tế vì điều kiện tài khoản, funding, review, hold, và lịch có thể thay đổi.

Cập nhật với bảo vệ phiên bản ETag

Các lần chỉnh sửa chiến dịch dùng cơ chế đồng thời lạc quan. Trước tiên hãy truy xuất chiến dịch và lưu chính xác header phản hồi ETag có dấu ngoặc kép. Sau đó gửi giá trị đó trong If-Match cùng yêu cầu PATCH. Điều này ngăn một trình duyệt, tác nhân, hoặc tích hợp ghi đè âm thầm lên một thay đổi mới hơn được thực hiện ở nơi khác.

# First retrieve the latest campaign and its ETag.
curl --config cpalead-auth.cfg \
  --dump-header campaign-headers.txt \
  "https://www.cpalead.com/api/v1/advertiser/campaigns/12345"

# Then send a reviewed partial update with that exact quoted ETag.
curl --config cpalead-auth.cfg \
  --request PATCH \
  --header "Content-Type: application/json" \
  --header 'If-Match: "COPY_THE_LATEST_ETAG"' \
  --data-binary '{"creative":{"description":"Updated public description"}}' \
  "https://www.cpalead.com/api/v1/advertiser/campaigns/12345"

• Không có If-Match: API trả về HTTP 428.
• If-Match lỗi thời: API trả về HTTP 412 với metadata phiên bản hiện tại.
• Sau 412: Lấy lại chiến dịch, so sánh thay đổi, xin phê duyệt, và thử lại với ETag mới.
• Sau kết quả mạng không rõ ràng: Lấy lại chiến dịch trước khi gửi một cập nhật khác.

PATCH chỉ chấp nhận các trường chiến dịch công khai. Nó hợp nhất đối tượng một phần được cung cấp với chiến dịch hiện tại và xác thực kết quả đầy đủ. Một số chỉnh sửa có thể yêu cầu review khác hoặc thay đổi phân phối, vì vậy hãy đọc trạng thái phản hồi mỗi lần.

Start và pause là các hành động rõ ràng, không có body

# Start an eligible campaign.
curl --config cpalead-auth.cfg \
  --request POST \
  --header "Idempotency-Key: start-campaign-12345-001" \
  "https://www.cpalead.com/api/v1/advertiser/campaigns/12345/actions/start"

# Pause an eligible campaign.
curl --config cpalead-auth.cfg \
  --request POST \
  --header "Idempotency-Key: pause-campaign-12345-001" \
  "https://www.cpalead.com/api/v1/advertiser/campaigns/12345/actions/pause"

Đừng gửi body JSON — thậm chí cả {} — cho start hoặc pause. Trước khi bắt đầu, hãy xác nhận chiến dịch, số dư, payout hoặc bid, hiệu ứng của launch package, quốc gia, thiết bị, lịch, cap hoặc ngân sách, landing page, và tracking. Sau phản hồi, hãy kiểm tra trạng thái công khai; một chiến dịch có thể được bật nhưng nằm ngoài lịch hằng ngày, bị tạm dừng vì funding, đạt cap, hoặc không thể phân phối vì lý do khác.

Các trạng thái HTTP và lỗi mà một tích hợp nên hiểu

Tự động hóa dựa trên trạng thái HTTP và error.code ổn định, không chỉ dựa vào cách diễn đạt thông báo. Chi tiết xác thực bao gồm đường dẫn, mã, và thông điệp tiếng Anh đơn giản. Hãy bao gồm request_id của phản hồi khi liên hệ hỗ trợ.

Giới hạn tần suất và thử lại có trách nhiệm

Các yêu cầu Campaign API và xác thực đều bị giới hạn tần suất để bảo vệ advertiser và dịch vụ. Giới hạn có thể thay đổi, vì vậy hãy dùng lược đồ OpenAPI trực tiếp và các header phản hồi thay vì hard-code số lượng yêu cầu. Khi API trả về HTTP 429, hãy đợi Retry-After thay vì lặp lại yêu cầu ngay lập tức. Hãy dùng phân trang, updated_since, và bộ nhớ đệm cục bộ cho các yêu cầu công khai không thay đổi để tránh gọi không cần thiết.

Lời nhắc dành cho tác nhân AI có khả năng dùng API hoặc giải pháp tích hợp

Lời nhắc này giả định ứng dụng khách có thể đính kèm bearer token riêng tư vào các yêu cầu HTTPS đã xác thực. Trước tiên, hãy chia sẻ hướng dẫn và OpenAPI URL, sau đó cấu hình token trong phần cài đặt bí mật của nền tảng ứng dụng khách. Không chèn token thật vào lời nhắc công khai này. Nếu một cuộc trò chuyện AI thông thường cho biết nó không thể gửi yêu cầu đã xác thực, hãy thu hồi token không cần thiết và dùng Temporary AI Campaign Draft Access thay thế.

Read this CPAlead Campaign API guide and the public OpenAPI schema.

Do not ask me to paste a bearer token into chat. Use only the token configured
privately in the integration. Begin with read and validate operations.

1. Ask whether I am creating CPA, CPI, or CPC.
2. Call the matching requirements endpoint.
3. Ask me for every missing business value and explain any financial,
   tracking, targeting, schedule, review, or delivery effect.
4. Draft strict campaign JSON and validate it.
5. Repair validation errors by their JSON Pointer paths.
6. Show me the final normalized intent and ask for confirmation before
   uploading, creating, updating, starting, or pausing anything.
7. Use a unique idempotency key for create, start, and pause.
8. Retrieve the latest campaign and ETag before an update.
9. After every write, report the campaign ID, public state, request ID,
   warnings, and recommended next step.
10. Never attempt archive or delete because those operations are not in
    the Campaign API.

Danh sách kiểm tra bảo mật cho AI, MCP, plugin, và code

• Ít đặc quyền nhất: Bắt đầu bằng đọc và xác thực. Chỉ thêm một quyền ghi khi cần.
• Hết hạn ngắn: Ưu tiên tùy chọn 48 giờ cho một tác vụ thiết lập AI một lần.
• Token riêng biệt: Cấp cho mỗi tác nhân hoặc tích hợp token có tên riêng của nó.
• Lưu trữ riêng tư: Giữ token trong phần cài đặt bí mật, không phải URL, prompt, log, analytics, ảnh chụp màn hình, hoặc kho lưu trữ.
• Xác nhận của con người: Yêu cầu tóm tắt trước khi create, update, start, hoặc pause.
• Thử lại an toàn: Giữ nguyên cùng key và payload sau một kết quả idempotent không chắc chắn.
• Kiểm tra phiên bản: Không bao giờ cập nhật mà không truy xuất ETag mới nhất.
• Kiểm tra phản hồi: Đọc trạng thái công khai và request ID sau mỗi lần ghi.
• Thu hồi kịp thời: Xóa quyền truy cập khỏi trang Advertising API khi công việc xong hoặc token có thể đã bị lộ.

Câu hỏi thường gặp

Tôi có thể dùng Full Campaign API trong ChatGPT thông thường không?

Chỉ khi ChatGPT có GPT Action đã được cấu hình hoặc một giải pháp tích hợp đã xác thực khác có thể gửi bearer token trong Authorization header. Một cuộc trò chuyện thông thường thường không thể làm điều đó. Thay vào đó, hãy dùng Temporary AI Campaign Draft Access. Quyền này chỉ có thể chuẩn bị và lưu các bản nháp chiến dịch chưa hoạt động; bạn xem lại và hoàn tất chúng trong CPAlead.

Tôi tìm API key CPAlead của mình ở đâu?

Đối với Campaign API, thông tin xác thực được gọi là token Campaign API. Đăng nhập và mở Advertising → Setup → API, rồi dùng Create a token. Hãy sao chép token ngay lập tức vì CPAlead chỉ hiển thị giá trị đầy đủ một lần.

API có thể tạo chiến dịch CPA, CPI, và CPC không?

Có. Mỗi loại có một cấu trúc JSON nghiêm ngặt nhưng khác nhau. Hãy lấy yêu cầu cho loại đó trước khi xây dựng.

Tôi có thể xác thực mà không cho AI tạo bất cứ thứ gì không?

Có. Chỉ cấp cho token campaigns:validate, và tùy chọn campaigns:read. Yêu cầu và xác thực không cần quyền create.

Một phản hồi hợp lệ có nghĩa là chiến dịch đã được duyệt không?

Không. Nó có nghĩa là payload hiện tại vượt qua xác thực và kiểm tra trước khi lưu. Review, funding, quyền truy cập tài khoản, holds, caps, lịch, và trạng thái thời gian thực vẫn áp dụng.

Create có thể khởi chạy chiến dịch ngay lập tức không?

Nó có thể, tùy theo tài khoản và chiến dịch. Nó cũng có thể đi vào review. Luôn kiểm tra trạng thái công khai trả về. Việc kích hoạt CPA hoặc CPI cũng có thể tính phí một launch package đã chọn nhưng chưa thanh toán.

Tôi có thể tải ảnh từ URL từ xa không?

Không. Tải tệp ảnh thông qua POST /images. CPAlead trả về một ID ảnh tạm thời, chỉ dùng một lần.

Tôi có thể tạo nhiều offer cùng lúc không?

Không có thao tác bulk-create. Hãy xác thực và tạo từng chiến dịch một cho mỗi yêu cầu, dùng external ID và idempotency key riêng biệt, và tôn trọng giới hạn tần suất cùng các quy tắc tạo tài khoản.

API có thể lưu trữ hoặc xóa một chiến dịch không?

Không. API công khai hiện tại có thể bắt đầu và tạm dừng các chiến dịch đủ điều kiện nhưng không cung cấp archive hoặc delete. Hãy dùng dashboard advertiser để lưu trữ.

Tại sao bản cập nhật của tôi nhận HTTP 412?

Chiến dịch đã thay đổi sau khi bạn truy xuất nó. Hãy lấy lại, xem dữ liệu mới nhất, hợp nhất thay đổi bạn định thực hiện, và thử lại với ETag mới.

Tại sao create trả về HTTP 409?

Hãy đọc mã lỗi ổn định. Các lý do công khai có thể gồm dùng lại idempotency key hoặc external ID với dữ liệu khác, một yêu cầu trước đó vẫn đang xử lý, giới hạn ba chiến dịch trước khi nạp tiền, các hạn chế funding hoặc tài khoản, một hold, hoặc xung đột trạng thái.

Ứng dụng của tôi có nên sao chép các giới hạn trường từ bài viết này không?

Không. Bài viết này giải thích quy trình làm việc. Ứng dụng của bạn nên đọc yêu cầu trực tiếp và lược đồ OpenAPI để các giá trị hiện tại luôn là nguồn thẩm quyền.

Bảng thông tin Campaign API thân thiện với máy

Bắt đầu với đọc và xác thực

Campaign API được thiết kế để một advertiser có thể bắt đầu một cách thận trọng. Hãy đưa cho một tác nhân đáng tin cậy hướng dẫn công khai và lược đồ, cấp quyền đọc và xác thực, và để nó chuẩn bị yêu cầu mà không thay đổi tài khoản. Khi JSON đã đúng và chủ sở hữu hiểu các tác động có thể có về review, phân phối, và tài chính, chỉ thêm quyền ghi cần thiết cho hành động tiếp theo đã được xác nhận.

Mở Campaign API trong Advertiser API Center để tạo token, hoặc mở lược đồ OpenAPI công khai của Campaign API để kiểm tra hợp đồng hiện tại. Tài liệu Publisher API là riêng biệt và bao gồm việc publisher truy xuất offers và báo cáo. Nếu một phản hồi không rõ ràng, hãy giữ token ở chế độ riêng tư và liên hệ Advertiser Support với request ID công khai và campaign ID.

Bạn có nhận thấy lỗi hoặc một khía cạnh của bài viết này cần được sửa chữa không? Vui lòng cung cấp liên kết bài viết và liên hệ với chúng tôi. Chúng tôi đánh giá cao phản hồi của bạn và sẽ xử lý vấn đề một cách nhanh chóng.