CPAlead Full Campaign API: অফার তৈরি ও পরিচালনা করুন

CPAlead-এর Full Campaign API verified self-serve advertiser-কে code, API-capable AI agent, MCP server, GPT Action অথবা plugin ব্যবহার করে CPA, CPI এবং CPC campaign নিয়ে কাজ করতে দেয়। দেওয়া permission অনুযায়ী authorized client বর্তমান requirements পড়তে, সম্পূর্ণ campaign সংরক্ষণের আগে validate করতে, creative upload করতে, campaign তৈরি করতে, campaign-এর list ও নির্দিষ্ট campaign retrieve করতে, version protection দিয়ে campaign edit করতে এবং eligible campaign স্পষ্টভাবে start বা pause করতে পারে।

এটি normal advertiser dashboard-এর automation companion। যদি আপনি প্রথমে campaign type, tracking, targeting, payout, cap, funding, review, এবং launch-এর field-by-field ব্যাখ্যা চান, তাহলে পড়ুন 2026-এ CPAlead-এ কীভাবে বিজ্ঞাপন দেবেন: আপনার প্রথম Offer যোগ ও চালু করুন। এই articleটি ব্যবহার করুন যখন আপনি সেই setup-কে structured JSON এবং controlled API actions হিসেবে প্রকাশ করতে প্রস্তুত।

Full Campaign API কী করতে পারে

APIটি বর্তমানে না archive, delete, bulk-create, বা generic toggle operation দেয়। Archive বা delete কাজ dashboard workflow-তেই থাকে। Start এবং pause আলাদা action, যাতে delivery পরিবর্তন করার আগে ব্যক্তি বা AI client স্পষ্ট confirmation চাইতে পারে।

Temporary AI Campaign Draft Access, Full Campaign API এবং Offer API Import-এর মধ্যে বেছে নিন

• Temporary AI Campaign Draft Access: সাধারণ ChatGPT এবং একই ধরনের AI চ্যাটের জন্য। প্রথম সফল advertiser deposit-এর আগে, চার ঘণ্টা কার্যকর private link সর্বোচ্চ তিনটি inactive campaign draft validate ও save করতে পারে। সফল advertiser deposit-এর পরে, link-এ মোট campaign draft-এর কোনো সীমা থাকে না। প্রতিটি account-এ একই সময়ে সর্বোচ্চ 10টি অসম্পূর্ণ campaign draft pending থাকতে পারে। এটি বর্তমান campaign দেখতে বা পরিচালনা করতে, upload করতে, terms বা package মেনে নিতে, funds খরচ করতে অথবা submit, start, pause বা activate করতে পারে না। Temporary AI Campaign Draft Access খুলুন।
• Full Campaign API: এমন API-capable agent, GPT Action, MCP server, plugin অথবা integration-এর জন্য, যা bearer token সুরক্ষিত রাখতে পারে। দেওয়া scopes campaign validate, upload, create, read, edit, start ও pause করতে পারে। Full Campaign API খুলুন।
• Offer API Import: এটি advertiser dashboard-এর একটি আলাদা workflow, যা compatible external feed থেকে offer আনে এবং তার field-গুলো CPAlead-এ map করে। Offer API Import খুলুন।

সাধারণ AI চ্যাট যখন নতুন offer প্রস্তুত করতে সাহায্য করে, তখন সুরক্ষিত campaign-draft option ব্যবহার করুন। Authenticated client-এর structured campaign-management abilities দরকার হলে Full Campaign API ব্যবহার করুন। CPAlead-কে compatible feed আনতে হলে Offer API Import ব্যবহার করুন। কোনো tool-কে তার কাজের প্রয়োজনের চেয়ে বেশি access দেবেন না।

Campaign API token তৈরি করুন

1. একটি verified self-serve advertiser account-এ sign in করুন।
2. Setup → API, তারপর Campaign API নির্বাচন করুন খুলুন।
3. Token-টিকে একটি চেনা যায় এমন নাম দিন, যেমন “Campaign validator” বা “My MCP agent.”
4. একটি expiration নির্বাচন করুন। AI setup-এর জন্য 48-hour option সুপারিশ করা হয়; 30-day, 90-day, এবং 365-day option-ও উপলভ্য।
5. শুধু client-এর প্রয়োজনীয় permission নির্বাচন করুন।
6. Token তৈরি করুন এবং সঙ্গে সঙ্গে copy করুন। Page reload হওয়ার পর CPAlead আর complete token দেখাতে পারে না।
7. এটিকে trusted client-এর secret configuration-এ সংরক্ষণ করুন এবং কাজ শেষ হলে revoke করুন।

