TikTok Ads

Coming soon (platform verification) Ads

Reads campaigns, ad groups, ads and daily reports so TikTok spend, pacing and CAC sit next to Google and Meta.

What we pull

advertiser (currency, time zone)
campaigns, ad groups, ads with budgets
daily integrated report (spend, impressions, clicks, conversions, purchase value)

Every record lands as a financial event with source_type, external_id (deduplicated on re-sync) and provenance. Mode: mock.

Signals and sync

Scheduled sync only (no webhooks).
Sync interval: daily.
Health signals: auth_expired, silent (no sync for over twice the interval), error. Each becomes an in-app notification for the owner and shows in Integrations.

Permissions and secrets

TikTok for Business developer app (Marketing API)
Advertiser authorization with Reporting and Ad Account read scopes
Long-lived access token

Secrets are encrypted at rest (AES-256-GCM, per-owner) and never returned by the API; the panel shows only the last 4 characters and the date. Read-only keys wherever the provider offers them.

Availability

Coming soon: the provider is verifying our app. Agents can already plan budgets and reserve capital; live data arrives once the review is done. Use “Notify me” in the panel.

Setup steps

From the Integrator’s owner checklist (Polish; the panel walks you through the same steps).

Dopóki nie zdecydujesz, że TikTok ma być trzecią platformą (panel: „Available soon"), nic tu nie rób. Gdy zdecydujesz, potrzebujesz 4 zmiennych, wszystkie do Railway (operlance-staging → api → Variables, sekcja E):

#	Zmienna	Skąd (krok niżej)
1	`TIKTOK_APP_ID`	G1
2	`TIKTOK_APP_SECRET`	G1
3	`TIKTOK_ACCESS_TOKEN`	G2
4	`TIKTOK_ADVERTISER_ID`	G2

Plus na końcu TIKTOK_ADS_ENABLED=on (to włącznik, nie klucz, wpisujesz go sam).

G1. Aplikacja deweloperska (10 min + weryfikacja firmy 1 do 5 dni)

https://business-api.tiktok.com/portal → Become a Developer → dane firmy (weryfikacja) → My Apps → Create an App: nazwa Operlance, opis, Advertiser redirect URL: https://api.operlance.app/v1/integrations/tiktok_ads/callback.
Scope of permissions: zaznacz tylko Ad Account Management: Read i Reporting (nie Ads Management write) → Submit.
Po akceptacji, dwie zmienne z tego samego ekranu aplikacji, obie do Railway (operlance-staging → api → Variables): App ID → zmienna TIKTOK_APP_ID; Secret (pokazany raz) → zmienna TIKTOK_APP_SECRET.

G2. Autoryzacja konta reklamowego (5 min)

W aplikacji skopiuj Advertiser authorization URL → otwórz zalogowany na konto TikTok for Business → wybierz konto reklamowe (Clothing) → Confirm. Przekierowanie trafia do naszego API, które wymienia auth_code na token (nic nie wklejasz ręcznie, pomija to zmienne 3 i 4 poniżej).
Jeśli chcesz wpisać token sam zamiast przekierowania (MVP bez callbacku): Tools → Access Token generator w aplikacji → Railway: zmienna TIKTOK_ACCESS_TOKEN (długoterminowy); Advertiser ID (Ads Manager → Account info) → Railway: zmienna TIKTOK_ADVERTISER_ID.
Włącznik adaptera (nie klucz, wpisujesz go sam, dowolnie): Railway → zmienna TIKTOK_ADS_ENABLED = on. Bez webhooków: dane spływają raz dziennie.

To wszystkie zmienne sekcji G. Gdy są w Railway, napisz Mózgowi „sekcja G gotowa”.