زمرہ: Tutorials

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

مصنف: CPAlead
CPAlead مشتہر مہم API: آفرز بنائیں اور منظم کریں

کیا آپ اپنے CPAlead کیمپیئنز بنانے یا ان کا نظم کرنے میں مدد کے لیے کسی AI ایجنٹ کو چاہتے ہیں؟

یہ عوامی گائیڈ اپنے ایجنٹ کے ساتھ شیئر کریں: https://www.cpalead.com/en/blog/tutorials/cpalead-advertiser-campaign-api-guide

عوامی OpenAPI schema بھی یہاں شیئر کریں: https://www.cpalead.com/api/v1/advertiser/openapi.json۔ گائیڈ اور schema عوامی ہیں؛ آپ کا bearer token عوامی نہیں ہے۔ token کو الگ سے ایک trusted AI client، MCP server، plugin، یا integration میں secret کے طور پر configure کریں۔ کبھی بھی token کو عوامی گفتگو، URL، campaign field، screenshot، یا source-code repository میں paste نہ کریں۔

Campaign API dashboard access نہیں ہے۔ Campaign API token صرف انہی campaign permissions کو authorize کرتا ہے جو آپ منتخب کریں۔ اسے آپ کے CPAlead dashboard میں sign in کرنے کے لیے استعمال نہیں کیا جا سکتا۔ Publisher AI Access ایک الگ publisher-only feature ہے۔

CPAlead Campaign API ایک verified self-serve advertiser کو code، AI agent، MCP server، یا plugin کے ذریعے CPA، CPI، اور CPC campaigns کے ساتھ کام کرنے کی اجازت دیتا ہے۔ ایک authorized client موجودہ campaign requirements پڑھ سکتا ہے، save کرنے سے پہلے مکمل campaign validate کر سکتا ہے، creative upload کر سکتا ہے، campaign create کر سکتا ہے، campaigns کی فہرست اور retrieval کر سکتا ہے، version protection کے ساتھ campaign edit کر سکتا ہے، اور eligible campaign کو واضح طور پر 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 کی صورت میں ظاہر کرنے کے لیے تیار ہوں، تو یہ مضمون استعمال کریں۔

سب سے محفوظ quick-start workflow

  1. صرف campaigns:read اور campaigns:validate کے ساتھ ایک short-lived Campaign API token بنائیں۔
  2. اپنے trusted client کو public OpenAPI URL دیں اور token کو privately bearer secret کے طور پر configure کریں۔
  3. اندازہ لگانے کے بجائے CPA، CPI، یا CPC کے لیے GET /requirements call کریں۔
  4. مکمل campaign JSON draft کریں اور POST /campaigns/validate call کریں۔
  5. ہر error، warning، payout، budget، targeting rule، schedule، اور ممکنہ charge کا جائزہ لیں۔
  6. اس کے بعد ہی image-upload اور campaign-create permissions شامل کریں۔
  7. ایک unique idempotency key کے ساتھ create کریں، پھر واپس آنے والی review اور delivery state کا معائنہ کریں۔
  8. کام مکمل ہونے پر token revoke کر دیں۔

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

CPAlead advertiser Campaign API operations and required permissions
عمل طریقہ اور path اجازت حفاظتی اصول
OpenAPI پڑھیںGET /openapi.jsonعوامیکسی token کی ضرورت نہیں
requirements پڑھیںGET /requirementscampaigns:validateJSON بنانے سے پہلے پڑھیں
JSON validate کریںPOST /campaigns/validatecampaigns:validatecampaign create نہیں کرتا
تصویر upload کریںPOST /imagesassets:createtemporary، expiring، single-use ID
Campaigns کی فہرست بنائیںGET /campaignscampaigns:readpagination کے ساتھ اور filterable
Campaign create کریںPOST /campaignscampaigns:createUnique Idempotency-Key
ایک campaign حاصل کریںGET /campaigns/{campaign}campaigns:readموجودہ ETag واپس کرتا ہے
Campaign update کریںPATCH /campaigns/{campaign}campaigns:updateIf-Match میں exact ETag
Campaign start کریںPOST /campaigns/{campaign}/actions/startcampaigns:toggleBodyless اور idempotent
Campaign pause کریںPOST /campaigns/{campaign}/actions/pausecampaigns:toggleBodyless اور idempotent

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

