Ghid API Taboola: Endpoint-uri Backstage, Autentificare și Utilizări Reale

API-ul Taboola — oficial API-ul Backstage — este interfața REST a Taboola pentru advertiseri. Te autentifici cu credentiale client OAuth 2.0, apoi citești și scrii tot ce poți atinge în Consola de Anunțuri: campanii, elemente creative, targeting, bugete și rapoarte de performanță, toate sub https://backstage.taboola.com/backstage/api/1.0/{account_id}/…. Este stratul pe care îl folosesc cumpărătorii media pentru a automatiza modificările de ofertă și buget, a încărca creativități în bloc, a sincroniza cheltuielile într-un depozit și a construi motoarele de reguli pe care interfața Taboola nu le oferă. Ceea ce nu expune în mod deliberat sunt datele altcuiva — pentru vederea competitivă a rețelei ai nevoie de un API complet diferit, pe care îl acoperim la final.

Ce acoperă API-ul Backstage#

Backstage reflectă consola de advertiser aproape unu-la-unu. În practică, patru zone fac cea mai mare parte a muncii:

• Gestionarea campaniilor. Creează, citește, actualizează și pune pe pauză campanii; setează CPC-uri, bugete zilnice și totale, targeting geo/platformă și blocarea site-urilor. Orice ai schimba manual la 7 dimineața după ce verifici numerele din noapte poate fi un script în schimb.
• Elemente (creativități). Fiecare campanie conține elemente — unitățile imagine-plus-titlu care servesc efectiv. API-ul îți permite să adaugi elemente în bloc, să le actualizezi starea și să citești starea de revizuire per element, ceea ce este modul în care conturile mari lansează zeci de variante creative fără să atingă interfața. (Dacă încă îți configurezi primele campanii manual, începe cu ghidul nostru de configurare a campaniilor Taboola — API-ul presupune că deja cunoști conceptele consolei.)
• Raportarea. Endpoint-uri de performanță agregate segmentate pe dimensiuni — zi, campanie, site, țară, platformă, element — materia primă pentru orice optimizare automatizată.
• Dicționare. Endpoint-uri de căutare pentru enumerările de care depinde totul: coduri de țară, platforme, segmente de audiență.

Accesul vine ca un client ID și un secret emis pentru contul tău — solicitat istoric prin managerul de cont Taboola — și referința oficială Backstage este sursa de adevăr pentru formele endpoint-urilor curente și procedurile de acces. Căile endpoint-urilor de mai jos sunt curente la momentul scrierii; verifică în referință înainte de a construi.

Autentificare: credentiale client la bearer token#

Backstage folosește fluxul standard OAuth 2.0 client-credentials. Schimbă ID-ul și secretul pentru un token:

curl -X POST "https://backstage.taboola.com/backstage/oauth/token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials"

Răspunsul conține un access_token pe care îl trimiți ca header bearer la fiecare apel:

curl "https://backstage.taboola.com/backstage/api/1.0/users/current/allowed-accounts" \
  -H "Authorization: Bearer YOUR_TOKEN"

Acel apel allowed-accounts este prima cerere corectă: returnează valorile account_id (ID-uri numerice și nume lizibile) de care are nevoie fiecare alt endpoint în calea sa. Token-urile expiră — cache-ază unul și reîmprospătează la un 401 în loc să generezi un token nou pe cerere, atât pentru latență, cât și pentru că cererile de token sunt limitate la rată mai agresiv decât cererile de date.

Endpoint-urile pe care le vei folosi de fapt#

Endpoint-urile de raportare iau parametrii de interogare start_date și end_date plus filtre opționale, iar segmentul dimension (day, campaign_breakdown, site_breakdown, country_breakdown, platform_breakdown…) decide segmentarea. site_breakdown este cel care contează cel mai mult pentru optimizare: este fluxul de performanță per publisher care alimentează automatizarea listelor de blocare.

Ce automatizează efectiv cumpărătorii media#

API-ul își justifică costul de configurare în patru sarcini recurente:

1. Motoare de reguli. Clasicul: la fiecare oră, trage site_breakdown pentru campaniile active; orice site care a cheltuit mai mult de N× CPA-ul țintă cu zero conversii intră pe lista de site-uri blocate a campaniei printr-o actualizare a campaniei. Aceasta este aceeași buclă de eliminare a pierzătorilor pe care o rulează manual orice advertiser Taboola serios — codificată, neemoțională și rulează la 3 dimineața.
2. Gestionarea ofertelor. Ajustarea CPC-urilor campaniilor (și a modificatorilor de ofertă per site unde sunt disponibile) în sus în zilele și geo-urile care depășesc ținta, în jos când CPA-ul derivă — ajustări mici, frecvente, plictisitoare care se compun.
3. Operațiuni bulk cu creativități. Încărcarea a 30 de variante de titlu/imagine per campanie, punerea pe pauză a tuturor celor sub mediana CTR săptămânal și menținerea rotației creative înaintea oboselii fără un după-amiază de clicuri.
4. Pipeline-uri de cheltuieli. Un job nocturn care trage campaign-summary pe zi în depozit, astfel încât cheltuielile Taboola să ajungă lângă veniturile din conversii și fiecare alt canal într-un singur dashboard.

