CPAlead Full Campaign API: Gumawa at Pamahalaan ang Mga Offer

Pinahihintulutan ng CPAlead Full Campaign API ang isang verified self-serve advertiser na gumamit ng code, API-capable AI agent, MCP server, GPT Action, o plugin para sa mga CPA, CPI, at CPC campaign. Ayon sa mga ibinigay na permission, maaaring basahin ng isang authorized client ang mga kasalukuyang requirement, mag-validate ng kumpletong campaign bago ito i-save, mag-upload ng creative, gumawa ng campaign, maglista at kumuha ng mga campaign, mag-edit ng campaign na may version protection, at malinaw na magsimula o mag-pause ng isang eligible campaign.

Ito ang automation na kasama ng karaniwang advertiser dashboard. Kung gusto mo muna ng paliwanag na field-by-field tungkol sa mga campaign type, tracking, targeting, payouts, caps, funding, review, at launch, basahin ang How to Advertise on CPAlead in 2026: Add and Launch Your First Offer. Gamitin ang artikulong ito kapag handa ka nang isalin ang setup na iyon bilang structured JSON at kontroladong API actions.

Ano ang magagawa ng Full Campaign API

Ang API ay hindi kasalukuyang nagbibigay ng archive, delete, bulk-create, o generic toggle operation. Ang archive o delete ay ginagawa sa dashboard workflow. Ang start at pause ay magkahiwalay na actions para makapaghiling ang tao o AI client ng malinaw na kumpirmasyon bago baguhin ang delivery.

Pumili sa Temporary AI Campaign Draft Access, Full Campaign API, at Offer API Import

• Temporary AI Campaign Draft Access: Para sa karaniwang ChatGPT at katulad na AI chat. Bago ang unang matagumpay na advertiser deposit, ang apat-na-oras na private link ay maaaring mag-validate at mag-save ng hanggang tatlong inactive campaign draft. Pagkatapos ng matagumpay na advertiser deposit, wala nang kabuuang limit ng campaign draft sa bawat link. Ang bawat account ay maaaring magkaroon ng hanggang 10 hindi natapos na campaign draft na pending nang sabay-sabay. Hindi nito maaaring tingnan o pamahalaan ang mga kasalukuyang campaign, mag-upload, tumanggap ng terms o packages, gumastos ng pondo, magsumite, magsimula, mag-pause, o mag-activate. Buksan ang Temporary AI Campaign Draft Access.
• Full Campaign API: Para sa API-capable agent, GPT Action, MCP server, plugin, o integration na kayang protektahan ang bearer token. Ayon sa mga ibinigay na scope, maaari nitong mag-validate, mag-upload, gumawa, magbasa, mag-edit, magsimula, at mag-pause ng mga campaign. Buksan ang Full Campaign API.
• Offer API Import: Isang hiwalay na workflow sa advertiser dashboard na kumukuha ng mga offer mula sa compatible external feed at nagma-map ng mga field nito sa CPAlead. Buksan ang Offer API Import.

Gamitin ang protektadong opsyon para sa campaign draft kapag tinutulungan ka ng karaniwang AI chat na maghanda ng bagong offer. Gamitin ang Full Campaign API kapag kailangan ng authenticated client ng mga structured campaign-management ability. Gamitin ang Offer API Import kapag dapat kumuha ang CPAlead mula sa compatible feed. Huwag bigyan ang anumang tool ng access na mas malawak kaysa sa kailangan ng trabaho nito.

Gumawa ng Campaign API token

1. Mag-sign in sa isang verified self-serve advertiser account.
2. Buksan ang Setup → API, pagkatapos piliin ang Campaign API.
3. Bigyan ang token ng madaling makilalang pangalan, gaya ng “Campaign validator” o “My MCP agent.”
4. Pumili ng expiration. Inirerekomenda ang 48-hour option para sa AI setup; available din ang 30-day, 90-day, at 365-day na opsyon.
5. Piliin lamang ang mga permission na kailangan ng client.
6. Gumawa ng token at kopyahin ito agad. Hindi na maipapakita ng CPAlead ang kumpletong token muli pagkatapos mag-reload ang page.
7. I-store ito sa secret configuration ng pinagkakatiwalaang client at i-revoke ito kapag natapos ang gawain.