Campaign API اور Offer API Import مختلف ہیں

  • Campaign API: ایک scoped bearer-token API جو آپ کے advertiser account میں campaigns کو validate، create، read، edit، start، اور pause کرتی ہے۔
  • Offer API Import: ایک الگ advertiser-dashboard workflow جو compatible external feed سے offers پڑھتا ہے اور اس کے fields کو CPAlead میں map کرتا ہے۔

Advertiser API Center یہ tools الگ صفحات پر رکھتا ہے۔ Sign in کریں، Setup → API کھولیں، پھر وہ tool منتخب کریں جو آپ کے کام سے میل کھاتا ہو۔ جب آپ کی اپنی application، agent، MCP server، یا plugin کے پاس پہلے ہی offer data موجود ہو اور اسے CPAlead کے ساتھ کام کرنے کے لیے structured طریقہ درکار ہو، تو Campaign API استعمال کریں۔ جب CPAlead کو supported offer feed fetch اور map کرنا ہو تو importer استعمال کریں۔ کسی integration کو اس کے کام سے زیادہ وسیع token نہ دیں۔

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 استعمال کریں۔

CPAlead Campaign API token form with name, expiration, permission checkboxes, and Create token button
Setup → API کھولیں، Campaign API منتخب کریں، پھر token کو نام دیں، expiration منتخب کریں، اور صرف وہ permissions دیں جن کی آپ کے integration کو ضرورت ہو۔ CPAlead تیار token ایک بار دکھاتا ہے، اس لیے اسے فوراً کاپی کریں اور trusted integration کی secret settings میں محفوظ کریں۔
Campaign API token permissions
اجازتاجازت دیتی ہےکب دیں
campaigns:readاپنے campaigns دیکھیںمحفوظ ابتدائی اجازت
campaigns:validaterequirements پڑھیں اور JSON validate کریںمحفوظ ابتدائی اجازت
assets:createcampaign images upload کریںجب حقیقی create یا image edit تیار کر رہے ہوں
campaigns:createایک campaign بنائیںfinal JSON کے جائزے کے بعد
campaigns:updateایک campaign edit کریںصرف جب edits درکار ہوں
campaigns:toggleCampaign start یا pause کریںصرف واضح delivery controls کے ساتھ

Token rule: عوامی گائیڈ اور OpenAPI URL آزادانہ طور پر شیئر کریں۔ Bearer token صرف اُس client کے ساتھ شیئر کریں جس پر آپ بھروسہ کرتے ہیں، اس کی private secret settings کے ذریعے۔ CPAlead ایک secure hash محفوظ کرتا ہے اور creation کے بعد token کا صرف ابتدائی حصہ دکھاتا ہے۔

Base URL, authentication, اور response format

API base: https://www.cpalead.com/api/v1/advertiser
OpenAPI: https://www.cpalead.com/api/v1/advertiser/openapi.json

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: ایک declared action کے لیے pay کرتا ہے۔ Tracking URL میں {CLICK_ID} ہونا ضروری ہے، اور preview URL، conversion goal، daily cap، اور launch package create shape کا حصہ ہیں۔
  • CPI: install یا configured app event کے لیے pay کرتا ہے۔ یہ {CLICK_ID} استعمال کرتا ہے اور device platform، tracking method، supported iOS version، اور proxy handling جیسے app-oriented choices شامل کرتا ہے۔
  • CPC: ایک valid click کے لیے pay کرتا ہے۔ یہ conversion payout، daily cap، اور launch package کے بجائے bid اور daily budget استعمال کرتا ہے۔

