CPAlead Full Campaign API: آفرز بنائیں اور ان کا انتظام کریں

CPAlead Full Campaign API ایک تصدیق شدہ self-serve advertiser کو code، API استعمال کرنے کے قابل AI ایجنٹ، MCP server، GPT Action یا plugin کے ذریعے CPA، CPI اور CPC مہمات پر کام کرنے دیتا ہے۔ دی گئی permissions کے مطابق، مجاز client موجودہ requirements پڑھ سکتا ہے، مکمل مہم کو save کرنے سے پہلے validate کر سکتا ہے، creative upload کر سکتا ہے، مہم create کر سکتا ہے، مہمات کی فہرست اور تفصیل حاصل کر سکتا ہے، version protection کے ساتھ مہم edit کر سکتا ہے، اور اہل مہم کو واضح طور پر start یا pause کر سکتا ہے۔

یہ عام advertiser dashboard کا automation companion ہے۔ اگر آپ پہلے campaign types، tracking، targeting، payouts، caps، funding، review، اور launch کی field-by-field وضاحت چاہتے ہیں، تو How to Advertise on CPAlead in 2026: Add and Launch Your First Offer پڑھیں۔ جب آپ اس setup کو structured JSON اور controlled API actions کی صورت میں ظاہر کرنے کے لیے تیار ہوں، تو یہ مضمون استعمال کریں۔

Full Campaign API کیا کر سکتا ہے

API فی الحال archive، delete، bulk-create، یا generic toggle operation فراہم نہیں کرتی۔ Archive یا delete کا کام dashboard workflow ہے۔ Start اور pause الگ actions ہیں تاکہ delivery تبدیل کرنے سے پہلے انسان یا AI client واضح تصدیق مانگ سکے۔

Temporary AI Campaign Draft Access، Full Campaign API اور Offer API Import میں سے انتخاب کریں

• Temporary AI Campaign Draft Access: عام ChatGPT اور ایسی ہی AI چیٹس کے لیے۔ پہلی کامیاب advertiser deposit سے پہلے، چار گھنٹے والا نجی لنک مہم کو validate کر کے مہم کے زیادہ سے زیادہ تین غیر فعال مسودے محفوظ کر سکتا ہے۔ کامیاب advertiser deposit کے بعد، لنک پر مہم کے مسودوں کی کوئی مجموعی حد نہیں رہتی۔ ہر اکاؤنٹ میں ایک وقت میں مہم کے زیادہ سے زیادہ 10 نامکمل مسودے زیر التوا ہو سکتے ہیں۔ یہ موجودہ مہمات کو دیکھ یا ان کا انتظام نہیں کر سکتا، upload نہیں کر سکتا، شرائط یا packages قبول نہیں کر سکتا، فنڈز خرچ نہیں کر سکتا، submit، start، pause یا activate نہیں کر سکتا۔ Temporary AI Campaign Draft Access کھولیں۔
• Full Campaign API: API استعمال کرنے کے قابل ایجنٹ، GPT Action، MCP server، plugin یا ایسی integration کے لیے جو bearer token کو محفوظ رکھ سکتی ہو۔ دیے گئے scopes مہمات کو validate، upload، create، read، edit، start اور pause کرنے کی اجازت دے سکتے ہیں۔ Full Campaign API کھولیں۔
• Offer API Import: advertiser dashboard کا الگ workflow، جو ایک موافق بیرونی feed سے آفرز حاصل کرتا ہے اور اس کے fields کو CPAlead میں map کرتا ہے۔ Offer API Import کھولیں۔

جب عام AI چیٹ نئی آفر تیار کرنے میں مدد کر رہی ہو تو مہم کے مسودے کا محفوظ اختیار استعمال کریں۔ جب کسی تصدیق شدہ client کو مہمات کے منظم انتظام کی صلاحیتیں درکار ہوں تو Full Campaign API استعمال کریں۔ جب CPAlead کو ایک موافق feed حاصل کرنا ہو تو Offer API Import استعمال کریں۔ کسی ٹول کو اس کے کام کی ضرورت سے زیادہ رسائی نہ دیں۔

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 options بھی دستیاب ہیں۔
5. صرف وہ permissions منتخب کریں جن کی client کو ضرورت ہو۔
6. Token بنائیں اور فوراً کاپی کریں۔ Page reload ہونے کے بعد CPAlead مکمل token دوبارہ نہیں دکھا سکتا۔
7. اسے trusted client کی secret configuration میں محفوظ کریں اور task ختم ہونے پر revoke کر دیں۔

