KartFiyat API Docs
REST API
v1 · REST v3 · GraphQL
Ana Sayfa

İlan Yönetimi Plus

Pazardaki ilanları arayın, kendi ilanlarınızı yönetin (fiyat, içerik, yayın durumu, silme) ve ilanlarınızı öne çıkarın.

Plus Paketi Gerektirir

Bu sayfadaki endpoint'ler yalnızca Plus (ve üstü: Kurumsal) paketinde çalışır. Diğer paketlerle istek yapıldığında 403 PLAN_UPGRADE_REQUIRED hatası döner. Tüm istekler Authorization: Bearer YOUR_API_KEY başlığı ile gönderilir ve işlemler API anahtarının sahibi olan kullanıcı hesabı üzerinde yapılır.

Yazma işlemleri yalnızca kendi ilanlarınızda çalışır. Başkasına ait bir ilan id'si gönderilirse 422 PLUS_LISTING_ERROR ("Bu ilan size ait değil.") döner.

GET /api/v1/plus/listings

Yayındaki (onaylı ve stoklu) ilanlarda arama yapar, sayfalı sonuç döner.

Query Parametreleri

Parametre Tip Varsayılan Açıklama
search string - İlan/ürün adında arama
seller_name string - Satıcı adına göre filtrele
set_name string - Set adına göre filtrele
category string - Kategori slug'ı
type string - single, card, sealed, bundle
min_price / max_price numeric - Fiyat aralığı (TL)
min_pc / max_pc numeric - PriceCharting çarpanı aralığı
game[] array - Oyun filtresi (pokemon, onepiece …)
language[] array - Dil filtresi
grade_filters[] array - Grade/grup id'leri (PSA 10, CGC 9 …)
sort_by string popular latest, price_low, price_high, pc_multiplier_asc, pc_multiplier_desc, popular
per_page integer 20 Sayfa başına ilan (max: 100)
page integer 1 Sayfa numarası

Opsiyonel Alanlar

Yanıt varsayılan olarak sadeidir. Aşağıdaki bayrakları 1 göndererek ek alanlar isteyebilirsiniz. Bu bayraklar /plus/listings ve /plus/my-listings için geçerlidir.

Bayrak Eklenen Alan Açıklama
with_item item Ürün bilgisi (id, name, code, slug, genre, game)
with_pc pc_multiplier PriceCharting fiyatına göre çarpan
with_average average_price Aynı ürünün son 10 satışının ortalaması
with_last_sales last_sales Aynı ürünün son 10 satışı (fiyat + tarih)

Örnek İstek

curl -X GET "https://kartfiyat.com/api/v1/plus/listings?search=charizard&min_price=500&sort_by=price_low&with_item=1&with_average=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Örnek Yanıt

