API Base URL

https://pdf-to-question.aydinacar.net/api

Tüm API istekleri bu base URL üzerinden yapılır. Örnek: https://pdf-to-question.aydinacar.net/api/auth/login

Kimlik Doğrulama (Authentication)

API'yi kullanmak için önce bir kullanıcı hesabı oluşturmanız ve Bearer token almanız gerekir. Token'ı aldıktan sonra, tüm korumalı endpoint'lere istek yaparken Authorization header'ında token'ı göndermeniz gerekir.

POST 1. Kullanıcı Kaydı

Yeni bir kullanıcı hesabı oluşturun. Kayıt işlemi başarılı olduğunda otomatik olarak Bearer token döner.

Endpoint: https://pdf-to-question.aydinacar.net/api/auth/register

Request Body:

{
  "name": "Ahmet Yılmaz",
  "email": "ahmet@example.com",
  "password": "güvenlişifre123",
  "password_confirmation": "güvenlişifre123",
  "phone": "+905551234567"
}

Response (201 Created): ✓ Gerçek Response

{
  "success": true,
  "message": "Kayıt başarılı! 14 günlük ücretsiz deneme başlatıldı.",
  "data": {
    "user": {
      "id": 1,
      "name": "Ahmet Yılmaz",
      "email": "ahmet@example.com",
      "phone": "+905551234567",
      "country_code": "TR",
      "language": "tr",
      "currency": "TRY",
      "role": "manager"
    },
    "token": "1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "trial_ends_at": "2025-12-08T10:30:00+00:00"
  }
}

🎁 Bonus: Yeni kayıt olan kullanıcılara otomatik olarak 14 günlük ücretsiz trial verilir.

POST 2. Kullanıcı Girişi

Mevcut bir kullanıcı hesabı ile giriş yapın ve Bearer token alın.

Endpoint: https://pdf-to-question.aydinacar.net/api/auth/login

Request Body:

Response (200 OK): ✓ Gerçek Response

{
  "success": true,
  "message": "Giriş başarılı",
  "data": {
    "user": {
      "id": 1,
      "name": "Ahmet Yılmaz",
      "email": "ahmet@example.com",
      "phone": "+905551234567",
      "country_code": "TR",
      "language": "tr",
      "currency": "TRY",
      "role": "manager",
      "avatar": null
    },
    "token": "2|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "subscription": {
      "status": "trial",
      "plan": "monthly",
      "plan_type": "monthly",
      "is_trial": true,
      "is_active": true,
      "trial_ends_at": "2025-12-08T10:30:00+00:00",
      "starts_at": "2025-11-24T10:30:00+00:00",
      "ends_at": "2025-12-08T10:30:00+00:00",
      "days_remaining": 14,
      "resident_count": 0
    }
  }
}

3. Bearer Token ile API İsteği

Token'ı aldıktan sonra, korumalı endpoint'lere istek yaparken Authorization header'ında Bearer token göndermeniz gerekir.

Header Formatı:

Authorization: Bearer 1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Örnek: Kullanıcı Bilgilerini Getirme

curl -X GET https://pdf-to-question.aydinacar.net/api/auth/me \
  -H "Authorization: Bearer 1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

Response (200 OK): ✓ Gerçek Response

{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "name": "Ahmet Yılmaz",
      "email": "ahmet@example.com",
      "phone": "+905551234567",
      "country_code": "TR",
      "language": "tr",
      "currency": "TRY",
      "role": "manager",
      "avatar": null,
      "email_verified_at": null,
      "created_at": "2025-11-24T10:30:00+00:00"
    },
    "subscription": {
      "status": "trial",
      "plan": "monthly",
      "plan_type": "monthly",
      "is_trial": true,
      "is_active": true,
      "trial_ends_at": "2025-12-08T10:30:00+00:00",
      "starts_at": "2025-11-24T10:30:00+00:00",
      "ends_at": "2025-12-08T10:30:00+00:00",
      "days_remaining": 14,
      "resident_count": 0
    }
  }
}

Kod Örnekleri

cURL

# Kullanıcı Kaydı
curl -X POST https://pdf-to-question.aydinacar.net/api/auth/register \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Ahmet Yılmaz",
    "email": "ahmet@example.com",
    "password": "güvenlişifre123",
    "password_confirmation": "güvenlişifre123",
    "phone": "+905551234567"
  }'