Maaaring magkaroon ang advertiser ng hanggang 10 aktibong Campaign API token. Gumamit ng hiwalay na token para sa magkakahiwalay na integration para malimitahan mo ang permissions, masuri ang paggamit, at ma-revoke ang isang integration nang hindi naaantala ang iba.

Saan gagawa ng iyong Campaign API token

Ang Campaign API token ay ang pribadong API credential na ipinapadala sa Authorization header. Hindi ito ang iyong CPAlead password, at hindi ito magagamit para mag-sign in sa CPAlead dashboard. Pagkatapos mag-sign in, buksan ang Setup → API, piliin ang Campaign API, at gamitin ang Create a token form.

Base URL, authentication, at response format

Ang mga authenticated request ay nagpapadala ng token nang isang beses sa HTTP authorization header. Huwag kailanman ilagay ito sa URL o query string.

Authorization: Bearer YOUR_TOKEN
Accept: application/json

Para sa mga curl example sa ibaba, mas ligtas na i-store ang authorization header sa isang local curl configuration file na hindi kasama sa source control at ikaw lamang ang makakabasa:

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

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

Ang matagumpay na response ay may data object o listahan kasabay ng meta. Kasama sa metadata ang request_id at kasalukuyang schema version, at maaaring may pagination, resource version, o idempotent-replay flag. Ang error response ay may error object kasabay ng meta. I-save ang public request_id kapag nagte-troubleshoot kasama ang support, pero huwag kailanman ipadala sa support ang iyong bearer token.

Hakbang 1: Basahin ang live requirements

Ang requirements ang source of truth para sa kung ano ang puwedeng isumite ng account ngayon. Kabilang dito ang kasalukuyang schema at terms versions, eligibility sa account creation, sinusuportahang bansa at device, field limits, campaign-type rules, pricing ranges, schedules, launch packages, tracking requirements, image rules, at inirerekomendang workflow.

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

Gamitin ang type=CPA, type=CPI, o type=CPC para limitahan ang response. Huwag i-hard-code ang schema version, terms version, payout limit, bid, budget, launch package, country, device, o minimum app version mula sa lumang halimbawa. Kunin muli ang requirements kapag iniulat ng server na luma na ang isang value o version.

Ang tatlong campaign type

• CPA: Nagbabayad para sa isang aksyon o mga gantimpala para sa maraming event. Dapat may {CLICK_ID} ang tracking URL. Kasama sa datos para sa paggawa ng campaign ang preview URL, arawang limitasyon, at launch package. Kailangan ng conversion goal para sa campaign na may isang bayad; sa event campaign, nakasaad sa listahan ng mga event ang bawat aksyong may gantimpala.
• CPI: Nagbabayad para sa isang install o aksyon sa app, o mga gantimpala para sa maraming event. Gumagamit ito ng {CLICK_ID} at may dagdag na pagpipilian para sa app, tulad ng platform ng device, paraan ng tracking, mga suportadong bersyon ng OS, at paghawak sa proxy. Magdagdag ng hiwalay na install event kung gusto mong bayaran ang mga install sa isang event campaign.
• CPC: Nagbabayad para sa valid click. Gumagamit ito ng bid at daily budget sa halip na conversion payout, daily cap, at launch package.

Lahat ng halagang pera sa Campaign API ay nasa USD, at UTC ang ginagamit sa mga iskedyul ng API. Para sa CPA at CPI, ang bayad na mas mababa sa $10.00 ay nangangailangan ng arawang limitasyong hindi bababa sa 20. Kung $10.00 o higit pa ang bayad, puwedeng kasingbaba ng 5 ang arawang limitasyon. Para sa event campaign, gamitin ang kabuuan ng lahat ng bayad sa mga event para sa mga tuntuning ito sa minimum na limitasyon. Basahin ang kasalukuyang mga kinakailangan bago pumili ng mga halaga at limitasyon.

Hakbang 2: Mag-upload ng campaign image

Ang create request ay hindi tumatanggap ng remote image URL. I-upload muna ang file bilang multipart form data, pagkatapos ilagay ang ibinalik na pansamantalang image ID sa image_upload_id.

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

• Tinanggap na sources: JPG, JPEG, PNG, GIF, BMP, at WebP.
• Pinakamataas na laki ng file: 2 MiB.
• Source width at height: bawat isa ay dapat nasa pagitan ng 200 at 4096 pixels.
• Naka-store na resulta: isang hindi animated, walang metadata na 200×200 WebP crop.
• Habang hindi pa nagagamit na lifetime ng upload: 24 oras.
• Limit ng outstanding upload: hanggang 25 kasalukuyang hindi pa nagagamit na image uploads.
• Gamitin: isang campaign create o image update. Mag-upload muli para sa ibang campaign.

