API Dokümantasyonu

API Kullanım Kılavuzu

API sistemini kullanmak için aşağıdaki adımları takip edin:

Content-Type: application/json

{
    "field1": "value1",
    "field2": "value2"
}

{
    "success": true,
    "message": "İşlem başarılı",
    "data": {
        // Response data
    }
}

{
    "success": false,
    "message": "Hata mesajı",
    "errors": {
        "field_name": ["Hata detayı"]
    }
}

Genel Bakış

Satıcı API sistemi, satıcıların ürünlerini, siparişlerini ve diğer işlemlerini programatik olarak yönetmelerine olanak tanır. Gelişmiş API yapısı ile güçlü entegrasyonlar oluşturabilirsiniz.

Özellikler

• ✅ API Key/Secret ve Token tabanlı kimlik doğrulama
• ✅ Toplu ürün yükleme (100 ürüne kadar)
• ✅ Otomatik kategori hiyerarşisi yönetimi
• ✅ Görsel indirme ve optimizasyon
• ✅ Gelişmiş sipariş yönetimi
• ✅ Gerçek zamanlı stok yönetimi
• ✅ Toplu fiyat güncelleme
• ✅ Detaylı raporlama ve analitik
• ✅ Müşteri yönetimi
• ✅ Kupon yönetimi (ürün/sepet bazlı)
• ✅ Ürün yorumları ve değerlendirmeler
• ✅ Para çekme istekleri
• ✅ Mağaza ayarları yönetimi
• ✅ Mesajlaşma sistemi
• ✅ Destek talepleri
• ✅ Ürün soruları ve yanıtları
• ✅ Bildirim yönetimi
• ✅ Adres yönetimi
• ✅ Dosya yükleme
• ✅ Komisyon geçmişi
• ✅ Webhook sistemi (gerçek zamanlı bildirimler)
• ✅ Yüksek performans (~1.5 ürün/saniye)

Kimlik Doğrulama

Yöntem 1: API Key/Secret (Önerilen)

Satıcı panelinden veya admin panelinden API Key ve Secret oluşturun. Bu yöntem token'dan daha güvenli ve kalıcıdır.

// Headers
X-API-Key: sk_XXXXXXXXXXXX
X-API-Secret: xxxxxxxxxxxxxx
Content-Type: application/json

// Request Body
{
    "email": "seller@example.com",
    "password": "your_password"
}

Yöntem 2: Token

Giriş yaparak token alabilir ve tüm isteklerde kullanabilirsiniz.

// Headers
Authorization: Bearer 1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Profil İşlemleri

• GET /api/seller/profile - Profil bilgilerini getir
• PUT /api/seller/profile - Profil bilgilerini güncelle

Ürün İşlemleri

{
    "name": "Yeni Ürün",
    "description": "Ürün açıklaması",
    "category_id": 149,
    "category_ids": [150, 151],
    "brand_id": 5,
    "unit_price": 150.00,
    "current_stock": 100,
    "sku": "SKU-001",
    "barcode": "1234567890123",
    "delivery_time": 3,
    "unit": "adet",
    "weight": 0.5,
    "tax_rate": 20,
    "refundable": true,
    "thumbnail_img_url": "https://example.com/thumb.jpg",
    "gallery_images_urls": [
        "https://example.com/img1.jpg",
        "https://example.com/img2.jpg"
    ]
}

{
    "products": [
        {
            "name": "Toplu Ürün 1",
            "description": "Açıklama",
            "category_id": 149,
            "brand_id": 5,
            "unit_price": 150.00,
            "current_stock": 100,
            "barcode": "1234567890123",
            "delivery_time": 3,
            "tax_rate": 20,
            "refundable": true,
            "thumbnail_img_url": "https://example.com/thumb1.jpg",
            "gallery_images_urls": [
                "https://example.com/img1.jpg",
                "https://example.com/img2.jpg"
            ]
        },
        {
            "name": "Toplu Ürün 2",
            ...
        }
    ]
}