{
  "success": true,
  "data": [
    {
      "id": 5044,
      "title": "Charizard VMAX PSA 10",
      "slug": "charizard-vmax-psa-10-5044",
      "price": 12500.00,
      "item": {
        "id": 12345,
        "name": "Charizard VMAX",
        "code": "SWSH020",
        "slug": "charizard-vmax-swsh020",
        "genre": "single",
        "game": "pokemon"
      },
      "average_price": 11980.50
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total": 64,
    "last_page": 4,
    "has_more": true
  }
}
GET /api/v1/plus/my-listings

Kendi ilanlarınızı listeler (tüm durumlar dahil), en yeni önce.

Query Parametreleri

Parametre Tip Varsayılan Açıklama
status string - Duruma göre filtrele (active, pending, paused, sold …)
per_page integer 20 Sayfa başına ilan (max: 100)

Kendi ilanlarınızda yanıta ek olarak status ve approved_price alanları da döner.

Örnek Yanıt

{
  "success": true,
  "data": [
    {
      "id": 5044,
      "title": "Charizard VMAX PSA 10",
      "slug": "charizard-vmax-psa-10-5044",
      "price": 12500.00,
      "status": "active",
      "approved_price": 12500.00
    }
  ],
  "pagination": { "current_page": 1, "per_page": 20, "total": 7, "last_page": 1, "has_more": false }
}
GET /api/v1/plus/recent-sales

Pazardaki son satışları listeler. Satıcı bilgisi paylaşılmaz.

Örnek Yanıt

{
  "success": true,
  "data": [
    {
      "item": {
        "id": 12345,
        "name": "Charizard VMAX",
        "code": "SWSH020",
        "slug": "charizard-vmax-swsh020"
      },
      "price": 11750.00,
      "sold_at": "2026-07-26T18:42:11+03:00"
    }
  ],
  "pagination": { "current_page": 1, "per_page": 20, "total": 312, "last_page": 16, "has_more": true }
}
PATCH /api/v1/plus/listings/{id}/price

Kendi ilanınızın fiyatını günceller. Yalnızca fiyat değiştiği için ilan onaya düşmez.

Gövde Parametreleri

Parametre Tip Zorunlu Açıklama
price numeric Evet Yeni fiyat (min: 1, max: 9.999.999)

Örnek İstek

curl -X PATCH "https://kartfiyat.com/api/v1/plus/listings/5044/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"price": 11900}'

Örnek Yanıt

{
  "success": true,
  "message": "Fiyat güncellendi.",
  "data": {
    "id": 5044,
    "price": 11900.00,
    "status": "active"
  }
}
PATCH /api/v1/plus/listings/{id}

İlan bilgilerini günceller. Gönderilen alanlar uygulanır (kısmi güncelleme).

Dikkat: Fiyat dışında bir alan gönderirseniz ilan yeniden onaya alınır (status: "pending") ve onaylanana kadar yayında görünmez. Sadece fiyat değiştirmek istiyorsanız /plus/listings/{id}/price endpoint'ini kullanın.

Gövde Parametreleri

Parametre Tip Açıklama
price numeric Fiyat (min: 1, max: 9.999.999)
title string İlan başlığı (max: 255)
description string Açıklama (max: 5000)
shipping_payer string Kargoyu kim öder: buyer veya seller
offers_enabled boolean Teklif almayı aç/kapat
min_offer_price numeric Kabul edilecek en düşük teklif

Örnek Yanıt

{
  "success": true,
  "message": "Güncellendi. Fiyat dışı değişiklik nedeniyle ilan onaya alındı.",
  "data": {
    "id": 5044,
    "price": 11900.00,
    "status": "pending"
  }
}
POST /api/v1/plus/listings/{id}/status

İlanı yayından kaldırır veya yeniden yayına alır.

Query Parametreleri

Parametre Tip Zorunlu Açıklama
action string Evet pause (yayından kaldır) veya publish (yayına al)

publish işlemi ilanı doğrudan yayına almayabilir; mevcut satıcı akışında ilan yeniden onaya düşebilir. Sonuç data.status alanında döner.

Örnek İstek

curl -X POST "https://kartfiyat.com/api/v1/plus/listings/5044/status?action=pause" \
  -H "Authorization: Bearer YOUR_API_KEY"

Örnek Yanıt

{
  "success": true,
  "message": "Durum güncellendi.",
  "data": { "id": 5044, "status": "paused" }
}
DELETE /api/v1/plus/listings/{id}

Kendi ilanınızı siler. İşlem geri alınamaz.

Örnek Yanıt

{
  "success": true,
  "message": "İlan silindi."
}
POST /api/v1/plus/make-highlight

İlanı öne çıkarır. Hesabınızdaki öne çıkarma hakkından bir adet düşer.

Parametreler

Parametre Tip Zorunlu Açıklama
id integer Evet İlan id'si (query veya gövde ile gönderilebilir)

Örnek İstek

curl -X POST "https://kartfiyat.com/api/v1/plus/make-highlight?id=5044" \
  -H "Authorization: Bearer YOUR_API_KEY"

Örnek Yanıt

{
  "success": true,
  "message": "İlan öne çıkarıldı.",
  "data": {
    "id": 5044,
    "remaining_highlight_credits": 3
  }
}

Hatalar

Bu sayfadaki tüm yazma işlemleri hata durumunda 422 ile PLUS_LISTING_ERROR kodunu döner; sebep error.message alanındadır (örn. "İlan bulunamadı.", "Bu ilan size ait değil.", "Geçersiz işlem. \"pause\" veya \"publish\" kullanın."). 

{
  "success": false,
  "error": {
    "code": "PLUS_LISTING_ERROR",
    "message": "Bu ilan size ait değil."
  }
}