Maaaring i-check ng validation kung ang isang image ID ay kabilang sa iyong account at puwedeng gamitin nang hindi ito nauubos. Kinokonsumo ito ng matagumpay na campaign write. Ang pag-replay ng parehong natapos na create gamit ang parehong idempotency key ay magbabalik ng naka-store na resulta; hindi ito lilikha ng pangalawang campaign mula sa nagamit nang image.

Hakbang 3: Bumuo ng kumpletong campaign JSON

Ang API ay gumagamit ng mahigpit na JSON objects. Ang mga hindi kilalang field ay tinatanggihan sa halip na tahimik na hindi pansinin. Mas ligtas nito ang isang AI integration: ang maling baybay o imbentong property ay nagiging nakikitang validation issue sa halip na aksidenteng campaign setting.

Ang sumusunod na halimbawa ng CPA ay isang template, hindi handa para sa pagsusumite. Palitan ang bawat COPY_FROM_REQUIREMENTS na value, image ID, URL, payout, bansa, cap, at public description ng mga nirepasong value para sa iyong totoong offer.

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

Mahalagang tracking rule para sa CPA at CPI

Dapat maglaman ang tracking URL ng eksaktong {CLICK_ID} macro. Dapat i-save ng iyong tracker o affiliate platform ang numeric value na inilalagay doon ng CPAlead at ibalik ang naka-save na click ID na iyon sa CPAlead advertiser postback pagkatapos ng conversion. Huwag ilagay ang postback URL ng CPAlead sa campaign tracking URL. Para sa buong paliwanag mula click hanggang postback, gamitin ang public advertiser postback guide.

Pumili ng isang bayad o mga gantimpala para sa maraming event

Sinusuportahan ng CPA at CPI ang conversion_mode na may mga halagang single at events. Basahin ang conversion_modes at event_rules sa mga kinakailangan bago pumili. Nagbabayad ang CPC para sa mga click at hindi nito sinusuportahan ang mga gantimpala sa event.

Sa isang bayad na aksyon, tumatanggap ang kalahok ng isang bayad sa conversion. Sa mga gantimpala para sa maraming event, nagtatakda ka ng hiwalay at nakapirming bayad sa USD para sa bawat aksyon. Halimbawa, magbayad ng $0.50 para sa paggawa ng account at $1.25 para sa pagkumpleto ng tutorial. Ang pinakamataas na kabuuan ay $1.75 bawat kalahok; hindi ito dagdag na bayad.

Para sa kumpletong CPA request gaya ng halimbawa sa itaas, gamitin ang mga event field at presyong ito. Panatilihin ang iba pang kinakailangang field ng campaign. Para sa CPI, pumili rin ng suportadong platform ng app at paraan ng tracking. Palitan ang lahat ng halimbawang aksyon, presyo, at targeting ng sarili mong mga pagpipiliang nasuri mo na.

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

Ang isang listahan ay may 1–10 event. Kailangan ng bawat isa ng pangalan at bayad na higit sa zero, na may hindi hihigit sa dalawang decimal place; opsyonal ang mga tagubilin sa pagkumpleto. Maaaring hindi ilagay ang mga bagong event ID upang CPAlead ang magtalaga ng mga ito. Itabi ang mga ibinalik na numerong ID para sa mga susunod na update at postback. Sa pagsulat ng mga event, maaaring hindi isama ang pricing.payout; kung isasama, dapat katumbas ito ng kabuuan ng lahat ng bayad sa mga event. Opsyonal ang creative.conversion_goal para sa mga event campaign, at dapat false ang targeting.tools_only.

Maaaring bayaran ang bawat event nang isang beses lamang bawat kalahok, sa anumang pagkakasunod-sunod, sa loob ng 30 araw mula sa orihinal na click. Binibilang ng arawang limitasyon ang isang kalahok sa una niyang nabayarang event. Hindi na muling binibilang ang mga susunod na event. Ang pag-pause o pag-abot sa limitasyon ay humihinto sa bagong traffic ngunit hindi nagkakansela ng mga kwalipikadong gantimpalang hindi pa nababayaran. Magpanatili ng sapat na pondo para sa mga ito; ang mga nakabinbing pagkumpleto ay maaaring lumampas sa limitasyon ng traffic sa isang araw.