# Kullanıcı Girişi
curl -X POST https://pdf-to-question.aydinacar.net/api/auth/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "ahmet@example.com",
    "password": "güvenlişifre123"
  }'

# Token ile Korumalı Endpoint'e İstek
curl -X GET https://pdf-to-question.aydinacar.net/api/auth/me \
  -H "Authorization: Bearer 1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

JavaScript (Fetch API)

// Kullanıcı Kaydı
const registerResponse = await fetch('https://pdf-to-question.aydinacar.net/api/auth/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    name: 'Ahmet Yılmaz',
    email: 'ahmet@example.com',
    password: 'güvenlişifre123',
    password_confirmation: 'güvenlişifre123',
    phone: '+905551234567'
  })
});

const registerData = await registerResponse.json();
const token = registerData.data.token;

// Token ile Korumalı Endpoint'e İstek
const meResponse = await fetch('https://pdf-to-question.aydinacar.net/api/auth/me', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Accept': 'application/json'
  }
});

const meData = await meResponse.json();
console.log(meData);

Python (Requests)

import requests

# API Base URL
BASE_URL = "https://pdf-to-question.aydinacar.net/api"

# Kullanıcı Kaydı
register_data = {
    "name": "Ahmet Yılmaz",
    "email": "ahmet@example.com",
    "password": "güvenlişifre123",
    "password_confirmation": "güvenlişifre123",
    "phone": "+905551234567"
}

response = requests.post(
    f"{BASE_URL}/auth/register",
    json=register_data,
    headers={"Accept": "application/json"}
)

register_result = response.json()
token = register_result["data"]["token"]

# Token ile Korumalı Endpoint'e İstek
headers = {
    "Authorization": f"Bearer {token}",
    "Accept": "application/json"
}

me_response = requests.get(
    f"{BASE_URL}/auth/me",
    headers=headers
)

me_data = me_response.json()
print(me_data)

PHP (Guzzle HTTP)

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://pdf-to-question.aydinacar.net/api',
    'headers' => [
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
]);

// Kullanıcı Kaydı
$registerResponse = $client->post('/auth/register', [
    'json' => [
        'name' => 'Ahmet Yılmaz',
        'email' => 'ahmet@example.com',
        'password' => 'güvenlişifre123',
        'password_confirmation' => 'güvenlişifre123',
        'phone' => '+905551234567',
    ],
]);

$registerData = json_decode($registerResponse->getBody(), true);
$token = $registerData['data']['token'];

// Token ile Korumalı Endpoint'e İstek
$meResponse = $client->get('/auth/me', [
    'headers' => [
        'Authorization' => "Bearer {$token}",
    ],
]);

$meData = json_decode($meResponse->getBody(), true);
print_r($meData);

Korumalı Endpoint'ler

Aşağıdaki endpoint'ler Bearer token gerektirir. Token'ı Authorization: Bearer {token} header'ında göndermeniz gerekir.

GET /api/auth/me

Kullanıcı bilgilerini getirir

POST /api/auth/logout

Kullanıcı çıkışı yapar ve token'ı geçersiz kılar

GET /api/pdfs

Kullanıcının PDF'lerini listeler

POST /api/pdfs

Yeni bir PDF yükler ve işleme başlatır

GET /api/pdfs/{id}

PDF detayını getirir (sayfalar ve sorular dahil)

GET /api/pdfs/{id}/status

PDF işleme durumunu ve progress bilgisini getirir

GET /api/pdfs/{id}/questions

PDF'den çıkarılan soruları getirir

GET /api/pdfs/{pdfId}/pages/{pageId}/questions

Belirli bir sayfadaki soruları getirir (enhanced görsellerle)

PUT /api/pdfs/{pdfId}/questions/{questionId}

Soruyu günceller

PUT /api/pdfs/{pdfId}/questions/{questionId}/recrop

Soru görselini yeniden kırpar ve OCR işlemini tetikler

DELETE /api/pdfs/{id}

PDF'i siler

DELETE /api/pdfs/{pdfId}/questions/{questionId}

Tek soruyu siler (görsel dosyaları dahil)

POST /api/pdfs/{pdfId}/questions/{questionId}/reprocess-column

Soruyu siler ve ilgili sütunu (left/right) yeniden gap_detection ile işler

POST /api/pdfs/{pdfId}/pages/{pageId}/reprocess-gap-detection

Sayfadaki tüm soruları siler ve sayfayı yeniden gap_detection ile işler

POST /api/pdfs/{id}/reprocess

