CPAlead Full Campaign API: Creați și gestionați oferte

CPAlead Full Campaign API permite unui advertiser self-service verificat să folosească cod, un agent AI cu acces API, un server MCP, un GPT Action sau un plugin pentru a lucra cu campanii CPA, CPI și CPC. În funcție de permisiunile acordate, un client autorizat poate citi cerințele actuale, valida o campanie completă înainte de salvare, încărca un material publicitar, crea o campanie, lista și prelua campanii, edita o campanie cu protecția versiunii și porni sau întrerupe temporar, în mod explicit, o campanie eligibilă.

Acesta este companionul de automatizare pentru dashboard-ul obișnuit al advertiserului. Dacă vrei mai întâi o explicație câmp cu câmp a tipurilor de campanii, tracking-ului, targetării, payout-urilor, cap-urilor, finanțării, revizuirii și lansării, citește Cum să faci publicitate pe CPAlead în 2026: adaugă și lansează primul tău offer. Folosește acest articol când ești pregătit să exprimi acea configurare ca JSON structurat și acțiuni API controlate.

Ce poate face Full Campaign API

API-ul nu oferă în prezent o operațiune de arhivare, ștergere, creare în masă sau toggle generic. Lucrările de arhivare sau ștergere rămân un flux din dashboard. Pornirea și pauzarea sunt acțiuni separate, astfel încât o persoană sau un client AI să poată cere o confirmare clară înainte de a schimba livrarea.

Alegeți între Temporary AI Campaign Draft Access, Full Campaign API și Offer API Import

• Temporary AI Campaign Draft Access: Pentru ChatGPT obișnuit și conversații AI similare. Înainte de prima depunere reușită a advertiserului, un link privat valabil patru ore poate valida și salva până la trei schițe de campanie inactive. După o depunere reușită a advertiserului, linkul nu mai are o limită totală de schițe de campanie. Fiecare cont poate avea simultan până la 10 schițe de campanie nefinalizate în așteptare. Nu poate vedea sau gestiona campanii existente, încărca, accepta termeni sau pachete, cheltui fonduri, trimite, porni, întrerupe temporar sau activa. Deschideți Temporary AI Campaign Draft Access.
• Full Campaign API: Pentru un agent cu acces API, GPT Action, un server MCP, un plugin sau o integrare care poate proteja un bearer token. Permisiunile acordate pot valida, încărca, crea, citi, edita, porni și întrerupe temporar campanii. Deschideți Full Campaign API.
• Offer API Import: Un flux de lucru separat în panoul advertiserului, care preia oferte dintr-un feed extern compatibil și mapează câmpurile acestuia în CPAlead. Deschideți Offer API Import.

Folosiți opțiunea protejată pentru schițe de campanie atunci când o conversație AI obișnuită vă ajută să pregătiți o ofertă nouă. Folosiți Full Campaign API atunci când un client autentificat are nevoie de capabilități structurate pentru gestionarea campaniilor. Folosiți Offer API Import atunci când CPAlead trebuie să preia un feed compatibil. Nu oferiți niciunui instrument un acces mai larg decât are nevoie pentru sarcina sa.

Creează un token Campaign API

1. Autentifică-te într-un cont advertiser self-serve verificat.
2. Deschide Setup → API, apoi selectează Campaign API.
3. Dă tokenului un nume ușor de recunoscut, precum „Campaign validator” sau „My MCP agent.”
4. Alege o expirare. Opțiunea de 48 de ore este recomandată pentru configurarea AI; opțiunile de 30 de zile, 90 de zile și 365 de zile sunt, de asemenea, disponibile.
5. Selectează doar permisiunile de care clientul are nevoie.
6. Creează tokenul și copiază-l imediat. CPAlead nu poate afișa din nou tokenul complet după reîncărcarea paginii.
7. Stochează-l în configurarea secretă a clientului de încredere și revocă-l când sarcina se încheie.