I-track at i-update ang mga event campaign

Para sa karaniwang postback, ipadala ang sarili mong postback ID, ang orihinal na naka-save na click_id, at value na tumutukoy sa natapos na reward. Isama ang campaign_id para sa dagdag na proteksiyon; dapat itong tumugma sa campaign ng orihinal na click. Gamitin ang URL na ginawa para sa account at huwag mag-imbento ng mga ID.

Kapag kulang ang balanse, ibinabalik ang HTTP 503 na may low_balance. Magdagdag ng pondo at subukang muli ang parehong event pagkatapos ng Retry-After. Gamitin ang Guided Test bago magpadala ng traffic.

Para sa karaniwang tracker, tinatanggap ng Full Campaign API at Temporary AI Campaign Draft Access ang opsyonal na event field na postback_event_value kapag nakalista ito sa event_rules.event_fields. Halimbawa, nagdaragdag ang "postback_event_value": "tutorial_complete" ng tracker code para sa reward na iyon. Gumagana pa rin ang pangalan ng event. Pinapanatili ng AppsFlyer ang hiwalay nitong field na appsflyer_event_name.

Ginagamit ng AppsFlyer CPI ang Integrated Partner setup ng CPAlead. Huwag i-paste sa AppsFlyer ang karaniwang advertiser postback. I-map ang bawat naka-save na numerong event ID bilang partner event identifier. Dapat eksaktong tumugma ang opsyonal na appsflyer_event_name sa pangalan sa SDK; kailangan ng mga partner ID para matukoy ang gantimpala kapag inuulit ang mga pangalan. Isang gantimpala lamang ang maaaring gumamit ng install, at dapat tahasang ipadala ng callback nito ang event_type=install. Suriin ang mga nakalaang template sa Postback Setup. Hindi kino-configure ng pag-save ng campaign sa API ang AppsFlyer.

Pinapalitan ng PATCH na may events ang buong listahan; hindi nagbabago ang listahan kung wala ang field na ito. Panatilihin ang bawat naka-save na event ID, kunin ang kasalukuyang ETag, at ipadala ang If-Match. Pagkatapos ng totoong paglahok o lead, mananatiling naka-lock ang paraan ng pagbabayad, paraan ng tracking, pagkakakilanlan ng AppsFlyer app, at mga detalye ng reward. Dagdag na value para sa karaniwang tracker lamang ang maaaring itama; itinatala ang pagbabagong iyon at hindi nito binabago ang reward. Kopyahin ang campaign kung babaguhin ang mga reward. Hindi nilala-lock ng Guided Test clicks lamang ang event setup.

Maaaring tumakbo ang mga event campaign sa Offerwall V2, Publisher Offers API, at mga direktang link. Kailangan ng Offerwall V2 ng hindi nagbabagong user ID ng publisher sa subid. Pinananatili ng mga bumabalik na kalahok ang kanilang orihinal na click at takdang panahon. Hindi sinusuportahan ng mga klasikong offerwall, locker, at tracking pixel ang mga event campaign na ito.

Maghanda ng mga event campaign gamit ang AI o offer feed

Maaaring maghanda ang Temporary AI Campaign Draft Access ng kumpletong listahan ng mga event para suriin sa karaniwang CPA/CPI form. Hindi ito maaaring gumawa ng live campaign, mag-configure ng tracking, tumanggap ng mga tuntunin o launch package, mag-upload ng larawan, o gumastos ng pera. May bisa ang pribadong link sa loob ng apat na oras. Bago ang matagumpay na deposito ng advertiser, maaari itong mag-save ng hanggang tatlong campaign draft; pagkatapos ng matagumpay na deposito, wala nang kabuuang limitasyon bawat link. Maaaring magkaroon ang bawat account ng hanggang 10 nakabinbing campaign draft na hindi pa tapos, at mawawalan ng bisa ang mga hindi pa tapos na campaign draft pagkatapos ng pitong araw.

Maaaring maghanda ang Offer API Import ng mga listahan mula sa events, event_payouts, o goals; sinusuportahan ng custom mapping ang ibang path. Pinapanatili ang wastong numerong ID mula sa source. Ang source na gumagamit ng text o pangalan ay nangangailangan ng naka-save na tracker value at numerong Event ID na itinalaga ng CPAlead. Bawat reward ay nangangailangan ng pangalan at nakapirming bayad sa USD. Suriin sa preview ang mga ID, tracker value, at buong listahan ng reward. Kung hindi maihanda ng preview ang buong listahan, itama ang mapping bago magpatuloy. Ang pagkuha ng feed ay naghahanda ng bagong form at hindi nag-a-update ng mga kasalukuyang campaign.