ایک advertiser کے پاس زیادہ سے زیادہ 10 active Campaign API tokens ہو سکتے ہیں۔ الگ integrations کے لیے الگ tokens استعمال کریں تاکہ آپ permissions محدود رکھ سکیں، استعمال کا جائزہ لے سکیں، اور ایک 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 requests token کو HTTP authorization header میں ایک بار بھیجتے ہیں۔ اسے کبھی 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 اور current schema version شامل ہوتے ہیں، اور pagination، resource version، یا idempotent-replay flag بھی شامل ہو سکتا ہے۔ Error response میں error object کے ساتھ meta ہوتا ہے۔ Support کے ساتھ troubleshooting کرتے وقت عوامی request_id محفوظ کریں، لیکن support کو کبھی بھی اپنا bearer token نہ بھیجیں۔

Step 1: Live requirements پڑھیں

Requirements اس چیز کا source of truth ہیں جو account ابھی submit کر سکتا ہے۔ ان میں current schema اور terms versions، 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 استعمال کریں۔ کسی پرانے example سے schema version، terms version، payout limit، bid، budget، launch package، country، device، یا minimum app version hard-code نہ کریں۔ جب server بتائے کہ کوئی value یا version پرانا ہو چکا ہے تو requirements دوبارہ fetch کریں۔

تین campaign types

• 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 requests remote image URL قبول نہیں کرتے۔ پہلے file کو multipart form data کے طور پر upload کریں، پھر واپس آنے والا temporary image ID image_upload_id میں رکھیں۔

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

• قبول شدہ sources: JPG, JPEG, PNG, GIF, BMP, اور WebP۔
• زیادہ سے زیادہ file size: 2 MiB۔
• Source width اور height: ہر ایک 200 اور 4096 pixels کے درمیان ہونا چاہیے۔
• Stored result: ایک non-animated، metadata-free 200×200 WebP crop۔
• Unused upload lifetime: 24 hours۔
• Outstanding-upload limit: زیادہ سے زیادہ 25 current unused image uploads۔
• Use: ایک campaign create یا image update۔ مختلف campaign کے لیے دوبارہ upload کریں۔

Validation چیک کر سکتی ہے کہ image ID آپ کے account سے تعلق رکھتا ہے اور استعمال کے قابل ہے بغیر اسے consume کیے۔ کامیاب campaign write اسے consume کرتی ہے۔ اسی مکمل create کو اسی idempotency key کے ساتھ دوبارہ چلانے پر محفوظ result واپس آتا ہے؛ یہ consumed image سے دوسری campaign create نہیں کرتا۔

Step 3: مکمل campaign JSON بنائیں

API strict JSON objects استعمال کرتی ہے۔ Unknown fields silently ignore ہونے کے بجائے رد کر دیے جاتے ہیں۔ اس سے AI integration زیادہ محفوظ ہوتی ہے: غلط لکھا گیا یا گھڑا گیا property ایک نظر آنے والا validation issue بن جاتا ہے، نہ کہ غلطی سے campaign setting۔

مندرجہ ذیل CPA example ایک template ہے، submit کرنے کے لیے تیار campaign نہیں۔ اپنے حقیقی offer کے لیے ہر COPY_FROM_REQUIREMENTS value، image ID، URL، payout، country، cap، اور public description کو reviewed values سے بدلیں۔