Un advertiser poate avea până la 10 tokenuri Campaign API active. Folosește tokenuri separate pentru integrări separate, astfel încât să poți limita permisiunile, verifica utilizarea și revoca o integrare fără a o întrerupe pe alta.

Unde să creezi tokenul Campaign API

Un token Campaign API este credențialul API privat trimis în header-ul Authorization. Nu este parola ta CPAlead și nu poate fi folosit pentru a te autentifica în dashboard-ul CPAlead. După autentificare, deschide Setup → API, selectează Campaign API și folosește formularul Create a token.

URL de bază, autentificare și formatul răspunsului

Cereri autentificate trimit tokenul o singură dată în header-ul HTTP authorization. Nu-l pune niciodată în URL sau în query string.

Authorization: Bearer YOUR_TOKEN
Accept: application/json

Pentru exemplele curl de mai jos, o configurare mai sigură este să stochezi header-ul de autorizare într-un fișier local de configurare curl, exclus din controlul sursei și care poate fi citit doar de tine:

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

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

Un răspuns de succes are un obiect sau o listă data, plus meta. Metadatele includ un request_id și versiunea curentă a schemei și pot include paginare, o versiune a resursei sau un flag de reapelare idempotentă. Un răspuns de eroare are un obiect error, plus meta. Salvează request_id public când depanezi cu suportul, dar nu trimite niciodată tokenul bearer către suport.

Pasul 1: Citește cerințele live

Cerințele sunt sursa de adevăr pentru ceea ce contul poate trimite acum. Ele includ versiunea curentă a schemei și a termenilor, eligibilitatea pentru crearea contului, țările și dispozitivele suportate, limitele câmpurilor, regulile pentru tipurile de campanii, intervalele de preț, programele, pachetele de lansare, cerințele de tracking, regulile pentru imagini și fluxul de lucru recomandat.

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

Folosește type=CPA, type=CPI sau type=CPC pentru a limita răspunsul. Nu fixa în cod o versiune a schemei, o versiune a termenilor, o limită de payout, un bid, un buget, un pachet de lansare, o țară, un dispozitiv sau o versiune minimă a aplicației dintr-un exemplu vechi. Preia din nou cerințele când serverul raportează că o valoare sau o versiune este depășită.

Cele trei tipuri de campanii

• CPA: Plătește pentru o singură acțiune sau pentru mai multe evenimente. URL-ul de urmărire trebuie să conțină {CLICK_ID}. Un URL de previzualizare, o limită zilnică și un pachet de lansare fac parte din cererea de creare. Pentru o campanie cu plată unică este obligatoriu un obiectiv de conversie; o campanie cu evenimente definește fiecare acțiune recompensată în lista sa de evenimente.
• CPI: Plătește pentru o instalare sau o acțiune în aplicație ori pentru mai multe evenimente. Folosește {CLICK_ID} și adaugă opțiuni specifice aplicațiilor, precum platforma dispozitivului, metoda de urmărire, versiunile de sistem de operare acceptate și gestionarea proxy-urilor. Adăugați un eveniment explicit de instalare dacă instalările trebuie plătite într-o campanie cu evenimente.
• CPC: Plătește pentru un click valid. Folosește un bid și un buget zilnic în locul unui payout de conversie, al unui daily cap și al unui launch package.

Toate valorile monetare din API-ul pentru campanii sunt în USD, iar programările API folosesc UTC. Pentru CPA și CPI, o plată sub $10.00 necesită o limită zilnică de cel puțin 20. O plată de $10.00 sau mai mult permite o limită zilnică de numai 5. Pentru o campanie cu evenimente, folosiți suma tuturor plăților pentru evenimente la aplicarea acestor reguli privind limita minimă. Citiți cerințele actuale înainte de a alege prețurile și limitele.

Pasul 2: Încarcă o imagine pentru campanie

Cererea de creare nu acceptă o URL de imagine remote. Încarcă mai întâi fișierul ca date de formular multipart, apoi plasează ID-ul temporar al imaginii returnat în image_upload_id.

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