PDF'i yeniden işler (resimleri yeniden oluşturur)

GET /api/tokens/balance

Token bakiyesini getirir

GET /api/tokens/usage

Token kullanım geçmişini getirir

GET /api/tokens/pdfs/{pdfId}/usage

PDF'e ait token kullanımını getirir

GET /api/invoices

Fatura listesini getirir

GET /api/bank-accounts

Banka hesap bilgilerini getirir

Not: Tüm korumalı endpoint'lerin detaylı dokümantasyonu için API_ENTEGRASYON.md dosyasını inceleyebilirsiniz. /api/* altındaki tüm endpoint'ler (auth/register ve auth/login hariç) Bearer token gerektirir.

PDF İşlemleri - Detaylı Örnekler

POST PDF Yükleme

Endpoint: /api/pdfs

Request Headers:

Authorization: Bearer YOUR_TOKEN_HERE
Content-Type: multipart/form-data

Request Body (multipart/form-data):

file (required): PDF dosyası (max 1GB)
preload (optional, boolean, default: false):
- false: PDF yüklenir ve otomatik işlenir (bakiye düşer)
- true: PDF sadece yüklenir, işlenmez (bakiye düşmez, manuel başlatılır)
page_range_start (optional): İşlenecek ilk sayfa numarası
page_range_end (optional): İşlenecek son sayfa numarası

cURL Örneği 1: Tüm sayfaları işle

curl -X POST https://pdf-to-question.aydinacar.net/api/pdfs \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -F "file=@/path/to/your/file.pdf"

cURL Örneği 2: Sadece 5-10 arası sayfaları işle

curl -X POST https://pdf-to-question.aydinacar.net/api/pdfs \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -F "file=@/path/to/your/file.pdf" \
  -F "page_range_start=5" \
  -F "page_range_end=10"

cURL Örneği 3: PDF'i sadece yükle, işleme (preload: true)

curl -X POST https://pdf-to-question.aydinacar.net/api/pdfs \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -F "file=@/path/to/your/file.pdf" \
  -F "preload=true"

📦 Ön Yükleme Modu: PDF yalnızca sunucuya yüklenir, işlenmez. Bakiye düşmez. İstediğiniz zaman POST /api/pdfs/{id}/start-processing endpoint'i ile işlemeye başlatabilirsiniz.

Response (201 Created): ✓ Gerçek Response

{
  "success": true,
  "message": "PDF başarıyla yüklendi ve işleme başladı",
  "data": {
    "id": 42,
    "filename": "matematik_sorulari.pdf",
    "status": "processing",
    "status_display": "İşleniyor",
    "page_range_start": 5,
    "page_range_end": 10,
    "python_version": "v3",
    "created_at": "2025-11-24T10:30:00+00:00",
    // İşlem asenkron çalışır
    // Status kontrolü için: GET /api/pdfs/42/status
  }
}

⚡ Asenkron İşlem: PDF yükleme işlemi arka planda çalışır. İşlem durumunu kontrol etmek için /api/pdfs/{id}/status endpoint'ini kullanın.

💰 Ücretlendirme: PDF yükleme için minimum $2 bakiye gerekir. İşlem maliyeti sayfa sayısı ve soru sayısına göre hesaplanır.

Hata Response - Yetersiz Bakiye (402 Payment Required): ✓ Gerçek Response

{
  "success": false,
  "message": "Yetersiz bakiye. PDF yüklemek için minimum $2 bakiyeniz olmalı.",
  "data": {
    "current_balance": 0.50,
    "required_balance": 2.00,
    "missing_amount": 1.50
  }
}

GET PDF İşleme Durumu

Endpoint: /api/pdfs/{id}/status

cURL Örneği:

curl -X GET https://pdf-to-question.aydinacar.net/api/pdfs/42/status \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json"

Response Örneği - İşleniyor (200 OK): ✓ Gerçek Response

{
  "success": true,
  "data": {
    "id": 42,
    "status": "processing",
    "status_display": "İşleniyor",
    "total_pages": 6,
    "total_questions": 18,
    "progress": 65,
    "current_stage": "validation_running",
    "stage_message": "Sorular doğrulanıyor...",
    "error_message": null,
    "cost": "0.245000",
    "token_usage": {
      "total_tokens": 12500,
      "total_cost_usd": 0.245,
      "question_count": 18
    },
    "balance": 9.755
  }
}