একজন advertiser-এর সর্বোচ্চ 10টি active Campaign API token থাকতে পারে। আলাদা integration-এর জন্য আলাদা token ব্যবহার করুন, যাতে permission সীমিত রাখা, ব্যবহার পর্যালোচনা করা, এবং এক integration বন্ধ করেও অন্যটিকে না থামিয়ে revoke করা যায়।

আপনার Campaign API token কোথায় তৈরি করবেন

একটি Campaign API token হল private API credential যা Authorization header-এ পাঠানো হয়। এটি আপনার CPAlead password নয়, এবং এটি CPAlead dashboard-এ sign in করার জন্য ব্যবহার করা যায় না। Sign in করার পর Setup → API, Campaign API নির্বাচন করুন খুলুন, এবং Create a token form ব্যবহার করুন।

Base URL, authentication, এবং response format

Authenticated request HTTP authorization header-এ token একবার পাঠায়। এটি কখনও URL বা query string-এ রাখবেন না।

Authorization: Bearer YOUR_TOKEN
Accept: application/json

নিচের curl উদাহরণগুলোর জন্য আরও নিরাপদ setup হলো authorization header-টি একটি local curl configuration file-এ সংরক্ষণ করা, যা source control থেকে বাদ থাকবে এবং কেবল আপনি পড়তে পারবেন:

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

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

একটি সফল response-এ data object বা list-এর সাথে meta থাকে। Metadata-তে একটি request_id এবং বর্তমান schema version থাকে, এবং pagination, resource version, বা idempotent-replay flag-ও থাকতে পারে। একটি error response-এ error object-এর সাথে meta থাকে। support-এর সাথে সমস্যা সমাধানের সময় public request_id সংরক্ষণ করুন, কিন্তু কখনও support-কে আপনার bearer token পাঠাবেন না।

Step 1: Live requirements পড়ুন

Requirements হলো account এখন কী submit করতে পারে তার source of truth। এতে বর্তমান schema এবং terms version, account creation eligibility, supported countries এবং devices, field limits, campaign-type rules, pricing ranges, schedules, launch packages, tracking requirements, image rules, এবং recommended workflow অন্তর্ভুক্ত থাকে।

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

Response সীমিত করতে type=CPA, type=CPI, বা type=CPC ব্যবহার করুন। পুরনো উদাহরণ থেকে schema version, terms version, payout limit, bid, budget, launch package, country, device, বা minimum app version hard-code করবেন না। Server যদি জানায় যে কোনো value বা version out of date, তাহলে requirements আবার fetch করুন।

তিনটি campaign type

• CPA: একটি কাজের জন্য বা একাধিক ইভেন্টের পুরস্কার হিসেবে অর্থ দেয়। ট্র্যাকিং URL-এ {CLICK_ID} থাকতে হবে। একটি প্রিভিউ URL, দৈনিক সীমা এবং লঞ্চ প্যাকেজ তৈরির অনুরোধের অংশ। একবার অর্থ দেওয়ার ক্যাম্পেইনে একটি কনভার্সন লক্ষ্য থাকা আবশ্যক; ইভেন্টভিত্তিক ক্যাম্পেইন তার ইভেন্টের তালিকায় প্রতিটি পুরস্কারযোগ্য কাজ নির্ধারণ করে।
• CPI: একটি ইনস্টল বা অ্যাপের কাজের জন্য, অথবা একাধিক ইভেন্টের পুরস্কার হিসেবে অর্থ দেয়। এতে {CLICK_ID} ব্যবহার করা হয় এবং অ্যাপসংক্রান্ত বিকল্প যোগ হয়, যেমন ডিভাইসের প্ল্যাটফর্ম, ট্র্যাকিং পদ্ধতি, সমর্থিত অপারেটিং সিস্টেমের সংস্করণ এবং প্রক্সি ব্যবস্থাপনা। ইভেন্টভিত্তিক ক্যাম্পেইনে ইনস্টলের জন্য অর্থ দিতে চাইলে স্পষ্টভাবে একটি ইনস্টল ইভেন্ট যোগ করুন।
• CPC: valid click-এর জন্য pay করে। এটি conversion payout, daily cap, এবং launch package-এর বদলে bid এবং daily budget ব্যবহার করে।