Campaign API کی تمام monetary values USD میں ہوتی ہیں، اور API schedules UTC استعمال کرتے ہیں۔ واپس آنے والے requirements پڑھیں اور فیصلہ کرنے والے شخص کو یہ حقائق دکھائیں۔

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 استعمال کریں۔

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 کے لیے دوبارہ استعمال نہیں کرنا چاہیے۔

Creation کا حقیقی اثر ہو سکتا ہے۔ Account settings، review، balance، schedule، اور campaign type کے مطابق، نئی campaign review کے لیے submit ہو سکتی ہے یا چلانے کے لیے eligible ہو سکتی ہے۔ CPA اور CPI campaigns کو start یا activate کرنے سے unpaid selected launch package charge ہو سکتا ہے۔ ہمیشہ واپس آنے والی public state اور financial requirements کا جائزہ لیں، نہ کہ یہ فرض کریں کہ create کا مطلب “draft save” ہے۔

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 کو سمجھنا چاہیے

Common Campaign API HTTP statuses
StatusمطلبClient action
200 / 201Read/update کامیاب یا resource create ہو گیاdata, meta, state, ETag، اور Location کا جائزہ لیں
400Malformed request یا missing/invalid idempotency keyRequest درست کریں؛ blind-retry نہ کریں
401Missing، invalid، expired، یا revoked tokenSecret کو ٹھیک کریں یا replace کریں
403Token کے پاس required permission یا account access نہیںLeast-privilege scope اور account eligibility کا جائزہ لیں
404Campaign اس advertiser کے لیے unavailable ہےID چیک کریں؛ کسی دوسرے account کا data فرض نہ کریں
409State، funding، hold، creation-limit، یا idempotency conflictStable error code اور recommended action پڑھیں
412Stale ETagUpdate retrieve، review، اور rebase کریں
415JSON endpoint کو غلط content type ملاapplication/json بھیجیں
422Validation ناکام ہوئیJSON Pointer issues درست کریں اور دوبارہ validate کریں
428Update میں If-Match غائب ہےCampaign retrieve کریں اور اس کا ETag بھیجیں
429Rate limit پہنچ گیاRetry-After کی پابندی کریں
503ضروری API storage یا service عارضی طور پر دستیاب نہیںبعد میں retry کریں بغیر کسی idempotent intent کو بدلے

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 استعمال کریں۔

ایک prompt جو آپ کسی trusted AI agent کو دے سکتے ہیں

پہلے گائیڈ اور OpenAPI URL شیئر کریں۔ Token کو agent platform کی private secret settings میں configure کریں؛ اس prompt میں کوئی حقیقی token درج نہ کریں۔

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 ہٹا دیں۔

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

اپنی 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

  • مقصد: self-serve advertiser campaigns بنانا اور manage کرنا۔
  • Base URL: https://www.cpalead.com/api/v1/advertiser
  • OpenAPI: https://www.cpalead.com/api/v1/advertiser/openapi.json
  • Token setup: /en/advertising/api کھولیں، پھر Campaign API منتخب کریں۔
  • Supported campaign types: CPA, CPI, CPC.
  • Currency: USD.
  • Schedule timezone: UTC.
  • Recommended AI token: پہلے read اور validate کے ساتھ 48 hours۔
  • Maximum active tokens: 10.
  • Image input: JPG/JPEG/PNG/GIF/BMP/WebP، 2 MiB تک، ہر side پر 200–4096 pixels۔
  • Image output: 200×200 metadata-free WebP؛ temporary ID 24 hours بعد expire ہوتا ہے اور single-use ہے۔
  • Create/start/pause retry safety: Idempotency-Key.
  • Update concurrency: strong ETag کے ساتھ If-Match.
  • CPA/CPI click macro: {CLICK_ID}.
  • Pre-deposit creation allowance: تین total self-serve campaigns۔
  • دستیاب نہیں: archive، delete، bulk create، generic toggle، remote-image create۔

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 سے رابطہ کریں۔

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