Meta Ads (Facebook and Instagram)

Coming soon (platform verification) Ads

Reads campaigns, ad sets, ads and daily insights so Meta spend, pacing and results are visible next to Google.

What we pull

ad account (currency, time zone)
campaigns, ad sets, ads with budgets
daily insights (spend, impressions, clicks, actions, action values)

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

Signals and sync

Webhooks deliver changes in real time; a scheduled sync fills gaps.
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

Meta app (Business type) with Marketing API
System user with View performance on the ad account
System user token with ads_read
App secret (webhook signature)

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).

Potrzebujesz 3 zmiennych (plus 1 opcjonalną, jeśli chcesz webhooki). Lista, zanim zaczniesz, wszystkie do Railway (operlance-staging → api → Variables, sekcja E):

#	Zmienna	Skąd (krok niżej)
1	`META_ADS_AD_ACCOUNT_ID`	D1
2	`META_ADS_APP_SECRET`	D2
3	`META_ADS_ACCESS_TOKEN`	D3
4 (opcjonalna)	`META_WEBHOOK_VERIFY_TOKEN`	D3 pkt 5

D1. Business Manager (jeśli nie masz)

https://business.facebook.com → Create account → nazwa firmy, Twoje imię, e-mail firmowy.
Settings (Business settings) → Accounts → Ad accounts → Add → Add an ad account (albo Claim) → konto reklamowe THARAN. Zapisz Ad account ID (cyfry po act_) → Railway (operlance-staging → api → Variables): zmienna META_ADS_AD_ACCOUNT_ID (same cyfry albo z act_, obojętne).

D2. Aplikacja Meta (5 min)

https://developers.facebook.com/apps → Create App.
Use case: Other → App type: Business → nazwa Operlance, e-mail, wybierz swój Business portfolio → Create app.
W aplikacji: Add products → Marketing API → Set up (nic więcej nie konfiguruj).
App settings → Basic: skopiuj App secret → Show → Railway (to samo miejsce): zmienna META_ADS_APP_SECRET. App ID zanotuj gdzieś u siebie (nie jest sekretem, nie idzie do Railway).
Zostaw aplikację w trybie Development: dla własnych kont wystarczy. App Review / Business Verification nie są potrzebne, dopóki nie łączymy cudzych kont (wtedy 2 do 10 dni roboczych, dokumenty rejestrowe firmy).

D3. System user + token (10 min)

Business settings → Users → System users → Add → nazwa operlance-api, rola Employee (nie Admin) → Create system user.
Zaznacz system usera → Add assets → Ad accounts → konto THARAN → uprawnienie View performance (NIE „Manage campaigns”) → Save changes. Analogicznie Apps → Operlance → Develop app.
Generate new token → wybierz aplikację Operlance → Token expiration: Never → zaznacz tylko ads_read (jeśli lista wymaga, dodatkowo business_management: ale nie ads_management) → Generate token.
Skopiuj token (pokazany raz) → Railway (operlance-staging → api → Variables): zmienna META_ADS_ACCESS_TOKEN. Ten token nie wygasa, chyba że go unieważnisz (System users → … → Revoke): zrób to, jeśli kiedykolwiek wycieknie.
Webhooki (opcjonalnie, zmienna 4 z tabeli powyżej): App → Webhooks → Ad Account → Subscribe z URL https://api.operlance.app/v1/webhooks/meta_ads i Verify token = dowolny ciąg, który wpiszesz też w Railway jako zmienną META_WEBHOOK_VERIFY_TOKEN. Spend i tak idzie codziennym syncem, webhook daje tylko „kampania wstrzymana”.

To wszystkie zmienne sekcji D (3 obowiązkowe + opcjonalna webhookowa). Gdy są w Railway, napisz Mózgowi „sekcja D gotowa”.