API Referansı

Bu sayfa, SeoAuthor API'nin tüm endpoint'lerini, parametrelerini ve yanıt formatlarını detaylı olarak açıklamaktadır.

🌐 Base URL

https://integration.seoauthor.ai

🔐 Kimlik Doğrulama

Tüm API çağrıları (login ve refresh hariç) Authorization header'ı gerektirir:

Authorization: Bearer YOUR_ACCESS_TOKEN

📚 Endpoint Kategorileri

🔑 Authentication

Endpoint	Method	Açıklama
/api/v1/auth/login	POST	Sistemde oturum açma
/api/v1/auth/refresh	POST	Token yenileme

📝 Makale İşlemleri

Endpoint	Method	Açıklama
/api/v1/makaleler/makale-olustur	POST	Tek makale oluşturma
/api/v1/makaleler/toplu-makale-olustur	POST	Toplu makale oluşturma
/api/v1/makaleler/makalelerim	GET	Makaleleri listeleme
/api/v1/makaleler/yazim-tonlari	GET	Yazım tonlarını getirme
/api/v1/makaleler/makale-boyutları	GET	Makale boyutlarını getirme

🏷️ Konu Yönetimi

Endpoint	Method	Açıklama
/api/v1/konular/konu-ekle	POST	Tek konu ekleme
/api/v1/konular/toplu-konu-ekle	POST	Toplu konu ekleme

📋 Başlık İşlemleri

Endpoint	Method	Açıklama
/api/v1/basliklar/baslik-olustur	POST	Başlık oluşturma

👤 Profil

Endpoint	Method	Açıklama
/api/v1/profil/guncel-bakiye	GET	Mevcut bakiye sorgulama
/api/v1/profil/hesap-ozeti	GET	Hesap özeti
/api/v1/profil/hesap-hareketleri	GET	Hesap hareketleri

🔍 Detaylı Endpoint Açıklamaları

🔐 Authentication Endpoints

POST /api/v1/auth/login

Açıklama: Sistemde oturum açma

Request Body:

{
  "email": "string (required)",
  "password": "string (required)"
}

Response (200):

{
  "accessToken": "string",
  "accessTokenExpire": "integer",
  "refreshToken": "string"
}

POST /api/v1/auth/refresh

Açıklama: Access token yenileme

Request Body:

{
  "refreshToken": "string (required)"
}

Response (200):

{
  "accessToken": "string",
  "accessTokenExpire": "integer",
  "refreshToken": "string"
}

📝 Makale Endpoints

POST /api/v1/makaleler/makale-olustur

Açıklama: Tek makale oluşturma

Headers:

Authorization: Bearer {accessToken}
Content-Type: application/json

Request Body:

{
  "baslik": "string (required)",
  "yazimTonu": "integer (required)",
  "makaleBoyutu": "integer (required)"
}

Response (200):

{
  "success": true,
  "message": "Makale oluşturma işlemi başlatıldı"
}

POST /api/v1/makaleler/toplu-makale-olustur

Açıklama: Birden fazla makaleyi aynı anda oluşturma

Request Body:

{
  "makaleler": [
    {
      "baslik": "string (required)"
    }
  ],
  "yazimTonu": "integer (required)",
  "makaleBoyutu": "integer (required)"
}

GET /api/v1/makaleler/makalelerim

Açıklama: Oluşturulan makaleleri listeleme

Query Parameters:

• konuId (integer, optional): Konu ID'si ile filtreleme
• durumId (integer, optional): Durum ID'si ile filtreleme
• pageIndex (integer, default: 0): Sayfa numarası
• pageSize (integer, default: 2147483647): Sayfa boyutu

Example:

GET /api/v1/makaleler/makalelerim?konuId=123&durumId=3&pageIndex=0&pageSize=10

GET /api/v1/makaleler/yazim-tonlari

Açıklama: Mevcut yazım tonlarını getirme

Response (200):

[
  {
    "id": 1,
    "name": "Profesyonel",
    "description": "Formal ve teknik dil"
  },
  {
    "id": 2,
    "name": "Samimi",
    "description": "Dostane ve yakın dil"
  }
]

GET /api/v1/makaleler/makale-boyutları

Açıklama: Mevcut makale boyutlarını getirme

Response (200):

[
  {
    "id": 1,
    "name": "Kısa",
    "wordCount": "300-500",
    "description": "Blog postları için ideal"
  },
  {
    "id": 2,
    "name": "Orta",
    "wordCount": "800-1200",
    "description": "Standart makaleler"
  }
]

🏷️ Konu Endpoints

POST /api/v1/konular/konu-ekle

Açıklama: Yeni konu ekleme

Request Body:

{
  "konu": "string (required)",
  "limit": "integer (required)"
}

POST /api/v1/konular/toplu-konu-ekle

Açıklama: Birden fazla konu ekleme

Request Body:

{
  "konular": [
    {
      "konu": "string (required)",
      "limit": "integer (required)"
    }
  ]
}

📋 Başlık Endpoints

POST /api/v1/basliklar/baslik-olustur

Açıklama: Anahtar kelimeden başlık oluşturma

Request Body:

{
  "anahtarKelime": "string (required)",
  "adet": "integer (default: 1)"
}

👤 Profil Endpoints

GET /api/v1/profil/guncel-bakiye

Açıklama: Mevcut hesap bakiyesini sorgulama

Response (200):

{
  "bakiye": 1500.5,
  "para_birimi": "TL"
}

GET /api/v1/profil/hesap-ozeti

