API-ul pentru campanii de publicitate CPAlead: creați și gestionați oferte

API-ul de campanii CPAlead permite unui advertiser self-serve verificat să folosească cod, un agent AI, un server MCP sau un plugin pentru a lucra cu campanii CPA, CPI și CPC. Un client autorizat poate citi cerințele curente ale campaniei, valida o campanie completă înainte de salvare, încărca un creative, crea o campanie, lista și recupera campanii, edita o campanie cu protecție de versiune și porni sau pune în pauză 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 API-ul de campanii

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.

Campaign API și importul Offer API sunt diferite

• Campaign API: Un API bearer-token cu scope, care validează, creează, citește, editează, pornește și pune în pauză campanii în contul tău de advertiser.
• Offer API Import: Un flux separat din dashboard-ul advertiserului, care citește oferte dintr-un feed extern compatibil și le mapează câmpurile în CPAlead.

Advertiser API Center păstrează aceste instrumente pe pagini separate. Autentifică-te, deschide Setup → API, apoi alege instrumentul care se potrivește sarcinii tale. Folosește Campaign API atunci când aplicația ta, agentul, serverul MCP sau pluginul are deja datele ofertei și are nevoie de o modalitate structurată de a lucra cu CPAlead. Folosește importatorul atunci când CPAlead trebuie să preia și să mapeze un feed de oferte suportat. Nu oferi unei integrări un token mai larg decât cere sarcina ei.

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 acțiune declarată. URL-ul de tracking trebuie să conțină {CLICK_ID}, iar un preview URL, un conversion goal, un daily cap și un launch package fac parte din forma de creare.
• CPI: Plătește pentru un install sau pentru un eveniment de aplicație configurat. Folosește {CLICK_ID} și adaugă opțiuni orientate pe aplicație, cum ar fi platforma dispozitivului, metoda de tracking, versiunea iOS suportată și gestionarea proxy-urilor.
• 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 Campaign API sunt în USD, iar programările din API folosesc UTC. Citește cerințele returnate și prezintă aceste informații persoanei care aprobă solicitarea.

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.

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.

Un prompt pe care îl poți oferi unui agent AI de încredere

Distribuie mai întâi ghidul și URL-ul OpenAPI. Configurează tokenul în setările private de secret ale platformei agentului; nu introduce un token real în acest prompt.

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

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.