Response Örneği - Tamamlandı (200 OK): ✓ Gerçek Response

{
  "success": true,
  "data": {
    "id": 42,
    "status": "completed",
    "status_display": "Tamamlandı",
    "total_pages": 6,
    "total_questions": 23,
    "progress": 100,
    "current_stage": "completed",
    "stage_message": "İşlem tamamlandı! (23 soru)",
    "error_message": null,
    "cost": "0.312000",
    "token_usage": {
      "total_tokens": 15900,
      "total_cost_usd": 0.312,
      "question_count": 23
    },
    "balance": 9.688
  }
}

📊 Progress Aşamaları:
• 0-20%: PDF sayfalara çevriliyor
• 20-40%: Sayfa tipleri analiz ediliyor
• 40-55%: Sorular tespit ediliyor (Gap Detection)
• 55-70%: Sorular doğrulanıyor (Validation)
• 70-85%: Soru metinleri çıkarılıyor (OCR)
• 85-95%: Soru numaraları eşleştiriliyor
• 95-100%: Tamamlanma

💡 Status Değerleri:
• preload: Ön yüklendi (işlenmedi)
• pending: İşlem sıraya alındı
• processing: İşleniyor
• completed: Tamamlandı
• failed: Başarısız

POST Preload PDF'i İşleme Başlat

Ön yüklenmiş (preload) bir PDF'in işlenmesini başlatır. Bu endpoint sadece status: preload olan PDF'ler için çalışır.

Endpoint: /api/pdfs/{id}/start-processing

Request Headers:

Authorization: Bearer YOUR_TOKEN_HERE
Accept: application/json

cURL Örneği:

curl -X POST https://pdf-to-question.aydinacar.net/api/pdfs/42/start-processing \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json"

Response (200 OK): ✓ Gerçek Response

{
  "success": true,
  "message": "PDF işleme kuyruğuna eklendi",
  "data": {
    "id": 42,
    "status": "processing",
    "status_display": "İşleniyor",
    "balance": 9.50
  }
}

🔄 Kullanım Akışı:
1. PDF'i preload=true ile yükle → Status: preload
2. Bu endpoint'i çağır → Status: processing
3. İşlem tamamlanınca → Status: completed

💰 Ücretlendirme: Bu endpoint çağrıldığında bakiye kontrolü yapılır ve işlem başlar. Minimum $2 bakiye gereklidir.

Hata Response - Zaten İşlenmiş (400 Bad Request): ✓ Gerçek Response

{
  "success": false,
  "message": "Bu PDF zaten işleme alınmış veya işleniyor",
  "current_status": "processing"
}

GET Soruları Getirme

Endpoint: /api/pdfs/{id}/questions

Query Parameters:

page_number (optional): Belirli bir sayfa için soruları getir

cURL Örneği 1: Tüm sorular

curl -X GET "https://pdf-to-question.aydinacar.net/api/pdfs/42/questions" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json"

cURL Örneği 2: Belirli sayfa için sorular

curl -X GET "https://pdf-to-question.aydinacar.net/api/pdfs/42/questions?page_number=1" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json"

Response Örneği (200 OK): ✓ Gerçek Response

{
  "success": true,
  "data": [
    {
      "id": 101,
      "pdf_id": 42,
      "page_id": 5,
      "page_number": 1,
      "question_number": "1",
      "question_text": "Aşağıdaki işlemlerden hangisinin sonucu 15'tir?",
      "coordinates": {
        "x1": 120,
        "y1": 250,
        "x2": 580,
        "y2": 450
      },
      "crop_image_url": "https://pdf-to-question.aydinacar.net/storage/questions/42/page_1_q_1_crop.png",
      "quality_status": "ok",
      "created_at": "2025-11-24T10:35:22+00:00"
    },
    {
      "id": 102,
      "pdf_id": 42,
      "page_id": 5,
      "page_number": 1,
      "question_number": "2",
      "question_text": "5 + 3 x 2 işleminin sonucu kaçtır?",
      "coordinates": {
        "x1": 120,
        "y1": 470,
        "x2": 580,
        "y2": 670
      },
      "crop_image_url": "https://pdf-to-question.aydinacar.net/storage/questions/42/page_1_q_2_crop.png",
      "quality_status": "ok",
      "created_at": "2025-11-24T10:35:23+00:00"
    },
    // ... daha fazla soru
  ],
  "meta": {
    "total_questions": 23,
    "total_pages": 6,
    "filtered_by_page": false
  }
}