{
    "success": true,
    "message": "Bulk product creation completed. 2 successful, 0 failed.",
    "data": {
        "total": 2,
        "success_count": 2,
        "failed_count": 0,
        "execution_time_seconds": 3.45,
        "products_per_second": 0.58,
        "success": [...],
        "failed": []
    }
}

{
    "success": true,
    "message": "Products exported successfully",
    "data": {
        "download_url": "https://example.com/storage/exports/seller_products_10_2024-12-15_143025.xlsx",
        "filename": "seller_products_10_2024-12-15_143025.xlsx",
        "file_size": 245760,
        "note": "Add ?download=true to the URL to download the file directly"
    }
}

{
    "products": [
        {
            "id": 123,
            "unit_price": 199.99,
            "current_stock": 50,
            "published": true
        },
        {
            "id": 124,
            "unit_price": 299.99,
            "published": false
        }
    ]
}

{
    "success": true,
    "message": "Bulk update completed. Updated: 2, Failed: 0",
    "data": {
        "updated_count": 2,
        "failed_count": 0,
        "errors": []
    }
}

Kategori İşlemleri

Kategorileri listeleyebilir, ağaç yapısını alabilir ve detaylarını görüntüleyebilirsiniz.

• GET /api/seller/categories - Kategorileri listele
• GET /api/seller/categories/tree - Kategori ağacını getir
• GET /api/seller/categories/{id} - Kategori detayı

🏷️ Marka İşlemleri

• GET /api/seller/brands - Markaları listele
• GET /api/seller/brands/{id} - Marka detayı

Sipariş İşlemleri

Endpoint'ler

• GET /api/seller/orders - Siparişleri listele (ödeme durumu dahil)
• GET /api/seller/orders/{id} - Sipariş detayı (ödeme durumu dahil)
• POST /api/seller/orders - Sipariş oluştur
• PUT /api/seller/orders/{id}/status - Sipariş durumu güncelle
• POST /api/seller/orders/{id}/cancel - Sipariş iptal et
• POST /api/seller/orders/{id}/upload-invoice - Sipariş faturası yükle

📋 Sipariş İşlemleri İçin Gerekli Sütunlar

1. Sipariş Oluşturmak İçin (POST /api/seller/orders)

2. Sipariş Durumu Güncellemek İçin (PUT /api/seller/orders/{id}/status)

3. Sipariş İptal Etmek İçin (POST /api/seller/orders/{id}/cancel)

Örnek İstekler

{
    "success": true,
    "data": [
        {
            "id": 123,
            "code": "20241215-14302545",
            "date": "2024-12-15 14:30:25",
            "customer": {
                "id": 45,
                "name": "Ahmet Yılmaz",
                "email": "ahmet@example.com",
                "phone": "05551234567"
            },
            "payment_type": "bank_payment",
            "payment_status": "paid",
            "delivery_status": "pending",
            "grand_total": "250.00"
        }
    ],
    "pagination": {
        "current_page": 1,
        "last_page": 5,
        "per_page": 20,
        "total": 72
    }
}

{
    "customer": {
        "name": "Ahmet Yılmaz",
        "email": "ahmet@example.com",
        "phone": "05551234567",
        "address": "Atatürk Cad. No:123",
        "city": "İstanbul",
        "country": "Türkiye",
        "postal_code": "34000",
        "tc_identity_number": "12345678901"
    },
    "items": [
        {
            "product_id": 789,
            "quantity": 2,
            "variation": ""
        }
    ],
    "payment_type": "bank_payment"
}

4. Sipariş Faturası Yüklemek İçin (POST /api/seller/orders/{id}/upload-invoice)

Örnek İstek (cURL):

curl -X POST https://example.com/api/seller/orders/123/upload-invoice \
  -H "Authorization: Bearer {token}" \
  -F "invoice_file=@/path/to/invoice.pdf"