ক্যাম্পেইন API-এর সব অর্থের পরিমাণ USD-এ দেওয়া হয় এবং API-এর সময়সূচি UTC অনুসরণ করে। CPA ও CPI-এর ক্ষেত্রে $10.00-এর কম পেমেন্টের জন্য দৈনিক সীমা কমপক্ষে 20 হতে হবে। $10.00 বা তার বেশি পেমেন্ট হলে দৈনিক সীমা 5 পর্যন্ত কম রাখা যায়। ইভেন্টভিত্তিক ক্যাম্পেইনে এই সর্বনিম্ন সীমার নিয়মগুলোর জন্য সব ইভেন্টের পেমেন্টের যোগফল ব্যবহার করুন। মূল্য এবং সীমা বেছে নেওয়ার আগে বর্তমান প্রয়োজনীয়তাগুলো পড়ুন।

Step 2: Campaign image upload করুন

Create request remote image URL গ্রহণ করে না। প্রথমে fileটি multipart form data হিসেবে upload করুন, তারপর returned temporary image ID-টি image_upload_id-এ রাখুন।

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

• Accepted sources: JPG, JPEG, PNG, GIF, BMP, এবং WebP।
• Maximum file size: 2 MiB।
• Source width and height: প্রতিটি 200 থেকে 4096 pixel-এর মধ্যে হতে হবে।
• Stored result: non-animated, metadata-free 200×200 WebP crop।
• Unused upload lifetime: 24 hours।
• Outstanding-upload limit: সর্বোচ্চ 25 current unused image upload।
• Use: একটি campaign create বা image update। অন্য campaign-এর জন্য আবার upload করুন।

Validation check করতে পারে যে একটি image ID আপনার account-এর এবং তা consume না করেই ব্যবহারযোগ্য আছে। Successful campaign write এটি consume করে। একই completed create-কে একই idempotency key দিয়ে আবার চালালে stored result ফেরে; consume হওয়া image দিয়ে দ্বিতীয় campaign তৈরি হয় না।

Step 3: Complete campaign JSON তৈরি করুন

APIটি strict JSON object ব্যবহার করে। Unknown field silently ignore না হয়ে reject হয়। ফলে AI integration আরও নিরাপদ হয়: misspelled বা invented property accidental campaign setting না হয়ে visible validation issue হয়ে যায়।

নিচের CPA exampleটি একটি template, submit করার জন্য প্রস্তুত campaign নয়। আপনার real offer-এর জন্য reviewed value দিয়ে প্রতিটি COPY_FROM_REQUIREMENTS value, image ID, URL, payout, country, cap, এবং public description replace করুন।

{
  "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
  }
}

গুরুত্বপূর্ণ CPA এবং CPI tracking rule

Tracking URL-এ অবশ্যই exact {CLICK_ID} macro থাকতে হবে। আপনার tracker বা affiliate platform-কে সেখানে CPAlead যে numeric value insert করে তা save করতে হবে এবং conversion-এর পরে সেই saved click ID CPAlead advertiser postback-এ ফেরত দিতে হবে। Campaign tracking URL-এ CPAlead-এর postback URL রাখবেন না। পুরো click-to-postback ব্যাখ্যার জন্য public advertiser postback guide ব্যবহার করুন।

একটি পেমেন্ট বা একাধিক ইভেন্টের পুরস্কার বেছে নিন

CPA ও CPI-তে conversion_mode-এর মান হিসেবে single এবং events সমর্থিত। বেছে নেওয়ার আগে প্রয়োজনীয়তা থেকে conversion_modes এবং event_rules পড়ুন। CPC ক্লিকের জন্য অর্থ দেয় এবং ইভেন্টের পুরস্কার সমর্থন করে না।

একটি অর্থপ্রদানের উপযুক্ত কাজের ক্ষেত্রে অংশগ্রহণকারী একটি কনভার্সন পেমেন্ট পান। একাধিক ইভেন্টের পুরস্কারের ক্ষেত্রে আপনি প্রতিটি কাজের জন্য USD-এ আলাদা নির্দিষ্ট পেমেন্ট ঠিক করেন। যেমন, অ্যাকাউন্ট তৈরির জন্য $0.50 এবং টিউটোরিয়াল শেষ করার জন্য $1.25 দিতে পারেন। অংশগ্রহণকারীপ্রতি সর্বোচ্চ মোট পরিমাণ $1.75; এটি অতিরিক্ত কোনো পেমেন্ট নয়।

ওপরের উদাহরণের মতো সম্পূর্ণ CPA অনুরোধের জন্য এই ইভেন্ট ফিল্ড ও মূল্য ব্যবহার করুন। ক্যাম্পেইনের অন্য আবশ্যক ফিল্ডগুলো রাখুন। CPI-এর জন্য একটি সমর্থিত অ্যাপ প্ল্যাটফর্ম ও ট্র্যাকিং পদ্ধতিও বেছে নিন। উদাহরণের সব কাজ, মূল্য এবং টার্গেটিংয়ের জায়গায় আপনার নিজের যাচাই করা পছন্দগুলো দিন।