Hakbang 4: I-validate bago lumikha

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"

Ang validation ay nagbabalik ng HTTP 200 na may data.valid, isang errors list, at isang warnings list. Maaari pa ring maglaman ang 200 response ng valid: false, kaya dapat suriin ng client ang value na iyon sa halip na ituring na approval ang HTTP status lamang. Bawat issue ay gumagamit ng JSON Pointer path gaya ng /tracking/url, /pricing/payout, o /image_upload_id. Dapat ayusin ng isang AI agent ang tanging tinukoy na field, i-validate muli, at ipakita ang final JSON sa may-ari ng account bago humingi ng create permission.

Ang valid na response ay nangangahulugang pumasa ang payload sa kasalukuyang validation at persistence preflight. Hindi ito pangako ng approval, activation, traffic, conversions, o hinaharap na eligibility. Ang real-time review, funding, account access, holds, schedule, cap, at state checks ay patuloy na nalalapat sa writes at lifecycle actions.

Hakbang 5: Lumikha nang ligtas gamit ang 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"

Ang create, start, at pause ay nangangailangan ng Idempotency-Key na may 8 hanggang 200 nakikitang ASCII characters. Gumamit ng bagong key para sa bawat nilalayong aksyon. Kung pumalya ang koneksyon at hindi mo alam kung natapos ang aksyon, ulitin ang identical na aksyon gamit ang parehong key. Maaaring i-replay ng CPAlead ang natapos na response sa halip na lumikha o maningil nang dalawang beses.

• Parehong key at parehong intensyon: Maaaring i-replay ang natapos na response gamit ang meta.idempotent_replay=true.
• Parehong key pero may binagong detalye: Nagbabalik ang API ng idempotency conflict.
• Parehong external ID pero may binagong detalye: Nagbabalik din ng conflict ang API.
• Nakaprocess pa ang nakaraang request: Maghintay sa naiulat na pagitan, pagkatapos ay ulitin ang parehong intensyon gamit ang parehong key.

Ang opsyonal na external_id ay sarili mong stable reference para sa create operation. Makakatulong ito sa reconciliation, ngunit hindi ito maaaring muling gamitin para sa ibang campaign na nilalayon.

Tatlong campaign bago ang deposit

Ang advertiser account ay maaaring lumikha ng hanggang tatlong kabuuang self-serve CPA, CPI, o CPC campaign bago ang unang matagumpay na advertiser deposit. Binibilang pa rin ang paused, denied, at archived campaign dahil hindi dapat malusutan ng paggawa at pag-archive ng mga throwaway campaign ang limit. Pagkatapos ng matagumpay na deposit, hindi na nalalapat ang partikular na limit na ito sa paglikha; nalalapat pa rin ang karaniwang review, balance, payout, budget, at activation rules.

Basahin at i-filter ang mga campaign

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

Sinusuportahan ng list endpoint ang campaign type, public state, updated_since timestamp, page, at per-page filters. Ang default ng pagination ay 25 campaign at pinapayagan ang hanggang 100 bawat page. Ang mga public state choice ay active, paused, pending_review, paused_for_funding, cap_reached, outside_schedule, denied, archived, at unavailable. Ang archived campaigns ay lumilitaw lamang kapag tahasan mong sinala ang state=archived.

Ang campaign resource ay naglalaman ng ID nito, opsyonal na external ID, version, type, name, creative, tracking, targeting, pricing, schedule, publisher-access setting, image URL, timestamps, at public state. Kasama rin sa state ang review, desired-delivery, delivery-reason, at capability hints. Advisory lamang ang capability hints: kunin ang pinakabagong campaign at hawakan ang totoong response ng operasyon dahil maaaring magbago ang account, funding, review, hold, at schedule conditions.

Mag-update gamit ang ETag version protection

Ang campaign edit ay gumagamit ng optimistic concurrency. Una, kunin ang campaign at i-save ang eksaktong nakapaloob sa panipi na ETag response header. Pagkatapos, ipadala ang value na iyon sa If-Match kasama ng PATCH request. Pinipigilan nito ang isang browser, agent, o integration na tahimik na ma-overwrite ang mas bagong pagbabagong ginawa sa ibang lugar.

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

