# Integrare live TikTok Ads & Facebook Ads — Roadmap

Obiectiv: sincronizare automată a cheltuielilor (`Cheltuit`) din CRM, pe baza campaniilor legate la fiecare produs testat (câmpul „Campanii legate" din formular).

Status: **infrastructura e construită și funcțională, în așteptarea aprobării aplicațiilor developer**. Pasul 1 (unelte de dezvoltare) e gata — Node.js, Homebrew, git funcționează pe acest Mac. Pasul 3 (serverul local + butoanele din CRM) e gata construit și pornește corect. Singurul lucru rămas e Pasul 2: obținerea App ID/App Secret de la TikTok și Meta — pui cheile în `.env`, pornești serverul, apeși „conectează" în CRM, gata.

⚠️ **Când treci de la localhost la live**: actualizează `FACEBOOK_REDIRECT_URI`/`TIKTOK_REDIRECT_URI` din `.env` și redirect URI-urile din dashboard-urile Facebook/TikTok la domeniul live al `ads-sync-server`, și `ALLOWED_ORIGINS` la domeniul live al CRM-ului. Vezi `supabase/README.md` pentru restul configurării (Supabase, autentificare).

## De ce nu se poate face direct din browser

- **TikTok Business API** este gândit exclusiv pentru apeluri server-to-server — un fetch direct din browser va fi blocat.
- **Meta Marketing API** necesită un „App Secret" pentru a obține un access token de lungă durată — acest secret nu poate fi expus niciodată într-un fișier HTML static.
- Concluzie: e nevoie de un mic server local (Node.js sau Python) care gestionează autentificarea și cheile în siguranță, iar CRM-ul din browser vorbește doar cu acest server local (nu direct cu TikTok/Meta).

## Pasul 1 — Pregătire mediu ✅ FĂCUT

Xcode Command Line Tools, Homebrew, Node.js (v26), npm și git sunt instalate și funcționale pe acest Mac.

## Pasul 2 — Cont developer + credențiale (tu, în lucru)

**Facebook / Meta Ads:**
1. Mergi pe [developers.facebook.com](https://developers.facebook.com) → creezi o App nouă, tip „Business".
2. Adaugi produsul **Marketing API** la App.
3. Notezi **App ID** și **App Secret** (din Setări → De bază).
4. Configurezi OAuth Redirect URI: `http://localhost:3737/auth/facebook/callback` (trebuie să fie identic cu `FACEBOOK_REDIRECT_URI` din `.env`).
5. Ai nevoie de acces la contul tău de Ads (Business Manager) cu rol care permite citirea de insights (`ads_read`).

**TikTok Ads:**
1. Mergi pe [business-api.tiktok.com/portal](https://business-api.tiktok.com/portal) (sau ads.tiktok.com → Marketing API).
2. Creezi o „Developer App".
3. Notezi **App ID** și **App Secret**.
4. Ceri acces la scope-ul de reporting (`Reporting`/`ads_management`) pentru contul tău de ads — TikTok poate cere aprobare manuală, care poate dura câteva zile.

Când ai aceste 4 valori (Facebook App ID/Secret, TikTok App ID/Secret):
1. Copiază `.env.example` (la rădăcina proiectului) în `.env`, dacă n-ai făcut-o deja.
2. Completează `TIKTOK_APP_ID`, `TIKTOK_APP_SECRET`, `FACEBOOK_APP_ID`, `FACEBOOK_APP_SECRET` (redirect URI-urile sunt deja completate corect, pe portul 3737).
3. Pornește serverul: `cd tools/ads-sync-server && npm start`.
4. În CRM (pagina Marketing → Testare Produse), apasă **conectează** lângă TikTok Ads / Facebook Ads din bara de sus — se deschide fereastra de autorizare, o confirmi, gata.

⚠️ **Verifică moneda contului de ads înainte de a te baza pe cifre.** `lib/tiktok.js` și `lib/facebook.js` iau valoarea `spend` direct de la API, fără nicio conversie sau verificare de monedă — dacă Business Manager-ul/advertiser-ul e setat pe USD sau EUR (frecvent implicit, chiar și pentru conturi din România), cheltuiala s-ar aduna direct peste veniturile în RON din Shopify la Finanțe → Profit, fără niciun avertisment. Verifică moneda din Ads Manager/TikTok Business Center **înainte** să te bazezi pe cifrele din Finanțe → Profit; dacă nu e RON, anunță-mă ca să adăugăm conversie valutară.

## Pasul 3 — Infrastructura (construită, ✅)

1. **`tools/ads-sync-server/`** — server local Node/Express, testat că pornește corect:
   - `server.js` — rutele OAuth (`/auth/tiktok/start`, `/auth/tiktok/callback`, `/auth/facebook/start`, `/auth/facebook/callback`), status (`/api/status`), lookup cheltuială (`/api/campaign-spend`), deconectare (`/api/disconnect`)
   - `lib/tiktok.js`, `lib/facebook.js` — client-ii API pentru fiecare platformă (auth URL, exchange token, listare campanii, raport cheltuială)
   - `lib/tokenStore.js` — salvare token-uri în Supabase (tabel `oauth_tokens`, doar service role key, inaccesibil din browser — vezi `supabase/README.md`)
   - `lib/requireAuth.js` — validează sesiunea CRM (JWT Supabase) la fiecare cerere — trebuie să fii logat în CRM ca să apeși „conectează" sau să vezi cheltuielile
   - detalii complete: [`tools/ads-sync-server/README.md`](../tools/ads-sync-server/README.md)
2. **CRM (`app/index.html`)** — bară de status „TikTok Ads / Facebook Ads" (conectat/neconectat, cu buton de conectare/deconectare) deasupra tabelului de produse, plus butonul **🔄 Sincronizează cheltuieli**, care sumează automat cheltuiala campaniilor legate per produs și completează câmpul „Cheltuit".

**Notă:** integrarea a fost scrisă conform documentației publice a celor două API-uri, dar încă netestată live (aplicațiile developer sunt în așteptare de aprobare la TikTok/Meta). E posibil ca la prima conectare reală să fie nevoie de mici ajustări dacă vreun câmp/endpoint s-a schimbat între timp — anunță-mă dacă apare vreo eroare la conectare sau sincronizare.

## Notă despre potrivirea după nume de campanie

Matching-ul se face pe **numele exact al campaniei** din Ads Manager (case-insensitive, spații ignorate). Recomandare: folosește o convenție de denumire consistentă care include numele produsului, ex:
```
TEST - Perie Electrică Animale - TikTok
TEST - Perie Electrică Animale - FB
```
Asta face matching-ul robust și îți e și ție mai ușor să găsești campania direct în Ads Manager.