• Surse acceptate: JPG, JPEG, PNG, GIF, BMP și WebP.
• Dimensiunea maximă a fișierului: 2 MiB.
• Lățimea și înălțimea sursei: fiecare trebuie să fie între 200 și 4096 pixeli.
• Rezultatul stocat: un crop WebP 200×200, fără metadate și fără animație.
• Durata de viață a uploadului nefolosit: 24 de ore.
• Limită de uploaduri restante: până la 25 de uploaduri de imagini nefolosite curente.
• Utilizare: o singură creare de campanie sau actualizare de imagine. Încarcă din nou pentru o campanie diferită.

Validarea poate verifica dacă un ID de imagine aparține contului tău și rămâne utilizabil fără a-l consuma. Scrierea reușită a campaniei îl consumă. Reapelarea aceleiași creări finalizate cu aceeași cheie idempotentă returnează rezultatul stocat; nu creează o a doua campanie din imaginea consumată.

Pasul 3: Construiește JSON-ul complet al campaniei

API-ul folosește obiecte JSON stricte. Câmpurile necunoscute sunt respinse, nu ignorate în tăcere. Acest lucru face o integrare AI mai sigură: o proprietate scrisă greșit sau inventată devine o problemă vizibilă de validare, nu o setare accidentală a campaniei.

Următorul exemplu CPA este un șablon, nu o campanie gata de trimis. Înlocuiește fiecare valoare COPY_FROM_REQUIREMENTS, ID-ul imaginii, URL-ul, payout-ul, țara, cap-ul și descrierea publică cu valori revizuite pentru oferta ta reală.

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

Regula importantă de tracking pentru CPA și CPI

URL-ul de tracking trebuie să conțină macro-ul exact {CLICK_ID}. Trackerul sau platforma ta de afiliere trebuie să salveze valoarea numerică pe care CPAlead o inserează acolo și să returneze acel click ID salvat către postback-ul advertiserului CPAlead după conversie. Nu plasa URL-ul de postback al CPAlead în URL-ul de tracking al campaniei. Pentru explicația completă click-to-postback, folosește ghidul public de postback pentru advertiser.

Alegeți o plată unică sau mai multe evenimente recompensate

CPA și CPI acceptă conversion_mode cu valorile single și events. Citiți conversion_modes și event_rules din cerințe înainte de a alege. CPC plătește pentru clicuri și nu acceptă recompense pentru evenimente.

Cu o singură acțiune plătită, participantul primește o plată pentru conversie. Cu mai multe evenimente recompensate, stabiliți o plată fixă separată în USD pentru fiecare acțiune. De exemplu, plătiți $0.50 pentru crearea unui cont și $1.25 pentru finalizarea tutorialului. Totalul maxim este de $1.75 per participant; acesta nu este o plată suplimentară.

Pentru o cerere CPA completă precum cea din exemplul de mai sus, folosiți aceste câmpuri de eveniment și aceste prețuri. Păstrați celelalte câmpuri obligatorii ale campaniei. Pentru CPI, alegeți și o platformă de aplicație și o metodă de urmărire acceptate. Înlocuiți toate acțiunile, prețurile și opțiunile de direcționare din exemplu cu propriile alegeri verificate.

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

O schemă de recompense conține 1–10 evenimente. Fiecare are nevoie de un nume și de o plată pozitivă cu cel mult două zecimale; instrucțiunile de finalizare sunt opționale. ID-urile evenimentelor noi pot fi omise, astfel încât CPAlead să le atribuie. Păstrați ID-urile numerice returnate pentru actualizări și postback-uri ulterioare. La salvarea evenimentelor, pricing.payout poate fi omis; dacă este furnizat, trebuie să fie egal cu suma tuturor plăților pentru evenimente. creative.conversion_goal este opțional pentru campaniile cu evenimente, iar targeting.tools_only trebuie să fie false.

Fiecare eveniment poate fi plătit o singură dată pentru fiecare participant, în orice ordine, în termen de 30 de zile de la clicul inițial. Limita zilnică numără un participant la primul său eveniment plătit. Evenimentele ulterioare nu sunt numărate din nou. Întreruperea campaniei sau atingerea limitei oprește traficul nou, dar nu anulează recompensele eligibile rămase de plătit. Păstrați suficiente fonduri pentru ele; finalizările în așteptare pot depăși limita de trafic a unei zile.