{
  "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 اس numeric value کو save کرے جو CPAlead اس میں inserts کرتی ہے اور 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: Create کرنے سے پہلے 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 کو approval سمجھنے کے بجائے اس value کا جائزہ لینا چاہیے۔ ہر issue JSON Pointer path استعمال کرتا ہے جیسے /tracking/url, /pricing/payout, یا /image_upload_id۔ AI agent کو صرف indicated field درست کرنی چاہیے، دوبارہ validate کرنا چاہیے، اور create permission مانگنے سے پہلے final JSON account owner کو دکھانا چاہیے۔

Valid response کا مطلب ہے کہ payload موجودہ validation اور persistence preflight سے گزر گیا ہے۔ یہ approval، activation، traffic، conversions، یا future eligibility کی ضمانت نہیں ہے۔ Real-time review، funding، account access، holds، schedule، cap، اور state checks اب بھی writes اور lifecycle actions پر لاگو ہوتے ہیں۔

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 کے لیے Idempotency-Key درکار ہے جس میں 8 سے 200 visible ASCII characters ہوں۔ ہر مطلوب action کے لیے نئی key استعمال کریں۔ اگر connection fail ہو جائے اور آپ کو معلوم نہ ہو کہ action مکمل ہوا یا نہیں، تو اسی key کے ساتھ بالکل وہی action دوبارہ آزمائیں۔ CPAlead مکمل response دوبارہ چلا سکتی ہے بجائے اس کے کہ دو بار create یا charge کرے۔

• ایک جیسی key اور ایک جیسا intent: مکمل response meta.idempotent_replay=true کے ساتھ replay ہو سکتا ہے۔
• ایک جیسی key لیکن بدلی ہوئی تفصیلات: API idempotency conflict واپس کرتی ہے۔
• ایک جیسا external ID لیکن بدلی ہوئی تفصیلات: API بھی conflict واپس کرتی ہے۔
• پچھلی request ابھی process ہو رہی ہے: رپورٹ کردہ interval کا انتظار کریں، پھر اسی key کے ساتھ وہی intent retry کریں۔

اختیاری external_id create operation کے لیے آپ کا اپنا stable reference ہے۔ یہ reconciliation آسان بنا سکتا ہے، لیکن اسے کسی مختلف مطلوب campaign کے لیے دوبارہ استعمال نہیں کرنا چاہیے۔

Deposit سے پہلے تین campaigns

ایک advertiser account اپنی پہلی successful advertiser deposit سے پہلے مجموعی طور پر تین self-serve CPA، CPI، یا CPC campaigns تک create کر سکتا ہے۔ Paused، denied، اور archived campaigns بھی count ہوتے ہیں کیونکہ throwaway campaigns create اور archive کر کے limit کو bypass نہیں کیا جانا چاہیے۔ Successful deposit کے بعد یہ مخصوص creation limit مزید لاگو نہیں رہتی؛ معمول کے review، balance، payout، budget، اور activation rules پھر بھی لاگو رہتے ہیں۔

Campaigns پڑھیں اور 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 filters کو support کرتا ہے۔ Pagination default طور پر 25 campaigns ہے اور فی page زیادہ سے زیادہ 100 کی اجازت دیتی ہے۔ Public state choices active, paused, pending_review, paused_for_funding, cap_reached, outside_schedule, denied, archived, اور unavailable ہیں۔ Archived campaigns صرف تب نظر آتی ہیں جب آپ واضح طور پر 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 hints بھی شامل ہیں۔ Capability hints مشورتی ہیں: latest campaign حاصل کریں اور اصل operation response کو handle کریں کیونکہ account، funding، review، hold، اور schedule کی شرائط بدل سکتی ہیں۔

ETag version protection کے ساتھ update کریں

Campaign edits optimistic concurrency استعمال کرتی ہیں۔ پہلے campaign retrieve کریں اور quoted ETag response header محفوظ کریں۔ پھر PATCH request کے ساتھ وہ value If-Match میں بھیجیں۔ اس سے ایک browser، agent، یا integration کو کہیں اور کی گئی نئی تبدیلی silently 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"

• If-Match نہیں: API HTTP 428 واپس کرتی ہے۔
• پرانی If-Match: API current version metadata کے ساتھ HTTP 412 واپس کرتی ہے۔
• 412 کے بعد: campaign دوبارہ retrieve کریں، تبدیلیوں کا موازنہ کریں، approval مانگیں، اور نئے ETag کے ساتھ retry کریں۔
• غیر واضح network result کے بعد: اگلا update بھیجنے سے پہلے campaign retrieve کریں۔

PATCH صرف public campaign fields قبول کرتا ہے۔ یہ supplied partial object کو current campaign کے ساتھ merge کرتا ہے اور complete result validate کرتا ہے۔ کچھ edits کے لیے دوبارہ review یا delivery change درکار ہو سکتی ہے، اس لیے ہر بار response state پڑھیں۔

Start اور pause واضح، bodyless actions ہیں

# 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 کا جائزہ لیں؛ campaign enabled ہو سکتی ہے لیکن اپنی daily schedule سے باہر، funding کے لیے paused، اپنے cap پر، یا کسی اور وجہ سے deliver کرنے کے قابل نہ ہو۔

HTTP statuses اور errors جنہیں integration کو سمجھنا چاہیے

HTTP status اور stable error.code کے خلاف automate کریں، صرف message wording کے خلاف نہیں۔ Validation details میں path، code، اور سادہ انگریزی میں message شامل ہوتے ہیں۔ Support سے رابطہ کرتے وقت response request_id شامل کریں۔

Rate limits اور ذمہ دارانہ retries

Campaign API requests اور authentication کو advertisers اور service کی حفاظت کے لیے rate limited رکھا جاتا ہے۔ Limits بدل سکتے ہیں، اس لیے request count hard-code کرنے کے بجائے live OpenAPI schema اور response headers استعمال کریں۔ جب API HTTP 429 واپس کرے تو فوراً requests دہرانے کے بجائے Retry-After کا انتظار کریں۔ غیر ضروری calls سے بچنے کے لیے pagination، updated_since، اور غیر بدلے ہوئے public requirements کی local caching استعمال کریں۔

API استعمال کرنے کے قابل AI ایجنٹ یا integration کے لیے prompt

یہ prompt فرض کرتا ہے کہ client تصدیق شدہ HTTPS درخواستوں کے ساتھ نجی bearer token لگا سکتا ہے۔ پہلے گائیڈ اور OpenAPI URL شیئر کریں، پھر token کو client platform کی نجی secret settings میں configure کریں۔ اس عوامی prompt میں اصل token شامل نہ کریں۔ اگر عام AI چیٹ کہے کہ وہ تصدیق شدہ درخواستیں نہیں بھیج سکتی، تو غیر ضروری 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، plugins، اور code کے لیے security checklist

• Least privilege: Read اور validate سے شروع کریں۔ صرف ضرورت پڑنے پر ایک write permission شامل کریں۔
• Short expiry: ایک بار کے AI setup task کے لیے 48-hour option ترجیح دیں۔
• Separate tokens: ہر agent یا integration کو اپنا الگ نامی token دیں۔
• Private storage: Tokens کو secret settings میں رکھیں، URLs، prompts، logs، analytics، screenshots، یا repositories میں نہیں۔
• Human confirmation: Create، update، start، یا pause سے پہلے summary لازمی کریں۔
• Safe retries: uncertain idempotent result کے بعد ایک ہی key اور payload برقرار رکھیں۔
• Version checks: latest ETag حاصل کیے بغیر کبھی update نہ کریں۔
• Response checks: ہر write کے بعد public state اور request ID پڑھیں۔
• Promptly revoke: جب کام مکمل ہو جائے یا token لیک ہونے کا امکان ہو تو Advertising API page سے access ہٹا دیں۔

اکثر پوچھے گئے سوالات

کیا میں عام ChatGPT میں Full Campaign API استعمال کر سکتا ہوں؟

صرف اس وقت جب ChatGPT میں ایک configured GPT Action یا کوئی دوسری تصدیق شدہ integration ہو جو Authorization header میں bearer token بھیج سکتی ہو۔ عام چیٹ عموماً ایسا نہیں کر سکتی۔ اس کے بجائے Temporary AI Campaign Draft Access استعمال کریں۔ یہ صرف مہم کے غیر فعال مسودے تیار اور محفوظ کر سکتا ہے؛ آپ CPAlead میں ان کا جائزہ لے کر انہیں مکمل کرتے ہیں۔

اپنی CPAlead API key کہاں ملے گی؟

Campaign API کے لیے credential کو Campaign API token کہا جاتا ہے۔ Sign in کریں اور Advertising → Setup → API کھولیں، پھر Create a token استعمال کریں۔ Token فوراً کاپی کریں کیونکہ CPAlead مکمل value صرف ایک بار دکھاتا ہے۔

کیا API CPA، CPI، اور CPC campaigns create کر سکتی ہے؟

جی ہاں۔ ہر type کی JSON shape سخت مگر مختلف ہے۔ اسے بنانے سے پہلے اُس type کے لیے requirements حاصل کریں۔

کیا میں AI کو کچھ create کرنے کی اجازت دیے بغیر validate کر سکتا ہوں؟

جی ہاں۔ Token کو صرف campaigns:validate، اور اختیاری طور پر campaigns:read دیں۔ Requirements اور validation کو create permission کی ضرورت نہیں ہوتی۔

کیا valid response کا مطلب ہے campaign approved ہے؟

نہیں۔ اس کا مطلب ہے کہ current payload validation اور preflight سے گزر گیا ہے۔ Review، funding، account access، holds، caps، schedules، اور real-time state پھر بھی لاگو ہوتے ہیں۔

کیا create فوراً campaign start کر سکتا ہے؟

یہ account اور campaign پر منحصر ہو کر ہو سکتا ہے۔ یہ review میں بھی جا سکتا ہے۔ ہمیشہ واپس آنے والی public state چیک کریں۔ CPA یا CPI activation ایک unpaid selected launch package بھی charge کر سکتی ہے۔

کیا میں remote URL سے image upload کر سکتا ہوں؟

نہیں۔ Image file کو POST /images کے ذریعے upload کریں۔ CPAlead ایک temporary single-use image ID واپس کرتا ہے۔

کیا میں ایک ساتھ بہت سے offers create کر سکتا ہوں؟

Bulk-create operation موجود نہیں ہے۔ ایک request میں ایک campaign validate اور create کریں، distinct external ID اور idempotency key استعمال کریں، اور rate limits اور account creation rules کا احترام کریں۔

کیا API کسی campaign کو archive یا delete کر سکتی ہے؟

نہیں۔ موجودہ عوامی API eligible campaigns کو start اور pause کر سکتی ہے لیکن archive یا delete پیش نہیں کرتی۔ Archival کے لیے advertiser dashboard استعمال کریں۔

میرے update کو HTTP 412 کیوں ملا؟

Campaign آپ کے retrieve کرنے کے بعد بدل گیا تھا۔ اسے دوبارہ حاصل کریں، تازہ ترین data کا جائزہ لیں، اپنی مطلوبہ تبدیلی merge کریں، اور نئے ETag کے ساتھ retry کریں۔

Create نے HTTP 409 کیوں واپس کیا؟

Stable error code پڑھیں۔ ممکنہ عوامی وجوہات میں مختلف data کے ساتھ reused idempotency key یا external ID، کوئی پچھلی request ابھی process ہو رہی ہونا، تین-campaign pre-deposit limit، funding یا account restrictions، hold، یا state conflict شامل ہیں۔

کیا میری application کو اس article سے field limits copy کرنی چاہئیں؟

نہیں۔ یہ article workflow کی وضاحت کرتا ہے۔ آپ کی application کو live requirements اور OpenAPI schema پڑھنا چاہیے تاکہ current values 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 effects کو سمجھ لے، تو صرف اگلی confirmed action کے لیے درکار write permission شامل کریں۔

Token بنانے کے لیے Advertiser API Center میں Campaign API کھولیں، یا موجودہ contract دیکھنے کے لیے public Campaign API OpenAPI schema کھولیں۔ Publisher API documentation الگ ہے اور publishers کے offers retrieve کرنے اور reporting کو cover کرتی ہے۔ اگر response واضح نہ ہو، token کو private رکھیں اور public request ID اور campaign ID کے ساتھ Advertiser Support سے رابطہ کریں۔

کیا آپ نے اس پوسٹ میں کوئی غلطی یا ایسی چیز نوٹ کی ہے جس کی درستگی کی ضرورت ہے؟ براہ کرم پوسٹ کا لنک فراہم کریں اور ہمیں رابطہ کریں. ہم آپ کی رائے کی قدر کرتے ہیں اور مسئلے کو جلدی حل کریں گے.