Örnek İstek (JavaScript/Fetch):

const formData = new FormData();
formData.append('invoice_file', fileInput.files[0]);

fetch('https://example.com/api/seller/orders/123/upload-invoice', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer {token}'
    },
    body: formData
})
.then(response => response.json())
.then(data => console.log(data));

Örnek Yanıt:

{
    "success": true,
    "message": "Invoice uploaded successfully",
    "data": {
        "order_id": 123,
        "invoice_file_id": 456,
        "invoice_url": "https://example.com/storage/uploads/all/invoice.pdf"
    }
}

İade Talepleri

Endpoint'ler

• GET /api/seller/refund-requests - İade taleplerini listele
• GET /api/seller/refund-requests/{id} - İade talebi detayı
• POST /api/seller/refund-requests/{id}/approve - İade talebini onayla
• POST /api/seller/refund-requests/{id}/reject - İade talebini reddet

1. İade Taleplerini Listeleme (GET /api/seller/refund-requests)

Query Parameters:

Örnek Yanıt:

{
    "success": true,
    "data": [
        {
            "id": 1,
            "order_id": 180,
            "order_code": "20260107-10255162",
            "order_detail_id": 183,
            "customer": {
                "id": 5,
                "name": "Kupon Test Müşteri",
                "email": "kupontest@example.com",
                "phone": "05551234567"
            },
            "product": {
                "id": 36557,
                "name": "Black Truffle Noir - Özel Üretim Kristal Çanta",
                "thumbnail": "https://example.com/uploads/thumb.jpg",
                "sku": "SKU-123"
            },
            "reason": "Ürün hasarlı geldi",
            "refund_amount": "29452.50",
            "refund_type": "individual",
            "refund_type_text": "Bireysel",
            "seller_approval": 0,
            "seller_approval_text": "Bekliyor",
            "admin_approval": 0,
            "admin_approval_text": "Bekliyor",
            "refund_status": 0,
            "refund_status_text": "Bekliyor",
            "rejection_reason": null,
            "created_at": "2026-01-07 10:25:51",
            "updated_at": "2026-01-07 10:25:51"
        }
    ],
    "pagination": {
        "current_page": 1,
        "last_page": 5,
        "per_page": 15,
        "total": 72
    }
}

2. İade Talebi Detayı (GET /api/seller/refund-requests/{id})

Örnek Yanıt:

{
    "success": true,
    "data": {
        "id": 1,
        "order_id": 180,
        "order_code": "20260107-10255162",
        "order_detail_id": 183,
        "customer": {
            "id": 5,
            "name": "Kupon Test Müşteri",
            "email": "kupontest@example.com",
            "phone": "05551234567"
        },
        "product": {
            "id": 36557,
            "name": "Black Truffle Noir - Özel Üretim Kristal Çanta",
            "thumbnail": "https://example.com/uploads/thumb.jpg",
            "sku": "SKU-123"
        },
        "reason": "Ürün hasarlı geldi",
        "refund_amount": "29452.50",
        "refund_type": "individual",
        "refund_type_text": "Bireysel",
        "seller_approval": 0,
        "seller_approval_text": "Bekliyor",
        "admin_approval": 0,
        "admin_approval_text": "Bekliyor",
        "refund_status": 0,
        "refund_status_text": "Bekliyor",
        "rejection_reason": null,
        "order_detail": {
            "id": 183,
            "variation": "",
            "quantity": 1,
            "price": "29452.50",
            "tax": "0.00",
            "shipping_cost": "0.00"
        },
        "order": {
            "id": 180,
            "code": "20260107-10255162",
            "date": "2026-01-07 10:25:51",
            "payment_status": "paid",
            "delivery_status": "confirmed"
        },
        "created_at": "2026-01-07 10:25:51",
        "updated_at": "2026-01-07 10:25:51"
    }
}

📋 İade Talepleri İçin Kullanılan Tablo Sütunları