Urmăriți și actualizați campaniile cu evenimente

Pentru postback-urile standard, trimite propriul ID de postback, valoarea click_id inițială salvată și o valoare care identifică recompensa realizată. Include campaign_id pentru protecție suplimentară; trebuie să corespundă campaniei clicului inițial. Folosește URL-ul generat pentru cont și nu inventa niciodată ID-uri.

Un sold insuficient returnează HTTP 503 cu low_balance. Adaugă fonduri și reîncearcă același eveniment după intervalul Retry-After. Folosește testul ghidat înainte de a trimite trafic.

Pentru sistemele de urmărire standard, API-ul complet de campanii și accesul temporar AI pentru schițe de campanie acceptă câmpul opțional de eveniment postback_event_value când acesta apare în event_rules.event_fields. De exemplu, "postback_event_value": "tutorial_complete" adaugă un cod de urmărire pentru recompensa respectivă. Numele evenimentului continuă să funcționeze. AppsFlyer păstrează câmpul său separat appsflyer_event_name.

CPI cu AppsFlyer folosește configurarea de partener integrat CPAlead. Nu introduceți postback-ul standard al advertiserului în AppsFlyer. Mapați fiecare ID numeric de eveniment salvat la identificatorul de eveniment al partenerului. Câmpul opțional appsflyer_event_name trebuie să corespundă exact numelui din SDK; numele repetate necesită ID-uri de partener pentru identificarea recompensei. O singură recompensă poate folosi install, iar callback-ul acesteia trebuie să trimită explicit event_type=install. Consultați șabloanele dedicate din configurarea postback-ului. Salvarea unei campanii prin API nu configurează AppsFlyer.

Un PATCH care conține events înlocuiește întreaga listă; omiterea câmpului păstrează lista. Păstrează fiecare ID de eveniment salvat, citește ETag-ul actual și trimite If-Match. După o participare reală sau o conversie, modul de plată, metoda de urmărire, identitatea aplicației AppsFlyer și detaliile recompenselor rămân blocate. Poate fi corectată doar o valoare suplimentară pentru urmărirea standard; modificarea este înregistrată și nu schimbă recompensa. Copiază campania pentru a-i schimba recompensele. Clicurile din testul ghidat, singure, nu blochează configurarea evenimentelor.

Campaniile cu evenimente pot rula prin Offerwall V2, API-ul de oferte pentru publisheri și linkuri directe. Offerwall V2 necesită un ID stabil de utilizator al publisherului în subid. Participanții care revin își păstrează clicul inițial și termenul-limită. Offerwall-urile clasice, lockerele și pixelii de urmărire nu acceptă aceste campanii cu evenimente.

Pregătiți campanii cu evenimente folosind AI sau un flux de oferte

Accesul temporar AI la ciorne de campanii poate pregăti o schemă completă de evenimente pentru verificare în formularul CPA/CPI obișnuit. Nu poate crea o campanie activă, configura urmărirea, accepta condiții sau pachete de lansare, încărca o imagine ori cheltui bani. Un link privat este valabil patru ore. Înainte de o depunere reușită a advertiserului, poate salva până la trei ciorne de campanii; după o depunere reușită, nu există o limită totală per link. Fiecare cont poate avea până la 10 ciorne de campanii nefinalizate în așteptare, iar ciornele nefinalizate expiră după șapte zile.

Importul de oferte prin API poate pregăti liste din events, event_payouts sau goals; corespondența personalizată acceptă alte căi. ID-urile numerice valide din sursă sunt păstrate. Sursele cu text sau nume necesită o valoare de urmărire salvată și un ID numeric de eveniment atribuit de CPAlead. Fiecare recompensă necesită un nume și o plată fixă în USD. Verifică ID-urile, valorile de urmărire și lista completă în previzualizare. Dacă previzualizarea nu poate pregăti întreaga listă, corectează corespondența înainte de a continua. Citirea unui flux pregătește un formular nou și nu actualizează campaniile existente.