{
  "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}
}

একটি পরিকল্পনায় 1–10টি ইভেন্ট থাকে। প্রতিটিতে একটি নাম এবং সর্বোচ্চ দুই দশমিক স্থানসহ শূন্যের বেশি পেমেন্ট থাকতে হবে; কাজ সম্পন্ন করার নির্দেশনা ঐচ্ছিক। নতুন ইভেন্টের ID না দিলেও চলে, সেক্ষেত্রে CPAlead সেগুলো নির্ধারণ করবে। পরবর্তী আপডেট ও পোস্টব্যাকের জন্য ফেরত পাওয়া সংখ্যাসূচক ID-গুলো রাখুন। ইভেন্ট সংরক্ষণের সময় pricing.payout না দিলেও চলে; দিলে তা সব ইভেন্টের পেমেন্টের যোগফলের সমান হতে হবে। creative.conversion_goal ইভেন্টভিত্তিক ক্যাম্পেইনের জন্য ঐচ্ছিক এবং targeting.tools_only-এর মান false হতে হবে।

মূল ক্লিকের 30 দিনের মধ্যে, যেকোনো ক্রমে, প্রতিটি ইভেন্টের জন্য প্রত্যেক অংশগ্রহণকারীকে একবার অর্থ দেওয়া যায়। অংশগ্রহণকারীর প্রথম অর্থপ্রদত্ত ইভেন্টের সময় তাঁকে দৈনিক সীমায় গণনা করা হয়। পরের ইভেন্টগুলো আবার গণনা করা হয় না। ক্যাম্পেইন পজ করলে বা সীমায় পৌঁছালে নতুন ট্রাফিক বন্ধ হয়, কিন্তু বকেয়া উপযুক্ত পুরস্কার বাতিল হয় না। সেগুলোর জন্য পর্যাপ্ত অর্থ রাখুন; অপেক্ষমাণ কাজ সম্পন্ন হওয়ার সংখ্যা এক দিনের ট্রাফিক সীমা ছাড়িয়ে যেতে পারে।

ইভেন্টভিত্তিক ক্যাম্পেইন ট্র্যাক ও আপডেট করুন

স্ট্যান্ডার্ড পোস্টব্যাকে আপনার নিজের পোস্টব্যাক ID, সেভ করা আসল click_id এবং সম্পন্ন পুরস্কারটি চিহ্নিত করার মান পাঠান। বাড়তি সুরক্ষার জন্য campaign_id যোগ করুন; এটি আসল ক্লিকের ক্যাম্পেইনের সঙ্গে মিলতে হবে। অ্যাকাউন্টের জন্য তৈরি URL ব্যবহার করুন এবং কখনো নিজের মতো ID বানাবেন না।

ব্যালেন্স কম হলে HTTP 503-এর সঙ্গে low_balance আসে। টাকা যোগ করে Retry-After-এ দেওয়া সময়ের পর একই ইভেন্ট আবার পাঠান। ট্র্যাফিক পাঠানোর আগে Guided Test ব্যবহার করুন।

স্ট্যান্ডার্ড ট্র্যাকারের জন্য Full Campaign API ও Temporary AI Campaign Draft Access ঐচ্ছিক ইভেন্ট ফিল্ড postback_event_value গ্রহণ করে, যখন এটি event_rules.event_fields-এ থাকে। যেমন, "postback_event_value": "tutorial_complete" ওই পুরস্কারের জন্য একটি ট্র্যাকার কোড যোগ করে। ইভেন্টের নামও কাজ করতে থাকে। AppsFlyer-এর আলাদা appsflyer_event_name ফিল্ড বহাল থাকে।

AppsFlyer CPI-তে CPAlead-এর ইন্টিগ্রেটেড পার্টনার সেটআপ ব্যবহার করা হয়। বিজ্ঞাপনদাতার সাধারণ পোস্টব্যাক AppsFlyer-এ পেস্ট করবেন না। সংরক্ষিত প্রতিটি সংখ্যাসূচক ইভেন্ট ID পার্টনারের ইভেন্ট শনাক্তকারী হিসেবে ম্যাপ করুন। ঐচ্ছিক appsflyer_event_name-কে SDK-এর নামের সঙ্গে হুবহু মিলতে হবে; একই নাম বারবার থাকলে পুরস্কার শনাক্ত করতে পার্টনার ID প্রয়োজন। কেবল একটি পুরস্কারে install ব্যবহার করা যায় এবং সেটির কলব্যাকে স্পষ্টভাবে event_type=install পাঠাতে হবে। পোস্টব্যাক সেটআপে এ জন্য নির্দিষ্ট টেমপ্লেটগুলো দেখুন। API দিয়ে ক্যাম্পেইন সংরক্ষণ করলে AppsFlyer কনফিগার হয়ে যায় না।