Açıklama: Hesap özet bilgileri

Response (200):

{
  "kullanici_adi": "john.doe",
  "email": "john@example.com",
  "uyelik_tarihi": "2024-01-15",
  "toplam_makale": 45,
  "aktif_konu_sayisi": 12
}

GET /api/v1/profil/hesap-hareketleri

Açıklama: Hesap hareket geçmişi

Query Parameters:

• pageIndex (integer, default: 0): Sayfa numarası
• pageSize (integer, default: 20): Sayfa boyutu

Response (200):

{
  "hareketler": [
    {
      "id": 1001,
      "tarih": "2024-08-13T10:30:00Z",
      "islem_tipi": "makale_olusturma",
      "tutar": -25.0,
      "aciklama": "JavaScript Rehberi - Makale Üretimi"
    }
  ],
  "toplam_sayfa": 5,
  "mevcut_sayfa": 0
}

⚠️ Hata Kodları

HTTP Status Codes

Kod	Açıklama	Çözüm
200	OK	İşlem başarılı
400	Bad Request	İstek parametrelerini kontrol edin
401	Unauthorized	Token'ınızı yenileyin veya giriş yapın
403	Forbidden	Yetkisiz işlem
404	Not Found	Endpoint veya kaynak bulunamadı
429	Too Many Requests	Rate limit aşıldı
500	Internal Server Error	Sunucu hatası

Örnek Hata Yanıtları

400 Bad Request

{
  "error": "ValidationError",
  "message": "Baslik alanı zorunludur",
  "statusCode": 400,
  "details": {
    "field": "baslik",
    "code": "REQUIRED"
  }
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Geçersiz veya süresi dolmuş token",
  "statusCode": 401
}

429 Too Many Requests

{
  "error": "RateLimitExceeded",
  "message": "Çok fazla istek. 60 saniye sonra tekrar deneyin.",
  "statusCode": 429,
  "retryAfter": 60
}

📊 Rate Limiting

API çağrılarınız için limitler:

Endpoint Grubu	Limit	Süre
Authentication	10 istek	1 dakika
Makale İşlemleri	100 istek	1 saat
Profil	1000 istek	1 saat
Genel	500 istek	5 dakika

Rate Limit Headers

API yanıtlarında rate limit bilgileri:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1692789600

🔧 Schema Definitions

LoginRequest

{
  "email": "string (required)",
  "password": "string (required)"
}

AuthResponse

{
  "accessToken": "string (required)",
  "accessTokenExpire": "integer (required)",
  "refreshToken": "string (required)"
}

MakaleEkleRequest

{
  "baslik": "string (required)",
  "yazimTonu": "integer (required)",
  "makaleBoyutu": "integer (required)"
}

TopluMakaleEkleRequest

{
  "makaleler": [
    {
      "baslik": "string (required)"
    }
  ],
  "yazimTonu": "integer (required)",
  "makaleBoyutu": "integer (required)"
}

KonuEkleRequest

{
  "konu": "string (required)",
  "limit": "integer (required)"
}

BaslikOlusturRequest

{
  "anahtarKelime": "string (required)",
  "adet": "integer (default: 1)"
}

🧪 Test Araçları

Postman Collection

API'yi test etmek için Postman collection'ı:

{
  "info": {
    "name": "SeoAuthor API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://integration.seoauthor.ai"
    },
    {
      "key": "accessToken",
      "value": ""
    }
  ]
}

cURL Örnekleri

Login

curl -X POST https://integration.seoauthor.ai/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password123"}'

Makale Oluşturma

curl -X POST https://integration.seoauthor.ai/api/v1/makaleler/makale-olustur \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"baslik":"Test Makale","yazimTonu":1,"makaleBoyutu":2}'

📱 SDK ve Client Libraries

JavaScript SDK Örneği

class FinexAPIClient {
  constructor(baseUrl = "https://integration.seoauthor.ai") {
    this.baseUrl = baseUrl;
    this.accessToken = null;
  }

  async login(email, password) {
    const response = await fetch(`${this.baseUrl}/api/v1/auth/login`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ email, password }),
    });

    const data = await response.json();
    this.accessToken = data.accessToken;
    return data;
  }

  async createArticle(baslik, yazimTonu, makaleBoyutu) {
    return this.request("POST", "/api/v1/makaleler/makale-olustur", {
      baslik,
      yazimTonu,
      makaleBoyutu,
    });
  }

  async getMyArticles(filters = {}) {
    const params = new URLSearchParams(filters);
    return this.request("GET", `/api/v1/makaleler/makalelerim?${params}`);
  }

  async request(method, endpoint, body = null) {
    const options = {
      method,
      headers: {
        Authorization: `Bearer ${this.accessToken}`,
        "Content-Type": "application/json",
      },
    };

    if (body) {
      options.body = JSON.stringify(body);
    }

    const response = await fetch(`${this.baseUrl}${endpoint}`, options);
    return response.json();
  }
}

API Test İpucu

API'yi test etmek için Postman veya Insomnia gibi araçları kullanabilirsiniz. Bu araçlar, authentication ve environment variables yönetimini kolaylaştırır.

Güncelleme Bildirimi

API dokümantasyonu düzenli olarak güncellenmektedir. Son değişiklikler için changelog sayfasını takip edin.

Rate Limit Uyarısı

API çağrı limitlerini aşmamaya dikkat edin. Limit aşımında 429 hata kodu alacaksınız ve belirtilen süre kadar beklemek zorunda kalacaksınız.