Pasul 4: Validează înainte de creare

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"

Validarea returnează HTTP 200 cu data.valid, o listă errors și o listă warnings. Un răspuns 200 poate conține totuși valid: false, așa că un client trebuie să inspecteze acea valoare în loc să considere doar statusul HTTP ca aprobare. Fiecare problemă folosește o cale JSON Pointer, cum ar fi /tracking/url, /pricing/payout sau /image_upload_id. Un agent AI ar trebui să repare doar câmpul indicat, să valideze din nou și să arate JSON-ul final proprietarului contului înainte de a solicita permisiunea de creare.

Un răspuns valid înseamnă că payload-ul trece validarea curentă și preflight-ul de persistență. Nu este o promisiune de aprobare, activare, trafic, conversii sau eligibilitate viitoare. Revizuirea în timp real, finanțarea, accesul la cont, reținerile, programul, cap-ul și verificările de stare se aplică în continuare la scrieri și acțiuni de ciclu de viață.

Pasul 5: Creează în siguranță cu 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"

Crearea, pornirea și pauzarea necesită un Idempotency-Key care conține între 8 și 200 de caractere ASCII vizibile. Folosește o cheie nouă pentru fiecare acțiune intenționată. Dacă conexiunea eșuează și nu știi dacă acțiunea s-a finalizat, reîncearcă acțiunea identică cu aceeași cheie. CPAlead poate reda răspunsul finalizat în loc să creeze sau să taxeze de două ori.

• Aceeași cheie și aceeași intenție: Răspunsul finalizat poate fi redat cu meta.idempotent_replay=true.
• Aceeași cheie cu detalii schimbate: API-ul returnează un conflict de idempotency.
• Același external ID cu detalii schimbate: API-ul returnează, de asemenea, un conflict.
• Cererea anterioară încă se procesează: Așteaptă intervalul raportat, apoi reîncearcă aceeași intenție cu aceeași cheie.

external_id opțional este referința ta stabilă pentru operațiunea de creare. Poate face reconcilierea mai ușoară, dar nu trebuie reutilizat pentru o altă campanie intenționată.

Trei campanii înainte de un depozit

Un cont advertiser poate crea până la trei campanii self-serve CPA, CPI sau CPC în total înainte de primul depozit reușit al advertiserului. Campaniile în pauză, respinse și arhivate încă contează, deoarece crearea și arhivarea unor campanii de unică folosință nu trebuie să ocolească limita. După un depozit reușit, această limită specifică de creare nu se mai aplică; regulile obișnuite de revizuire, sold, payout, buget și activare se aplică în continuare.

Citește și filtrează campaniile

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

Endpoint-ul de listare suportă tipul campaniei, starea publică, un timestamp updated_since, pagina și filtre per page. Paginarea are implicit 25 de campanii și permite până la 100 pe pagină. Opțiunile de stare publică sunt active, paused, pending_review, paused_for_funding, cap_reached, outside_schedule, denied, archived și unavailable. Campaniile arhivate apar doar când filtrezi explicit cu state=archived.

O resursă de campanie include ID-ul ei, ID-ul extern opțional, versiunea, tipul, numele, creative-ul, tracking-ul, targetarea, prețurile, programul, setarea de acces pentru publisheri, URL-ul imaginii, timestamp-urile și starea publică. Starea include, de asemenea, indicii despre review, desired-delivery, delivery-reason și capabilități. Indiciile de capabilitate sunt consultative: recuperează cea mai recentă campanie și gestionează răspunsul real al operațiunii, deoarece condițiile de cont, finanțare, revizuire, hold și program se pot schimba.

Actualizează cu protecție de versiune ETag