3. İade Talebini Onaylama (POST /api/seller/refund-requests/{id}/approve)

Bekleyen bir iade talebini onaylar. Sadece seller_approval = 0 (Bekliyor) durumundaki talepler onaylanabilir.

Örnek Yanıt:

{
    "success": true,
    "message": "İade talebi onaylandı",
    "data": {
        "id": 1,
        "seller_approval": 1,
        "seller_approval_text": "Onaylandı",
        ...
    }
}

4. İade Talebini Reddetme (POST /api/seller/refund-requests/{id}/reject)

Request Body:

{
    "rejection_reason": "Ürün kullanılmış durumda, iade kabul edilemez"
}

Örnek Yanıt:

{
    "success": true,
    "message": "İade talebi reddedildi",
    "data": {
        "id": 1,
        "seller_approval": 2,
        "seller_approval_text": "Reddedildi",
        "rejection_reason": "Ürün kullanılmış durumda, iade kabul edilemez",
        ...
    }
}

Stok Yönetimi

• GET /api/seller/stocks - Stokları listele (filtreleme: product_id, low_stock, out_of_stock)
• GET /api/seller/stocks/product/{productId} - Ürün stok detayı
• GET /api/seller/stocks/low-stock - Düşük stok uyarıları
• PUT /api/seller/stocks/{id} - Stok miktarı güncelle
• POST /api/seller/stocks/bulk-update - Toplu stok güncelleme

Fiyat Yönetimi

• PUT /api/seller/prices/product/{productId} - Ürün fiyatı güncelle
• POST /api/seller/prices/bulk-update - Toplu fiyat güncelleme

Raporlama

• GET /api/seller/reports/sales - Satış raporları (günlük/haftalık/aylık)
• GET /api/seller/reports/products - Ürün performans raporları
• GET /api/seller/reports/commission - Komisyon raporları
• GET /api/seller/reports/dashboard - Dashboard istatistikleri

Müşteri Yönetimi

• GET /api/seller/customers - Müşterileri listele
• GET /api/seller/customers/{id} - Müşteri detayı ve sipariş geçmişi

Kupon Yönetimi

• GET /api/seller/coupons - Kuponları listele
• GET /api/seller/coupons/{id} - Kupon detayı
• POST /api/seller/coupons - Kupon oluştur
• PUT /api/seller/coupons/{id} - Kupon güncelle
• DELETE /api/seller/coupons/{id} - Kupon sil

Ürün Yorumları

• GET /api/seller/reviews - Ürün yorumlarını listele
• GET /api/seller/reviews/product/{productId} - Ürün yorum detayları

Dijital Ürünler

• GET /api/seller/digital-products - Dijital ürünleri listele
• GET /api/seller/digital-products/{id} - Dijital ürün detayı
• POST /api/seller/digital-products - Dijital ürün oluştur
• PUT /api/seller/digital-products/{id} - Dijital ürün güncelle
• DELETE /api/seller/digital-products/{id} - Dijital ürün sil
• GET /api/seller/digital-products/{id}/download - Dijital ürün indir

Ödeme Geçmişi

• GET /api/seller/payment-history - Ödeme geçmişini listele
• GET /api/seller/payment-history/{id} - Ödeme detayı

Para Çekme İstekleri

• GET /api/seller/withdraw-requests - Para çekme isteklerini listele
• GET /api/seller/withdraw-requests/{id} - İstek detayı
• POST /api/seller/withdraw-requests - Yeni para çekme isteği oluştur

Mağaza Ayarları

• GET /api/seller/shop - Mağaza bilgilerini getir
• PUT /api/seller/shop - Mağaza ayarlarını güncelle
• POST /api/seller/shop/verification - Mağaza doğrulama başvurusu gönder

Mesajlaşma

• GET /api/seller/conversations - Konuşmaları listele
• GET /api/seller/conversations/{id} - Konuşma detayı ve mesajlar
• POST /api/seller/conversations/{id}/message - Mesaj gönder

