API dokumentáció és árazás

# AutoSEO – API dokumentáció és árazás

Ez a dokumentum tartalmazza az összes külső szolgáltatás API útmutatóját, API kulcs létrehozását és árazási információit.

**Megkülönböztetés:**
- **Platform API-k** (2–4. fejezet): A fejlesztő köti be a `.env`-ben – OpenAI, DataForSEO, Serpstat. Nem jelennek meg a felhasználói UI-ban.
- **Felhasználói integrációk** (5–7. fejezet): A felhasználó csatlakoztatja a saját fiókját – GA4, Search Console, Merchant Center. A Beállításokban láthatók.

---

## Tartalomjegyzék

1. [Összefoglaló – Szükséges külső források](#1-összefoglaló)
2. [OpenAI (AI generálás)](#2-openai)
3. [DataForSEO (Kulcsszó, SERP, Backlink)](#3-dataforseo)
4. [Serpstat (Alternatíva kulcsszóhoz)](#4-serpstat)
5. [Google Analytics 4](#5-google-analytics-4)
6. [Google Search Console](#6-google-search-console)
7. [Google Merchant Center](#7-google-merchant-center)
8. [Moz API (Backlink alternatíva)](#8-moz-api)
9. [Becsült havi költség](#9-becsült-havi-költség)

---

## 1. Összefoglaló

### Szükséges és elégséges külső források (SEMrush/Ahrefs szint)

| Kategória | Szolgáltatás | Kötelező? | Jelenlegi státusz |
|-----------|--------------|-----------|---------------------|
| **AI generálás** | OpenAI | ✅ Igen | ✅ Bekötve |
| **Kulcsszó kutatás** | DataForSEO vagy Serpstat | ✅ Igen | ✅ Bekötve |
| **SERP / Rank tracking** | DataForSEO SERP API | ✅ Igen | ✅ Org API + PostgreSQL idősor |
| **Backlink elemzés** | DataForSEO Backlinks vagy Moz | ✅ Igen | ✅ Összesítő API + UI; Moz opcionális |
| **Technikai SEO / Crawl** | Saját (fetch) vagy DataForSEO OnPage | Opcionális | ✅ Részben kész |
| **GA4** | Google Analytics Data API | Opcionális | ✅ OAuth / ADC + Data API |
| **Search Console** | Search Console API | ✅ Igen | ✅ OAuth + API |
| **Merchant Center** | Content API for Shopping | E-commerce esetén | ✅ OAuth + API |
| **AI Visibility** | OpenAI + oldal fetch (org API) | Új funkció | ✅ Kész; DataForSEO AI Optimization opcionális később |

---

## 2. OpenAI

### Mit csinál
- AI alt szöveg generálás (Kép SEO)
- Meta cím/leírás generálás
- Blog/cikk generálás
- Kategória leírás generálás
- Rövid leírás generálás

### API kulcs létrehozása
1. Regisztráció: https://platform.openai.com/signup
2. Bejelentkezés után: **API keys** → **Create new secret key**
3. Másold ki a kulcsot (pl. `sk-...`) – egyszer jelenik meg!

### .env
```
OPENAI_API_KEY=sk-...
```

### Árazás (2024–2025)
| Modell | Input (1M token) | Output (1M token) |
|--------|------------------|-------------------|
| gpt-4o-mini | ~$0.15 | ~$0.60 |
| gpt-4o | ~$2.50 | ~$10.00 |
| gpt-4-turbo | ~$10.00 | ~$30.00 |

**Becsült használat AutoSEO-ban:** gpt-4o-mini – ~100–500 token/kérés. 1000 kérés/hó ≈ $0.50–2.00.

---

## 3. DataForSEO

### Mit csinál
- **Keywords Data API** – kulcsszó kutatás (volume, difficulty, CPC, related)
- **SERP API** – keresési eredmények, pozíciók
- **Backlinks API** – backlink elemzés
- **OnPage API** – technikai SEO, oldal elemzés
- **Domain Analytics API** – domain overview
- **AI Optimization API** – AI keresés optimalizálás (ChatGPT, Perplexity stb.)

### Regisztráció és API kulcs
1. Regisztráció: https://dataforseo.com/
2. **Dashboard** → **API Access** – a bejelentkezési email és jelszó = API hitelesítés
3. Basic Auth: `Base64(login:password)`

### .env
```
DATAFORSEO_LOGIN=your_email@example.com
DATAFORSEO_PASSWORD=your_password
```

### Árazás (Pay-as-you-go, minimum $50)
Részletes árak: https://dataforseo.com/pricing-list

| API | Becsült ár / kérés | Megjegyzés |
|-----|-------------------|------------|
| Keywords Data (Google Ads) | ~$0.002–0.01 | Kulcsszó adatok |
| SERP API | ~$0.01–0.05 | Keresési eredmények |
| Backlinks API | ~$0.01–0.10 | Backlink adatok |
| OnPage API | ~$0.01–0.05 | Oldal elemzés |
| Domain Analytics | ~$0.01–0.05 | Domain overview |
| AI Optimization | Egyedi | AI visibility |

**Becsült havi költség (közepes használat):** $50–200/hó.

### SERP pozíció követés (Rank tracking)

- **Backend:** `lib/dataforseo-serp.ts` – Google Organic Live Advanced, `depth` 100 (organikus találatok szélesebb sávja).
- **API (bejelentkezés + szervezeti jogosultság):**
  - `GET /api/orgs/[orgId]/seo/rank-tracking` – követett kulcsszavak + legutóbbi pillanatkép; `dataForSeoConfigured` jelzi, hogy a szerveren be vannak-e állítva a DataForSEO kulcsok.
  - `POST` body: `{ "action": "add", "keyword", "targetDomain", "locationCode"?, "languageCode"?, "device"? }` | `{ "action": "check", "keywordId" }` | `{ "action": "checkAll" }` | `{ "action": "remove", "keywordId" }`.
- **UI:** SEO Eszközök → **SERP pozíció követés** (PostgreSQL szükséges; migráció: `prisma/migrations/.../rank_tracking`).

### Backlink összesítő (Backlinks summary)

- **Backend:** `lib/dataforseo-backlinks.ts` – `POST .../v3/backlinks/summary/live`.
- **API (bejelentkezés + szervezeti jogosultság):**
  - `GET /api/orgs/[orgId]/seo/backlinks` – havi kvóta + `dataForSeoConfigured`.
  - `POST` body: `{ "target": "pelda.hu", "includeSubdomains"?: boolean }` (domain vagy URL; normalizálva domainre megy; aldomainek alapból be) → összesítő metrikák + `costUsd`; **429**, ha elérted a havi limitet (UTC); sikeres hívás után `SeoApiUsage` (`backlinks_summary`).
- **UI:** SEO Eszközök → **Backlinkek** (egészség-gyűrű, metrika magyarázatok, előző méréshez képest változás; **két domain összevetés** = 2 API hívás; egy domain eredménye **localStorage** snapshot a böngészőben; JSON / CSV export).

### AI Visibility (OpenAI + oldal letöltés)

- **Backend:** `lib/ai-visibility.ts` (HTML → szöveg + heurisztikus oldal-jelek) + `lib/ai-visibility-analysis.ts` (JSON normalizálás) + `lib/openai-server.ts`.
- **API:**
  - `GET /api/orgs/[orgId]/seo/ai-visibility` – havi kvóta + `openaiConfigured`.
  - `POST` body: `{ "url": "https://...", "includeOrgContext"?: boolean }` – opcionálisan a user prompt kiegészül a szervezet integrációinak (GA4 / GSC / Ads / Merchant) nem titkos összefoglalójával (`lib/seo-org-context-for-ai.ts`). Válasz: összpontszám, 4 dimenzió (clarity, structure, trustSignals, snippetQuality), entitások, szándék, gyors nyerések, kockázatok, tartalmi rések, meta javaslatok, `pageSignals` (szószám, H1/H2, JSON-LD, OG, FAQ-heurisztika); **429** havi limitnél; siker után `SeoApiUsage` (`ai_visibility`).
- **Környezet:** `OPENAI_API_KEY` a szerveren (ugyanaz, mint más AI funkciókhoz).
- **UI:** SEO Eszközök → **AI Visibility** (tabok: áttekintés, részpontszámok, oldal-jelek, akció & export; böngészőben **legutóbbi elemzések** localStorage-ban, max 8; opcionális **tömeges URL** max 5 sor, soronként 1 kvóta; jelölőnégyzet a szervezeti kontextushoz – beállítás **szervezetenként** megmarad a böngészőben). A SEO Eszközök nézet tetején **SEO insights** sáv: integrációs pillák, rank kulcsszám (API), lokális backlink/AI pillanatkép (mentéskor eseménnyel frissül), gyors ugrás a Backlinkek / AI Visibility / Rank tracking fülekre (aktív fül kiemelve).

### Következő DataForSEO modulok (roadmap)

| Modul | API | Env | Költség / megjegyzés | DB / idősor |
|-------|-----|-----|----------------------|-------------|
| **AI Optimization** (AI SERP) | Labs / AI Optimization | `DATAFORSEO_*` + meglévő | Pay-as-you-go; opcionális kiegészítés a jelenlegi OpenAI AI Visibilityhez | Cache opcionális |
| **Domain Analytics / Labs** | Domain overview, keyword gap | Ugyanaz | Több hívás / domain; kvóta: `lib/plan-limits` + fair use | Opcionális tárolás |
| **OnPage** (mély audit) | OnPage | Ugyanaz | Drágább; nem helyettesíti a saját crawl-t | Feladat queue |

Részletes ütem: [ALL-IN-ONE-ROADMAP.md](./ALL-IN-ONE-ROADMAP.md), [GA-PILLARS-ACCEPTANCE.md](./GA-PILLARS-ACCEPTANCE.md).

---

## 4. Serpstat

### Mit csinál
- Kulcsszó kutatás (alternatíva DataForSEO-hoz)
- Domain elemzés
- Backlink adatok

### API kulcs létrehozása
1. Regisztráció: https://serpstat.com/
2. **Account** → **API Access** → API token másolása

### .env
```
SERPSTAT_TOKEN=your_api_token
```

### Árazás
- Lite: ~$69/hó
- Standard: ~$149/hó
- Advanced: ~$299/hó
- API limitek a csomagtól függnek

---

## 5. Google Analytics 4

### Mit csinál
- Oldalnézetek, konverziók
- Forgalom források
- Felhasználói viselkedés

### Beállítás
1. **Google Cloud Console**: https://console.cloud.google.com/
2. Projekt létrehozása vagy kiválasztása
3. **APIs & Services** → **Enable APIs** → **Google Analytics Data API**
4. **IAM** → **Service Accounts** → Szolgáltatásfiók létrehozása
5. JSON kulcs letöltése
6. GA4 Property-ban adj hozzá olvasási jogot a szolgáltatásfióknak

### .env
```
GA4_PROPERTY_ID=123456789
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
```

### Árazás
- Ingyenes (GA4 maga ingyenes, API hívások is)

---

## 6. Google Search Console

### Mit csinál
- Lekérdezési teljesítmény (kattintások, megjelenések, CTR, pozíció)
- Indexálási státusz
- Sitemap beküldés

### Beállítás
1. **Google Cloud Console** → **Search Console API** engedélyezése
2. **OAuth 2.0 Client ID** létrehozása (Web application)
3. Redirect URI: `https://your-domain.com/api/auth/callback/google`
4. Search Console: https://search.google.com/search-console – webhely hozzáadása

### .env
```
GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=xxx
```

### Árazás
- Ingyenes

---

## 7. Google Merchant Center

### Mit csinál
- Termékek szinkronizálása
- Feed feltöltés
- Hibák és figyelmeztetések

### Beállítás
1. Regisztráció: https://merchants.google.com/
2. **Content API for Shopping** engedélyezése a GCP-ben
3. OAuth vagy szolgáltatásfiók

### .env
```
MERCHANT_ID=123456789
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
```

### Árazás
- Ingyenes (API használat)

---

## 8. Moz API

### Mit csinál
- Backlink elemzés (alternatíva DataForSEO Backlinks-hez)
- Domain Authority (DA), Page Authority (PA)
- Link elemzés

### API kulcs
1. Regisztráció: https://moz.com/
2. **Moz Pro** vagy **API Access** csomag
3. Access ID + Secret Key

### .env
```
MOZ_ACCESS_ID=your_access_id
MOZ_SECRET_KEY=your_secret_key
```

### Árazás
- Moz Pro: ~$99–599/hó (API limitekkel)

---

## 9. Becsült havi költség

### Minimális konfiguráció (funkcionális MVP)
| Szolgáltatás | Becsült költség |
|--------------|-----------------|
| OpenAI | $5–20 |
| DataForSEO (min. $50) | $50 |
| **Összesen** | **~$55–70/hó** |

### Közepes használat (SEMrush szintű)
| Szolgáltatás | Becsült költség |
|--------------|-----------------|
| OpenAI | $20–50 |
| DataForSEO | $100–200 |
| Serpstat (opcionális backup) | $0 vagy $69 |
| **Összesen** | **~$120–320/hó** |

### Teljes stack (GA4, GSC, Merchant, AI Visibility)
| Szolgáltatás | Becsült költség |
|--------------|-----------------|
| OpenAI | $50–150 |
| DataForSEO | $150–300 |
| Google (GA4, GSC, Merchant) | $0 |
| **Összesen** | **~$200–450/hó** |

---

## Gyors hivatkozások

- [DataForSEO Pricing List](https://dataforseo.com/pricing-list)
- [OpenAI Pricing](https://openai.com/pricing)
- [Serpstat API Docs](https://serpstat.com/api/)
- [Google Analytics Data API](https://developers.google.com/analytics/devguides/reporting/data/v1)
- [Search Console API](https://developers.google.com/webmaster-tools/search-console-api-original)
- [Moz API](https://moz.com/help/links-api)