Editările de campanie folosesc concurență optimistă. Mai întâi recuperează campania și salvează exact header-ul de răspuns ETag între ghilimele. Apoi trimite acea valoare în If-Match cu cererea PATCH. Acest lucru împiedică un browser, agent sau integrare să suprascrie în tăcere o schimbare mai nouă făcută în altă parte.

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

• Fără If-Match: API-ul returnează HTTP 428.
• If-Match vechi: API-ul returnează HTTP 412 cu metadatele versiunii curente.
• După un 412: Recuperează din nou campania, compară modificările, cere aprobarea și reîncearcă cu noul ETag.
• După un rezultat de rețea neclar: Recuperează campania înainte de a trimite o altă actualizare.

PATCH acceptă doar câmpuri publice ale campaniei. Acesta îmbină obiectul parțial furnizat cu campania curentă și validează rezultatul complet. Unele editări pot necesita o altă revizuire sau pot modifica livrarea, așa că citește starea răspunsului de fiecare dată.

Pornirea și pauzarea sunt acțiuni explicite, fără body

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

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

Nu trimite un body JSON — nici măcar {} — pentru start sau pause. Înainte de a porni, confirmă campania, soldul, payout-ul sau bid-ul, efectul launch package-ului, țările, dispozitivele, programul, cap-ul sau bugetul, landing page-ul și tracking-ul. După răspuns, inspectează starea publică; o campanie poate fi activată, dar în afara programului zilnic, în pauză din cauza finanțării, la cap-ul ei sau altfel incapabilă să livreze.

Statusurile HTTP și erorile pe care o integrare trebuie să le înțeleagă

Automatizează pe baza statusului HTTP și a error.code stabil, nu doar pe formularea mesajului. Detaliile de validare includ o cale, un cod și un mesaj în limbaj simplu. Include request_id din răspuns când contactezi suportul.

Limite de rată și reîncercări responsabile

Cererile Campaign API și autentificarea sunt supuse limitelor de rată pentru a proteja advertiserii și serviciul. Limitele se pot schimba, așa că folosește schema OpenAPI live și header-ele de răspuns, în loc să fixezi în cod un număr de cereri. Când API-ul returnează HTTP 429, așteaptă Retry-After în loc să repeți imediat cererile. Folosește paginarea, updated_since și cache-ul local pentru cerințele publice neschimbate pentru a evita apelurile inutile.

Prompt pentru un agent AI sau o integrare cu acces API

Acest prompt presupune că acel client poate atașa un bearer token privat la cereri HTTPS autentificate. Distribuiți mai întâi ghidul și URL-ul OpenAPI, apoi configurați tokenul în setările private pentru secrete ale platformei client. Nu introduceți un token real în acest prompt public. Dacă o conversație AI obișnuită spune că nu poate face cereri autentificate, revocați tokenul inutil și folosiți în schimb 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.

Checklist de securitate pentru AI, MCP, pluginuri și cod

• Privilegii minime: Începe cu read și validate. Adaugă o singură permisiune de scriere doar când este nevoie.
• Expirare scurtă: Preferă opțiunea de 48 de ore pentru o sarcină de configurare AI o singură dată.
• Tokenuri separate: Dă fiecărui agent sau fiecărei integrări propriul token numit.
• Stocare privată: Păstrează tokenurile în setări secrete, nu în URL-uri, prompturi, loguri, analitice, capturi de ecran sau depozite.
• Confirmare umană: Cere un rezumat înainte de create, update, start sau pause.
• Reîncercări sigure: Păstrează aceeași cheie și același payload după un rezultat idempotent incert.
• Verificări de versiune: Nu actualiza niciodată fără a recupera cel mai recent ETag.
• Verificări ale răspunsului: Citește starea publică și request ID-ul după fiecare scriere.
• Revocare promptă: Elimină accesul din pagina Advertising API când sarcina s-a terminat sau un token ar fi putut fi divulgat.

Întrebări frecvente

Pot folosi Full Campaign API în ChatGPT obișnuit?