events থাকা PATCH পুরো তালিকা বদলে দেয়; এটি না পাঠালে তালিকা আগের মতো থাকে। প্রতিটি সেভ করা ইভেন্ট ID রাখুন, বর্তমান ETag নিন এবং If-Match পাঠান। আসল অংশগ্রহণ বা লিডের পর পেমেন্টের ধরন, ট্র্যাকিং পদ্ধতি, AppsFlyer অ্যাপের পরিচয় ও পুরস্কারের তথ্য লক থাকে। শুধু অতিরিক্ত স্ট্যান্ডার্ড ট্র্যাকার ভ্যালু সংশোধন করা যায়; সেই পরিবর্তন রেকর্ড হয় এবং পুরস্কার বদলায় না। পুরস্কার বদলাতে ক্যাম্পেইন কপি করুন। শুধু Guided Test-এর ক্লিক ইভেন্ট সেটআপ লক করে না।

ইভেন্টভিত্তিক ক্যাম্পেইন Offerwall V2, পাবলিশার অফারস API এবং সরাসরি লিংকের মাধ্যমে চালানো যায়। Offerwall V2-এর জন্য subid-এ পাবলিশারের একটি স্থায়ী ব্যবহারকারী ID প্রয়োজন। ফিরে আসা অংশগ্রহণকারীদের মূল ক্লিক ও শেষ সময়সীমা বহাল থাকে। প্রচলিত অফারওয়াল, লকার এবং ট্র্যাকিং পিক্সেল এসব ইভেন্টভিত্তিক ক্যাম্পেইন সমর্থন করে না।

AI বা অফার ফিড দিয়ে ইভেন্টভিত্তিক ক্যাম্পেইন প্রস্তুত করুন

AI ক্যাম্পেইন খসড়ার সাময়িক অ্যাক্সেস সাধারণ CPA/CPI ফর্মে পর্যালোচনার জন্য সম্পূর্ণ ইভেন্ট পরিকল্পনা তৈরি করতে পারে। এটি সক্রিয় ক্যাম্পেইন তৈরি, ট্র্যাকিং কনফিগার, শর্ত বা লঞ্চ প্যাকেজ গ্রহণ, ছবি আপলোড অথবা অর্থ খরচ করতে পারে না। একটি ব্যক্তিগত লিংক চার ঘণ্টা কার্যকর থাকে। বিজ্ঞাপনদাতার সফল ডিপোজিটের আগে এতে সর্বোচ্চ তিনটি ক্যাম্পেইন খসড়া সংরক্ষণ করা যায়; সফল ডিপোজিটের পরে প্রতিটি লিংকের জন্য মোট সংখ্যার সীমা থাকে না। প্রতিটি অ্যাকাউন্টে সর্বোচ্চ 10টি অসম্পূর্ণ ক্যাম্পেইন খসড়া অপেক্ষমাণ থাকতে পারে এবং অসম্পূর্ণ খসড়ার মেয়াদ সাত দিন পরে শেষ হয়।

Offer API Import, events, event_payouts বা goals থেকে ইভেন্ট তালিকা তৈরি করতে পারে; কাস্টম ম্যাপিং অন্য পাথ সমর্থন করে। উৎসের বৈধ সংখ্যাসূচক ID রাখা হয়। টেক্সট বা নামভিত্তিক উৎসের জন্য সেভ করা ট্র্যাকার ভ্যালু ও CPAlead-এর দেওয়া সংখ্যাসূচক ইভেন্ট ID দরকার। প্রতিটি পুরস্কারে নাম ও USD-তে নির্দিষ্ট পেমেন্ট থাকতে হবে। প্রিভিউতে ID, ট্র্যাকার ভ্যালু ও পুরস্কারের পুরো তালিকা দেখুন। প্রিভিউ পুরো তালিকা তৈরি করতে না পারলে এগোনোর আগে ম্যাপিং ঠিক করুন। ফিড আনা হলে নতুন ফর্ম তৈরি হয়; আগের ক্যাম্পেইন আপডেট হয় না।