📸 Görsel Formatı:
• crop_image_url: Sorunun PDF'den kesilmiş hali

DELETE Soru Silme

Tek bir soruyu ve tüm görsel dosyalarını (cropped, enhanced, trimmed) kalıcı olarak siler.

Endpoint: /api/pdfs/{pdfId}/questions/{questionId}

cURL Örneği:

curl -X DELETE https://pdf-to-question.aydinacar.net/api/pdfs/42/questions/101 \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json"

Response (200 OK): ✓ Gerçek Response

{
  "success": true,
  "message": "Soru başarıyla silindi"
}

⚠️ Dikkat: Bu işlem geri alınamaz! Soru ve tüm görselleri kalıcı olarak silinir.

PUT Soru Görselini Yeniden Kırpma

Soru görselini orijinal sütun görselinden (left/right column) yeniden kırpar. Kesim ayarları piksel cinsinden belirtilir. Pozitif değerler görseli daraltır (içeri keser), negatif değerler genişletir (dışarı genişletir). İşlem sonrası OCR işlemi otomatik tetiklenir.

Endpoint: /api/pdfs/{pdfId}/questions/{questionId}/recrop

Request Body Parametreleri:

Parametre	Tip	Zorunlu	Açıklama
left	integer	Hayır	Soldan kesim/genişletme (px). Pozitif = daralt, Negatif = genişlet
right	integer	Hayır	Sağdan kesim/genişletme (px). Pozitif = daralt, Negatif = genişlet
top	integer	Hayır	Üstten kesim/genişletme (px). Pozitif = daralt, Negatif = genişlet
bottom	integer	Hayır	Alttan kesim/genişletme (px). Pozitif = daralt, Negatif = genişlet
question_text	string	Hayır	Soru metnini güncelle
topic	string (max 255)	Hayır	Soru konusunu güncelle
correct_answer	string (max 10)	Hayır	Doğru cevabı güncelle (A, B, C, D, E vb.)

cURL Örneği:

curl -X PUT https://pdf-to-question.aydinacar.net/api/pdfs/42/questions/101/recrop \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "left": 10,
  "right": -5,
  "top": 0,
  "bottom": 15,
  "topic": "Matematik - Cebir",
  "question_text": "Güncellenmiş soru metni",
  "correct_answer": "B"
}'

Response (200 OK): ✓ Gerçek Response

{
  "success": true,
  "message": "Soru görseli yeniden kırpıldı ve OCR işlemi başlatıldı",
  "data": {
    "id": 101,
    "question_number": 3,
    "question_text": "Güncellenmiş soru metni",
    "topic": "Matematik - Cebir",
    "correct_answer": "B",
    "cropped_image_path": "pdf_questions/42/page_664_left_question_3_recrop_1764953737.jpg",
    "enhanced_image_path": null,
    "question_processing_step": "pending_direct_ocr",
    "coordinates": {
      // Koordinatlar değişmez, sadece görsel yeniden kırpılır
      "x": 100,
      "y": 200,
      "width": 500,
      "height": 300
    }
  }
}

📝 Önemli Notlar:
• Koordinatlar güncellenmez: Veritabanındaki koordinat bilgileri korunur, sadece görsel yeniden kırpılır
• Orijinal sütun görselinden kırpılır: İşlem sol veya sağ sütun görselinden yapılır (sorunun column_side değerine göre)
• Görsel sınırları: Genişletme işlemi görsel sınırlarını aşamaz, otomatik olarak sınırlanır
• Minimum boyut: Kırpılan görsel minimum 10x10 piksel olmalıdır
• OCR tetiklenir: İşlem sonrası soru pending_direct_ocr durumuna geçer ve OCR işlemi başlar
• Eski görseller silinir: Önceki cropped ve enhanced görselleri otomatik silinir
• Kullanıcı yüklediği görseller: column_side değeri "user" olan sorular için bu işlem yapılamaz

💡 Kesim Ayarları Örnekleri:
• left: 10 → Soldan 10px daralt (içeri kes)
• left: -10 → Soldan 10px genişlet (dışarı genişlet)
• right: 5, left: 5 → Her iki taraftan 5px daralt
• top: -20, bottom: -20 → Üstten ve alttan 20px genişlet
• Sadece metin güncellemesi için tüm kesim parametreleri 0 veya gönderilmeyebilir

POST Soruyu Yeniden İşleme (İlgili Sütun)