Numai atunci când ChatGPT are un GPT Action configurat sau altă integrare autentificată care poate trimite bearer token într-un Authorization header. De obicei, o conversație obișnuită nu poate face acest lucru. Folosiți în schimb Temporary AI Campaign Draft Access. Acesta poate doar să pregătească și să salveze schițe de campanie inactive; dvs. le verificați și le finalizați în CPAlead.

Unde găsesc cheia mea API CPAlead?

Pentru Campaign API, credențialul se numește Campaign API token. Autentifică-te și deschide Advertising → Setup → API, apoi folosește Create a token. Copiază tokenul imediat, deoarece CPAlead afișează valoarea completă doar o singură dată.

Poate API-ul să creeze campanii CPA, CPI și CPC?

Da. Fiecare tip are o formă JSON strictă, dar diferită. Preia cerințele pentru acel tip înainte de a-l construi.

Pot valida fără a permite unui AI să creeze ceva?

Da. Oferă tokenului doar campaigns:validate și, opțional, campaigns:read. Cerințele și validarea nu necesită permisiune de creare.

Un răspuns valid înseamnă că campania este aprobată?

Nu. Înseamnă că payload-ul curent trece validarea și preflight-ul. Revizuirea, finanțarea, accesul la cont, hold-urile, cap-urile, programele și starea în timp real se aplică în continuare.

Poate create să pornească imediat o campanie?

Poate, în funcție de cont și campanie. Poate însă intra și în revizuire. Inspectează întotdeauna starea publică returnată. Activarea CPA sau CPI poate, de asemenea, taxa un launch package selectat și neplătit.

Pot încărca o imagine dintr-o URL remote?

Nu. Încarcă fișierul imaginii prin POST /images. CPAlead returnează un ID temporar de imagine, utilizabil o singură dată.

Pot crea multe oferte deodată?

Nu există o operațiune de creare în masă. Validează și creează o singură campanie per cerere, folosește un external ID și o cheie idempotentă distincte și respectă limitele de rată și regulile de creare ale contului.

Poate API-ul să arhiveze sau să șteargă o campanie?

Nu. API-ul public actual poate porni și pune în pauză campanii eligibile, dar nu oferă arhivare sau ștergere. Folosește dashboard-ul advertiserului pentru arhivare.

De ce actualizarea mea a primit HTTP 412?

Campania s-a schimbat după ce ai recuperat-o. Ia-o din nou, revizuiește cele mai noi date, îmbină schimbarea dorită și reîncearcă cu noul ETag.

De ce create a returnat HTTP 409?

Citește codul stabil de eroare. Posibile motive publice includ o cheie idempotentă sau un external ID reutilizat cu date diferite, o cerere anterioară încă în procesare, limita de trei campanii înainte de depozit, restricții de finanțare sau cont, un hold sau un conflict de stare.

Ar trebui aplicația mea să copieze limitele câmpurilor din acest articol?

Nu. Acest articol explică fluxul de lucru. Aplicația ta ar trebui să citească cerințele live și schema OpenAPI, astfel încât valorile curente să rămână autoritative.

Fișă de informații Campaign API, prietenoasă pentru mașini

Începe cu read și validate

API-ul de campanii este proiectat astfel încât un advertiser să poată începe cu prudență. Oferă unui agent de încredere ghidul public și schema, acordă acces de citire și validare și lasă-l să pregătească o cerere fără a modifica contul. Când JSON-ul este corect și proprietarul înțelege posibilele efecte asupra revizuirii, livrării și finanțelor, adaugă doar permisiunea de scriere necesară pentru următoarea acțiune confirmată.

Deschide Campaign API în Advertiser API Center pentru a crea un token sau deschide schema publică OpenAPI a Campaign API pentru a inspecta contractul curent. Documentația Publisher API este separată și acoperă publisherii care recuperează oferte și raportează. Dacă un răspuns nu este clar, păstrează tokenul privat și contactează Advertiser Support cu request ID-ul public și campaign ID-ul.

Ați observat o eroare sau un aspect al acestei postări care necesită corecție? Vă rugăm să oferiți linkul postării și luați legătura cu noi. Apreciem părerea dvs. și vom aborda problema prompt.