Step 4: তৈরি করার আগে validate করুন

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 HTTP 200 সহ data.valid, একটি errors list, এবং একটি warnings list ফেরত দেয়। 200 response-এও valid: false থাকতে পারে, তাই client-কে HTTP status-কে একাই অনুমোদন হিসেবে না ধরে সেই value inspect করতে হবে। প্রতিটি issue /tracking/url, /pricing/payout, বা /image_upload_id-এর মতো JSON Pointer path ব্যবহার করে। একটি AI agent-কে শুধু নির্দেশিত field-টিই repair করতে হবে, আবার validate করতে হবে, এবং create permission চাইবার আগে account owner-কে final JSON দেখাতে হবে।

একটি valid response মানে payloadটি বর্তমান validation এবং persistence preflight পাস করেছে। এটি approval, activation, traffic, conversions, বা ভবিষ্যৎ যোগ্যতার promise নয়। Real-time review, funding, account access, hold, schedule, cap, এবং state check এখনও write এবং lifecycle action-এ প্রযোজ্য।

Step 5: Idempotency সহ নিরাপদে create করুন

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, এবং pause-এর জন্য 8 থেকে 200 visible ASCII character-সহ একটি Idempotency-Key দরকার। প্রতিটি intended action-এর জন্য নতুন key ব্যবহার করুন। Connection ব্যর্থ হলে এবং actionটি সম্পন্ন হয়েছিল কি না না জানলে, একই key দিয়ে identical action পুনরায় চেষ্টা করুন। CPAlead একই জিনিস দুবার create বা charge না করে completed response replay করতে পারে।

• Same key and same intent: Completed response meta.idempotent_replay=true সহ replay করা যেতে পারে।
• Same key with changed details: API একটি idempotency conflict ফেরত দেয়।
• Same external ID with changed details: API-ও একটি conflict ফেরত দেয়।
• Previous request still processing: Report করা interval অপেক্ষা করুন, তারপর একই key দিয়ে একই intent পুনরায় চেষ্টা করুন।

Optional external_id হলো create operation-এর জন্য আপনার নিজস্ব স্থায়ী reference। Reconciliation সহজ করতে পারে, কিন্তু ভিন্ন intended campaign-এর জন্য এটি পুনরায় ব্যবহার করা যাবে না।

Deposit-এর আগে তিনটি campaign

একটি advertiser account প্রথম successful advertiser deposit-এর আগে সর্বোচ্চ তিনটি মোট self-serve CPA, CPI, বা CPC campaign তৈরি করতে পারে। Paused, denied, এবং archived campaign-ও গণনা হয়, কারণ throwaway campaign তৈরি ও archive করা এই limit এড়াতে পারবে না। Successful deposit-এর পরে এই নির্দিষ্ট creation limit আর প্রযোজ্য নয়; normal review, balance, payout, budget, এবং activation rule তখনও প্রযোজ্য থাকে।

Campaign read এবং filter করুন

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

List endpoint campaign type, public state, updated_since timestamp, page, এবং per-page filter সমর্থন করে। Pagination-এর default 25 campaigns এবং page-প্রতি সর্বোচ্চ 100 অনুমতি দেয়। Public state choice হলো active, paused, pending_review, paused_for_funding, cap_reached, outside_schedule, denied, archived, এবং unavailable। Archived campaign কেবল তখনই দেখা যায় যখন আপনি স্পষ্টভাবে state=archived filter করেন।

একটি campaign resource-এ এর ID, optional external ID, version, type, name, creative, tracking, targeting, pricing, schedule, publisher-access setting, image URL, timestamps, এবং public state থাকে। State-এ review, desired-delivery, delivery-reason, এবং capability hint-ও থাকে। Capability hint advisory: সর্বশেষ campaign retrieve করুন এবং বাস্তব operation response handle করুন, কারণ account, funding, review, hold, এবং schedule condition পরিবর্তিত হতে পারে।

ETag version protection সহ update করুন

Campaign edit optimistic concurrency ব্যবহার করে। প্রথমে campaign retrieve করুন এবং exact quoted ETag response header save করুন। তারপর PATCH request-এর সাথে সেই value If-Match-এ পাঠান। এতে একটি browser, agent, বা integration অন্যত্র করা নতুন পরিবর্তন নীরবে overwrite করা থেকে রক্ষা পায়।

# 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"

• No If-Match: API HTTP 428 ফেরত দেয়।
• Stale If-Match: API বর্তমান version metadata সহ HTTP 412 ফেরত দেয়।
• 412-এর পরে: campaign আবার retrieve করুন, পরিবর্তন তুলনা করুন, approval চান, এবং নতুন ETag দিয়ে retry করুন।
• Unclear network result-এর পরে: আরেকটি update পাঠানোর আগে campaign retrieve করুন।