Soruyu siler ve sorunun bulunduğu sütunu (left veya right) yeniden gap_detection ile işler. PDF durumu "processing" olarak güncellenir ve tüm işlem akışı otomatik devam eder.

Endpoint: /api/pdfs/{pdfId}/questions/{questionId}/reprocess-column

cURL Örneği:

curl -X POST https://pdf-to-question.aydinacar.net/api/pdfs/42/questions/101/reprocess-column \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json"

Response (200 OK): ✓ Gerçek Response

{
  "success": true,
  "message": "Soru silindi ve left sütunu yeniden işleme alındı.",
  "data": {
    "pdf_id": 42,
    "page_id": 5,
    "page_number": 1,
    "column_side": "left",
    "batch_job_id": 1234,
    "status": "processing"
  }
}

🔄 İşlem Akışı:
1. Soru ve görselleri silinir
2. PDF status "processing" olur
3. İlgili sütun için gap_detection başlar
4. Validation → OCR → Text Matching otomatik devam eder
5. PDF status "completed" olur

POST Sayfayı Yeniden İşleme (Gap Detection)

Sayfadaki tüm soruları siler ve sayfayı (hem left hem right sütun) yeniden gap_detection ile işler. PDF durumu "processing" olarak güncellenir.

Endpoint: /api/pdfs/{pdfId}/pages/{pageId}/reprocess-gap-detection

cURL Örneği:

curl -X POST https://pdf-to-question.aydinacar.net/api/pdfs/42/pages/5/reprocess-gap-detection \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json"

Response (200 OK): ✓ Gerçek Response

{
  "success": true,
  "message": "Sayfa 1 yeniden işleme alındı. 4 soru silindi.",
  "data": {
    "pdf_id": 42,
    "page_id": 5,
    "page_number": 1,
    "deleted_questions": 4,
    "batch_job_id": 1235,
    "status": "processing"
  }
}

⚠️ Dikkat: Bu işlem sayfadaki TÜM soruları siler ve yeniden tespit eder. Hem sol hem sağ sütun yeniden işlenir.

🔄 İşlem Akışı:
1. Sayfadaki tüm sorular ve görselleri silinir
2. PDF status "processing" olur
3. Sol ve sağ sütun için gap_detection başlar
4. Validation → OCR → Text Matching otomatik devam eder
5. PDF status "completed" olur

Token İşlemleri

Token Sistemi

Sistem USD bazlı çalışır. PDF yükleme, soru çıkarma ve görsel iyileştirme işlemleri OpenAI API kullanımına göre maliyetlendirilir. Tüm ücretlendirme USD ($) cinsindendir.

💰 Fiyatlandırma:
• Minimum bakiye gereksinimi: $2.00
• Ortalama maliyet: $0.10 - $0.50 / PDF (sayfa ve soru sayısına göre)

GET Token Bakiyesi

Endpoint: /api/tokens/balance

cURL Örneği:

curl -X GET https://pdf-to-question.aydinacar.net/api/tokens/balance \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json"

Response (200 OK): ✓ Gerçek Response

{
  "success": true,
  "data": {
    "balance_usd": 9.688,
    "currency": "USD",
    "formatted": "$9.69"
  }
}

GET Token Kullanım Geçmişi

Endpoint: /api/tokens/usage

Query Parameters:

per_page (optional, default: 20): Sayfa başına kayıt sayısı
page (optional, default: 1): Sayfa numarası

cURL Örneği:

curl -X GET "https://pdf-to-question.aydinacar.net/api/tokens/usage?per_page=10" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json"

Response (200 OK): ✓ Gerçek Response

{
  "success": true,
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 501,
        "pdf_id": 42,
        "pdf_filename": "matematik_sorulari.pdf",
        "operation_type": "gap_detection",
        "input_tokens": 8500,
        "output_tokens": 1200,
        "total_tokens": 9700,
        "cost_usd": 0.182,
        "created_at": "2025-11-24T10:32:15+00:00"
      },
      {
        "id": 502,
        "pdf_id": 42,
        "pdf_filename": "matematik_sorulari.pdf",
        "operation_type": "ocr",
        "input_tokens": 5200,
        "output_tokens": 1000,
        "total_tokens": 6200,
        "cost_usd": 0.130,
        "created_at": "2025-11-24T10:34:42+00:00"
      }
    ],
    "per_page": 10,
    "total": 48,
    "last_page": 5
  },
  "summary": {
    "total_cost_usd": 10.312,
    "total_tokens": 528400,
    "total_operations": 48
  }
}

