Contract v1.0.0

← Integrations

Meta Ads

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

D1. Business Manager (jeśli nie masz)

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

D2. Aplikacja Meta (5 min)

  1. https://developers.facebook.com/apps → Create App.
  2. Use case: Other → App type: Business → nazwa Operlance, e-mail, wybierz swój Business portfolio → Create app.
  3. W aplikacji: Add products → Marketing API → Set up (nic więcej nie konfiguruj).
  4. App settings → Basic: skopiuj App secret → Show → Railway META_ADS_APP_SECRET. App ID zanotuj (nie jest sekretem).
  5. 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)

  1. Business settings → Users → System users → Add → nazwa operlance-api, rola Employee (nie Admin) → Create system user.
  2. Zaznacz system usera → Add assets → Ad accounts → konto THARAN → uprawnienie View performance (NIE „Manage campaigns”) → Save changes. Analogicznie Apps → Operlance → Develop app.
  3. 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.
  4. Skopiuj token (pokazany raz) → Railway META_ADS_ACCESS_TOKEN. Ten token nie wygasa, chyba że go unieważnisz (System users → … → Revoke): zrób to, jeśli kiedykolwiek wycieknie.
  5. Webhooki (opcjonalnie): App → Webhooks → Ad Account → Subscribe z URL https://api-production-3516.up.railway.app/v1/webhooks/meta_ads i Verify token = dowolny ciąg, który wpiszesz też w Railway jako META_WEBHOOK_VERIFY_TOKEN. Spend i tak idzie codziennym syncem, webhook daje tylko „kampania wstrzymana”.