PATCH কেবল public campaign field গ্রহণ করে। এটি সরবরাহ করা partial object-কে বর্তমান campaign-এর সাথে merge করে এবং complete result validate করে। কিছু edit-এর জন্য আবার review দরকার হতে পারে বা delivery পরিবর্তন হতে পারে, তাই প্রতিবার response state পড়ুন।

Start এবং pause হলো explicit, bodyless action

# 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"

Start বা pause করতে JSON body পাঠাবেন না—{}-ও নয়। Start করার আগে campaign, balance, payout বা bid, launch-package effect, countries, devices, schedule, cap বা budget, landing page, এবং tracking নিশ্চিত করুন। Response-এর পরে public state inspect করুন; একটি campaign enabled হতে পারে কিন্তু তার daily schedule-এর বাইরে, funding-এর জন্য paused, cap-এ, বা অন্য কারণে delivery দিতে অক্ষম হতে পারে।

একটি integration-এর বোঝা উচিত এমন HTTP status এবং error

শুধু message wording-এর ওপর নির্ভর না করে HTTP status এবং stable error.code-এর বিরুদ্ধে automate করুন। Validation details-এ একটি path, code, এবং plain-English message থাকে। Support-এর সাথে যোগাযোগের সময় response-এর request_id অন্তর্ভুক্ত করুন।

Rate limit এবং দায়িত্বশীল retry

Campaign API request এবং authentication rate limited, যাতে advertiser এবং service সুরক্ষিত থাকে। Limit পরিবর্তিত হতে পারে, তাই hard-code করা request count-এর বদলে live OpenAPI schema এবং response headers ব্যবহার করুন। API যখন HTTP 429 ফেরত দেয়, তখন সঙ্গে সঙ্গে request repeat না করে Retry-After মেনে চলুন। অপ্রয়োজনীয় call এড়াতে pagination, updated_since, এবং অপরিবর্তিত public requirements-এর local caching ব্যবহার করুন।

API-capable AI agent অথবা integration-এর জন্য prompt

এই prompt ধরে নেয় যে client authenticated HTTPS request-এর সঙ্গে private bearer token যুক্ত করতে পারে। প্রথমে guide এবং OpenAPI URL শেয়ার করুন, তারপর client platform-এর private secret settings-এ token configure করুন। এই public prompt-এ আসল token দেবেন না। সাধারণ AI চ্যাট যদি বলে যে এটি authenticated request পাঠাতে পারে না, তাহলে অপ্রয়োজনীয় token revoke করুন এবং তার বদলে Temporary AI Campaign Draft Access ব্যবহার করুন।

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.

AI, MCP, plugin, এবং code-এর জন্য security checklist

• Least privilege: Read এবং validate দিয়ে শুরু করুন। প্রয়োজন হলে তবেই একটি write permission যোগ করুন।
• Short expiry: একবারের AI setup কাজের জন্য 48-hour option পছন্দ করুন।
• Separate tokens: প্রতিটি agent বা integration-কে তার নিজস্ব named token দিন।
• Private storage: Token secret settings-এ রাখুন, URL, prompt, log, analytics, screenshot, বা repository-তে নয়।
• Human confirmation: Create, update, start, বা pause করার আগে summary বাধ্যতামূলক করুন।
• Safe retries: অনিশ্চিত idempotent result-এর পরে একই key এবং payload বজায় রাখুন।
• Version checks: সর্বশেষ ETag retrieve না করে কখনও update করবেন না।
• Response checks: প্রতিটি write-এর পরে public state এবং request ID পড়ুন।
• Revoke promptly: কাজ শেষ হলে বা token ফাঁস হতে পারে মনে হলে Advertising API page থেকে access সরিয়ে দিন।

সচরাচর জিজ্ঞাসিত প্রশ্ন

আমি কি সাধারণ ChatGPT-তে Full Campaign API ব্যবহার করতে পারি?

শুধু তখনই, যখন ChatGPT-তে configured GPT Action অথবা অন্য কোনো authenticated integration থাকে, যা Authorization header-এ bearer token পাঠাতে পারে। সাধারণ চ্যাট সাধারণত তা পারে না। এর বদলে Temporary AI Campaign Draft Access ব্যবহার করুন। এটি শুধু inactive campaign draft প্রস্তুত ও save করতে পারে; আপনি সেগুলো CPAlead-এ review করে সম্পূর্ণ করবেন।