GET PDF Token Kullanımı

Endpoint: /api/tokens/pdfs/{pdfId}/usage

cURL Örneği:

curl -X GET https://pdf-to-question.aydinacar.net/api/tokens/pdfs/42/usage \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json"

Response (200 OK): ✓ Gerçek Response

{
  "success": true,
  "data": {
    "pdf_id": 42,
    "pdf_filename": "matematik_sorulari.pdf",
    "total_cost_usd": 0.312,
    "total_tokens": 15900,
    "question_count": 23,
    "operations": [
      {
        "operation_type": "page_analysis",
        "cost_usd": 0.045,
        "tokens": 2300
      },
      {
        "operation_type": "gap_detection",
        "cost_usd": 0.182,
        "tokens": 9700
      },
      {
        "operation_type": "ocr",
        "cost_usd": 0.085,
        "tokens": 3900
      }
    ]
  }
}

Hata Yönetimi

401 Unauthorized

Token geçersiz, eksik veya süresi dolmuş olduğunda:

{
  "success": false,
  "message": "Unauthorized. Please login."
}

Çözüm: Yeniden giriş yapın ve yeni token alın (POST /api/auth/login)

422 Validation Error

Gönderilen veriler doğrulama kurallarına uygun olmadığında:

{
  "success": false,
  "message": "Validation error",
  "errors": {
    "email": ["E-posta adresi zaten kullanılıyor"],
    "password": ["Şifre en az 8 karakter olmalıdır"],
    "file": ["Dosya PDF formatında olmalıdır"]
  }
}

Çözüm: errors objesindeki hataları kontrol edin ve verileri düzeltin

402 Payment Required

Yetersiz bakiye olduğunda (PDF yükleme için):

{
  "success": false,
  "message": "Yetersiz bakiye. PDF yüklemek için minimum $2 bakiyeniz olmalı.",
  "data": {
    "current_balance": 0.50,
    "required_balance": 2.00,
    "missing_amount": 1.50
  }
}

Çözüm: Bakiye yükleyin veya yeterli bakiye olduğunda tekrar deneyin

404 Not Found

İstenen kaynak (PDF, soru vb.) bulunamadığında:

{
  "success": false,
  "message": "PDF not found or you don't have permission to access it."
}

Çözüm: ID'yi kontrol edin veya bu kaynağa erişim yetkiniz olup olmadığını kontrol edin

500 Internal Server Error

Sunucu tarafında beklenmeyen bir hata oluştuğunda:

{
  "success": false,
  "message": "An unexpected error occurred. Please try again later.",
  "error": "Internal server error"
}

Çözüm: Birkaç dakika bekleyip tekrar deneyin. Sorun devam ederse destek ile iletişime geçin

💡 Best Practices:
• Her API çağrısında Accept: application/json header'ı gönderin
• Token'ları güvenli bir şekilde saklayın (environment variables)
• Hata durumlarını success alanına göre kontrol edin
• Rate limiting için 429 Too Many Requests durumunu handle edin
• Asenkron işlemler için polling interval'i en az 2 saniye olmalı

Yardım ve Destek

API kullanımı ile ilgili sorularınız için bizimle iletişime geçebilirsiniz.

Destek Sayfası Ana Sayfa

API Dokümantasyonu

API Base URL

Kimlik Doğrulama (Authentication)

POST 1. Kullanıcı Kaydı

POST 2. Kullanıcı Girişi

3. Bearer Token ile API İsteği

Kod Örnekleri

cURL

JavaScript (Fetch API)

Python (Requests)

PHP (Guzzle HTTP)

Korumalı Endpoint'ler

PDF İşlemleri - Detaylı Örnekler

POST PDF Yükleme

GET PDF İşleme Durumu

POST Preload PDF'i İşleme Başlat

GET Soruları Getirme

DELETE Soru Silme

PUT Soru Görselini Yeniden Kırpma

POST Soruyu Yeniden İşleme (İlgili Sütun)

POST Sayfayı Yeniden İşleme (Gap Detection)

Token İşlemleri

Token Sistemi

GET Token Bakiyesi

GET Token Kullanım Geçmişi

GET PDF Token Kullanımı

Hata Yönetimi

401 Unauthorized

422 Validation Error

402 Payment Required

404 Not Found

500 Internal Server Error

Yardım ve Destek