Destek Talepleri

• GET /api/seller/support-tickets - Destek taleplerini listele
• GET /api/seller/support-tickets/{id} - Ticket detayı
• POST /api/seller/support-tickets - Yeni ticket oluştur
• POST /api/seller/support-tickets/{id}/reply - Ticket'a yanıt ver

Ürün Soruları

• GET /api/seller/product-queries - Ürün sorularını listele
• GET /api/seller/product-queries/{id} - Soru detayı
• PUT /api/seller/product-queries/{id}/reply - Soruya yanıt ver

Bildirimler

• GET /api/seller/notifications - Bildirimleri listele
• PUT /api/seller/notifications/{id}/read - Bildirimi okundu işaretle
• DELETE /api/seller/notifications/{id} - Bildirimi sil
• POST /api/seller/notifications/bulk-delete - Toplu bildirim sil

Adresler

• GET /api/seller/addresses - Adresleri listele
• GET /api/seller/addresses/{id} - Adres detayı
• POST /api/seller/addresses - Yeni adres oluştur
• PUT /api/seller/addresses/{id} - Adres güncelle
• DELETE /api/seller/addresses/{id} - Adres sil
• PUT /api/seller/addresses/{id}/set-default - Varsayılan adres belirle

Dosya Yükleme

• GET /api/seller/uploads - Yüklenen dosyaları listele
• GET /api/seller/uploads/{id} - Dosya bilgisi
• POST /api/seller/uploads - Dosya yükle
• DELETE /api/seller/uploads/{id} - Dosya sil

Komisyon Geçmişi

• GET /api/seller/commission-history - Komisyon geçmişini listele
• GET /api/seller/commission-history/{id} - Komisyon detayı

Webhook Sistemi

Webhook'lar ile sistemdeki değişiklikleri gerçek zamanlı olarak takip edebilirsiniz.

• GET /api/seller/webhooks - Webhook'ları listele
• POST /api/seller/webhooks - Yeni webhook oluştur
• PUT /api/seller/webhooks/{id} - Webhook güncelle
• DELETE /api/seller/webhooks/{id} - Webhook sil

// Webhook oluşturma örneği
POST /api/seller/webhooks
{
    "event_type": "order.created",
    "url": "https://your-domain.com/webhook-handler",
    "secret": "your-secret-key" // Opsiyonel, otomatik oluşturulur
}

// Webhook payload örneği
{
    "event": "order.created",
    "timestamp": "2026-01-03T10:30:00Z",
    "data": {
        "order_id": 123,
        "code": "20260103-001",
        "grand_total": "150.00"
    }
}

// Header'da imza kontrolü
X-Webhook-Signature: sha256_hmac_signature

Performans Metrikleri

Örnek Kodlar

cURL Örneği

curl -X POST https://www.giyimmoda.com.tr/api/seller/products/bulk \
  -H "X-API-Key: sk_XXXXXXXXXXXX" \
  -H "X-API-Secret: xxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [...]
  }'

PHP Örneği

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.giyimmoda.com.tr/api/seller/products/bulk');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['products' => $products]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: sk_XXXXXXXXXXXX',
    'X-API-Secret: xxxxxxxxxxxxxx',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

JavaScript Örneği

const response = await fetch('https://www.giyimmoda.com.tr/api/seller/products/bulk', {
    method: 'POST',
    headers: {
        'X-API-Key': 'sk_XXXXXXXXXXXX',
        'X-API-Secret': 'xxxxxxxxxxxxxx',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        products: [...]
    })
});
const data = await response.json();

📋 Hızlı Referans: Hangi İşlem İçin Hangi Sütunlar?

✅ Sipariş Oluşturmak İçin

✅ Ürün Eklemek İçin

⚠️ Önemli Notlar

Destek

API ile ilgili sorularınız için lütfen destek ekibi ile iletişime geçin.