আমার CPAlead API key কোথায় পাব?

Campaign API-এর জন্য credential-টিকে Campaign API token বলা হয়। Sign in করুন এবং Advertising → Setup → API খুলুন, তারপর Create a token ব্যবহার করুন। Tokenটি সঙ্গে সঙ্গে copy করুন, কারণ CPAlead সম্পূর্ণ value কেবল একবারই দেখায়।

API কি CPA, CPI, এবং CPC campaign তৈরি করতে পারে?

হ্যাঁ। প্রতিটি type-এর JSON shape কঠোর কিন্তু আলাদা। এটি build করার আগে ওই type-এর জন্য requirements fetch করুন।

AI-কে কিছু create করতে না দিয়েও কি validate করা যায়?

হ্যাঁ। Token-এ শুধু campaigns:validate, এবং চাইলে campaigns:read দিন। Requirements এবং validation-এর জন্য create permission লাগে না।

Valid response মানে কি campaign approve হয়েছে?

না। এর মানে current payload validation এবং preflight পাস করেছে। Review, funding, account access, hold, cap, schedule, এবং real-time state তখনও প্রযোজ্য।

Create কি সঙ্গে সঙ্গে campaign start করতে পারে?

Account এবং campaign-এর ওপর নির্ভর করে পারে। এটি review-এও যেতে পারে। Returned public state সবসময় inspect করুন। CPA বা CPI activation unpaid selected launch package-ও charge করতে পারে।

আমি কি remote URL থেকে image upload করতে পারি?

না। POST /images দিয়ে image file upload করুন। CPAlead একটি temporary single-use image ID ফেরত দেয়।

আমি কি একসাথে অনেক offer create করতে পারি?

Bulk-create operation নেই। প্রতি request-এ এক campaign validate এবং create করুন, একটি distinct external ID এবং idempotency key ব্যবহার করুন, এবং rate limits ও account creation rules মেনে চলুন।

API কি campaign archive বা delete করতে পারে?

না। বর্তমান public API eligible campaign start এবং pause করতে পারে, কিন্তু archive বা delete প্রকাশ করে না। Archival-এর জন্য advertiser dashboard ব্যবহার করুন।

আমার update কেন HTTP 412 পেল?

আপনি এটি retrieve করার পর campaign পরিবর্তিত হয়েছে। আবার নিন, নতুন data review করুন, আপনার intended change merge করুন, এবং নতুন ETag দিয়ে retry করুন।

Create কেন HTTP 409 ফেরত দিল?

Stable error code পড়ুন। সম্ভাব্য public কারণের মধ্যে রয়েছে ভিন্ন data সহ reused idempotency key বা external ID, আগের request এখনও processing-এ থাকা, তিন-campaign pre-deposit limit, funding বা account restriction, hold, অথবা state conflict।

আমার application কি এই article থেকে field limits নকল করবে?

না। এই article workflow ব্যাখ্যা করে। আপনার application-এর live requirements এবং OpenAPI schema পড়া উচিত, যাতে current value-ই authoritative থাকে।

Machine-friendly Campaign API fact sheet

Read এবং validate দিয়ে শুরু করুন

Campaign API এমনভাবে design করা যে advertiser সতর্কভাবে শুরু করতে পারে। Trusted agent-কে public guide এবং schema দিন, read ও validation access grant করুন, এবং account না বদলিয়ে request প্রস্তুত করতে দিন। যখন JSON সঠিক হবে এবং owner সম্ভাব্য review, delivery, এবং financial effect বুঝবেন, তখন পরবর্তী confirmed action-এর জন্য প্রয়োজনীয় write permission-ই কেবল যোগ করুন।

Token তৈরি করতে Advertiser API Center-এ Campaign API খুলুন, অথবা বর্তমান contract inspect করতে public Campaign API OpenAPI schema খুলুন। Publisher API documentation আলাদা এবং এটি publisher-দের offer retrieve ও reporting কভার করে। Response যদি অস্পষ্ট হয়, token private রাখুন এবং public request ID ও campaign ID সহ Advertiser Support-এর সাথে যোগাযোগ করুন।

আপনি কি এই পোস্টে একটি ত্রুটি বা সংশোধনের প্রয়োজনীয়তা লক্ষ্য করেছেন? দয়া করে পোস্টের লিঙ্ক প্রদান করুন এবং আমাদের সাথে যোগাযোগ করুন. আমরা আপনার প্রতিক্রিয়া মূল্যায়ন করি এবং সমস্যাটি দ্রুত সমাধান করব.