• Walang If-Match: Nagbabalik ang API ng HTTP 428.
• Luma na ang If-Match: Nagbabalik ang API ng HTTP 412 na may kasalukuyang version metadata.
• Pagkatapos ng 412: Kunin muli ang campaign, ihambing ang mga pagbabago, humingi ng approval, at subukang muli gamit ang bagong ETag.
• Pagkatapos ng malabong resulta ng network: Kunin ang campaign bago magpadala ng isa pang update.

Tinatanggap lang ng PATCH ang public campaign fields. Isinasama nito ang ibinigay na partial object sa kasalukuyang campaign at ini-validate ang kumpletong resulta. Ang ilang edit ay maaaring mangailangan ng isa pang review o makapagpabago ng delivery, kaya basahin ang response state sa tuwing gagawa.

Ang start at pause ay tahasan, walang-body na 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"

Huwag magpadala ng JSON body—kahit {}—sa start o pause. Bago magsimula, kumpirmahin ang campaign, balance, payout o bid, epekto ng launch-package, bansa, device, schedule, cap o budget, landing page, at tracking. Pagkatapos ng response, suriin ang public state; maaaring naka-enable ang campaign ngunit nasa labas ng pang-araw-araw na schedule nito, naka-pause para sa funding, nasa cap nito, o hindi pa rin makapag-deliver.

Mga HTTP status at error na dapat maunawaan ng integration

Mag-automate batay sa HTTP status at stable error.code, hindi lang sa pagkakasulat ng mensahe. Kasama sa validation details ang path, code, at plain-English message. Isama ang response request_id kapag nakikipag-ugnayan sa support.

Rate limits at responsableng retries

Ang Campaign API requests at authentication ay may rate limit para protektahan ang advertisers at ang service. Maaaring magbago ang limits, kaya gamitin ang live OpenAPI schema at response headers sa halip na mag-hard-code ng bilang ng request. Kapag nagbalik ang API ng HTTP 429, maghintay sa Retry-After imbes na agad ulitin ang requests. Gumamit ng pagination, updated_since, at lokal na caching ng hindi nagbago na public requirements para maiwasan ang hindi kailangang mga tawag.

Prompt para sa API-capable AI agent o integration

Ipinapalagay ng prompt na ito na kayang ilakip ng client ang private bearer token sa authenticated HTTPS requests. Ibahagi muna ang gabay at OpenAPI URL, saka i-configure ang token sa private secret settings ng client platform. Huwag maglagay ng tunay na token sa pampublikong prompt na ito. Kung sabihin ng karaniwang AI chat na hindi ito makapagpadala ng authenticated requests, i-revoke ang hindi kailangang token at gamitin sa halip ang 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.

Security checklist para sa AI, MCP, plugins, at code

• Least privilege: Magsimula sa read at validate. Magdagdag lamang ng isang write permission kapag kailangan.
• Maikling expiry: Mas mainam ang 48-hour option para sa isang beses na AI setup task.
• Hiniwalay na tokens: Bigyan ang bawat agent o integration ng sarili nitong may pangalang token.
• Pribadong storage: Panatilihin ang tokens sa secret settings, hindi sa URLs, prompts, logs, analytics, screenshots, o repositories.
• Pagkumpirma ng tao: Humiling ng buod bago mag-create, update, start, o pause.
• Ligtas na retries: Panatilihin ang parehong key at payload pagkatapos ng hindi tiyak na idempotent result.
• Version checks: Huwag kailanman mag-update nang hindi kinukuha ang pinakabagong ETag.
• Response checks: Basahin ang public state at request ID pagkatapos ng bawat write.
• Mag-revoke agad: Alisin ang access mula sa Advertising API page kapag tapos na ang trabaho o maaaring nag-leak ang token.

Mga madalas itanong

Magagamit ko ba ang Full Campaign API sa karaniwang ChatGPT?

Magagamit lamang kapag may naka-configure na GPT Action ang ChatGPT o ibang authenticated integration na kayang magpadala ng bearer token sa Authorization header. Karaniwang hindi iyon magagawa ng normal na chat. Gamitin sa halip ang Temporary AI Campaign Draft Access. Inactive campaign draft lamang ang maaari nitong ihanda at i-save; ikaw ang magrerepaso at tatapos sa mga ito sa CPAlead.