Un plan minimal de integrare#

Dacă pornești de la zero, această secvență te duce la automatizare utilă în aproximativ o zi de muncă, cu fiecare pas verificabil înainte de următorul:

1. Round-trip token. Schimbă credentialele pentru un token și apelează allowed-accounts. Dacă funcționează, autentificarea și permisiunile sunt rezolvate.
2. Raportare doar citire. Trage campaign-summary pe zi pentru ultima săptămână și reconciliază numerele cu Consola de Anunțuri. Nu scrie nimic până când citirile tale se potrivesc cu ceea ce arată interfața.
3. O singură mutație sigură. Pune și scoate de pe pauză o campanie de test prin PUT. Confirmă că schimbarea apare în consolă și că starea de servire o urmează.
4. Sincronizarea nocturnă a cheltuielilor. Programează tragerea raportului în baza ta de date. Doar asta justifică integrarea pentru majoritatea echipelor.
5. Motorul de reguli, în dry-run. Calculează deciziile de blocare a site-urilor și înregistrează ce s-ar întâmpla o săptămână înainte de a-l lăsa să scrie. Compararea alegerilor sale cu cele pe care le faci manual este cel mai ieftin QA pe care îl vei rula vreodată.

Săritul direct la pasul cinci este greșeala standard — bug-urile pe calea de scriere împotriva unui cont de anunțuri live sunt lecții costisitoare.

Limite de rată și capcane practice#

• Respectă plafonul. Backstage aplică limite de rată per cont; grupează citirile (un apel de raport per campanie pe oră, nu unul pe minut) și retrage-te la 429-uri. Verifică referința pentru limitele curente în loc să presupui.
• Raportarea întârzie servirea. Datele din orele recente se stabilizează în timp; construiește reguli pe baza unor date cu cel puțin câteva ore vechime sau vei pune campaniile pe pauză pe baza unor numere incomplete.
• Editările nu sunt instant. Schimbările în campanii se propagă la servire cu întârziere, iar editările elementelor pot re-trigări revizuirea. Automatizarea ar trebui să tolereze decalajul în loc să re-emită scrieri "eșuate".
• Stochează ID-uri, nu nume. Numele campaniilor și elementelor sunt editate de oameni; ID-urile numerice sunt chei de join stabile.
• Protejează calea de scriere. Un motor de reguli cu un bug poate pune pe pauză întreaga cheltuială a unui cont sau să înmulțească o ofertă cu 10. Înregistrează fiecare mutație, adaugă limite de bun-simț (nu schimba niciodată o ofertă cu mai mult de X% pe pas) și pornește orice regulă nouă în modul dry-run.

Celălalt API Taboola: date competitive#

Tot ce este mai sus vede exact un cont: al tău. Backstage nu-ți va spune niciodată care advertiseri cresc în verticala ta, ce creativități rulează sau cât timp a supraviețuit campania unui competitor — rețeaua nu publică nicio bibliotecă de anunțuri proprie și niciun endpoint oficial nu expune activitatea altor advertiseri.

Aceasta este lacuna pe care o acoperă API-ul de dezvoltator al OpenAdLibrary. Indexul conține peste 206.000 de creativități Taboola live (iulie 2026) într-un corpus de peste 725.000 de anunțuri native pe 49 de rețele, iar aceleași date din spatele bibliotecii de anunțuri Taboola sunt interogabile prin REST: caută creativități după advertiser, verticală, geo și longevitate; trage titluri și pagini de destinație; urmărește când concurenții lansează și închid campanii. Ghidul API pentru date de anunțuri native documentează endpoint-urile, iar dacă fluxul tău de lucru trăiește într-un agent LLM există un server MCP care expune același corpus ca instrumente pentru Claude și ChatGPT. O cheie gratuită acoperă utilizarea ușoară și prețurile rămân plate pentru restul; peisajul mai larg al accesului la inteligență publicitară programatic este explorat în instrumente de spionaj publicitar cu API.

Cele două API-uri se combină natural: Backstage automatizează execuția pe contul tău, API-ul de inteligență automatizează cercetarea pe conturile tuturor celorlalți. Cumpărătorii care obțin cel mai mult din automatizare rulează ambele — un motor de reguli care își menține propriile campanii tăiate și un flux competitiv care semnalează când un advertiser nou începe să crească în verticala lor, astfel încât următorul test să nu fie ales orb. Începe cu instrumentul de spionaj Taboola pentru a vedea corpusul competitiv într-un browser, apoi ia aceleași interogări programatic când fluxul de lucru se dovedește.