Saan ko makikita ang aking CPAlead API key?

Para sa Campaign API, ang credential ay tinatawag na Campaign API token. Mag-sign in at buksan ang Advertising → Setup → API, pagkatapos gamitin ang Create a token. Kopyahin agad ang token dahil isang beses lamang ipinapakita ng CPAlead ang buong value.

Kayang lumikha ng API ng CPA, CPI, at CPC campaigns?

Oo. Bawat type ay may mahigpit ngunit magkaibang JSON shape. Kunin ang requirements para sa type na iyon bago ito buuin.

Maaari ba akong mag-validate nang hindi pinapayagang lumikha ang AI ng kahit ano?

Oo. Bigyan ang token ng campaigns:validate lamang, at opsyonal ang campaigns:read. Hindi kailangan ng create permission para sa requirements at validation.

Ang valid na response ba ay nangangahulugang aprubado ang campaign?

Hindi. Nangangahulugan ito na pumasa ang kasalukuyang payload sa validation at preflight. Nalalapat pa rin ang review, funding, account access, holds, caps, schedules, at real-time state.

Puwede bang agad magsimula ang create ng campaign?

Maaaring oo, depende sa account at campaign. Maaari rin itong pumasok sa review. Palaging suriin ang ibinalik na public state. Maaari ring maningil ang CPA o CPI activation ng hindi pa nababayarang napiling launch package.

Maaari ba akong mag-upload ng image mula sa remote URL?

Hindi. I-upload ang image file sa pamamagitan ng POST /images. Nagbabalik ang CPAlead ng pansamantala, single-use na image ID.

Maaari ba akong lumikha ng maraming offers nang sabay-sabay?

Walang bulk-create operation. I-validate at lumikha ng isang campaign bawat request, gumamit ng natatanging external ID at idempotency key, at sundin ang rate limits at mga patakaran sa account creation.

Maaari bang mag-archive o mag-delete ang API ng campaign?

Hindi. Ang kasalukuyang public API ay maaaring magsimula at mag-pause ng karapat-dapat na campaigns ngunit hindi nagbibigay ng archive o delete. Gamitin ang advertiser dashboard para sa archival.

Bakit tumanggap ng HTTP 412 ang aking update?

Nagbago ang campaign pagkatapos mo itong kunin. Kunin ito muli, suriin ang pinakabagong data, i-merge ang nilalayon mong pagbabago, at subukang muli gamit ang bagong ETag.

Bakit nagbalik ng HTTP 409 ang create?

Basahin ang stable error code. Kabilang sa posibleng public reasons ang muling ginamit na idempotency key o external ID na may ibang data, isang naunang request na nakaprocess pa, ang tatlong-campaign na pre-deposit limit, mga restriksiyon sa funding o account, isang hold, o isang state conflict.

Dapat bang kopyahin ng application ko ang field limits mula sa artikulong ito?

Hindi. Ipinaliliwanag ng artikulong ito ang workflow. Dapat basahin ng iyong application ang live requirements at OpenAPI schema upang manatiling awtoritatibo ang kasalukuyang values.

Machine-friendly na Campaign API fact sheet

Magsimula sa read at validate

Dinisenyo ang Campaign API upang ang advertiser ay makapagsimula nang may pag-iingat. Bigyan ang isang pinagkakatiwalaang agent ng public guide at schema, bigyan ng read at validation access, at hayaan itong maghanda ng request nang hindi binabago ang account. Kapag tama na ang JSON at nauunawaan ng may-ari ang posibleng review, delivery, at financial effects, idagdag lamang ang write permission na kailangan para sa susunod na kumpirmadong aksyon.

Buksan ang Campaign API sa Advertiser API Center upang lumikha ng token, o buksan ang public Campaign API OpenAPI schema upang suriin ang kasalukuyang contract. Ang Publisher API documentation ay hiwalay at tumatalakay sa pagkuha ng offers at reporting ng publishers. Kung hindi malinaw ang isang response, panatilihing pribado ang token at makipag-ugnayan sa Advertiser Support gamit ang public request ID at campaign ID.

Napansin mo ba ang isang pagkakamali o isang aspeto ng post na ito na nangangailangan ng pagwawasto? Mangyaring ibigay ang link ng post at makipag-ugnayan sa amin. Pinahahalagahan namin ang iyong feedback at agarang aayusin ang isyu.