Koleksiyonlar Plus

Kendi koleksiyonlarınızı listeleyin; koleksiyona kayıt ekleyin, güncelleyin ve çı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.

Koleksiyonların kendisi API üzerinden oluşturulmaz; site üzerinden açtığınız koleksiyonların içeriğini yönetirsiniz. Size ait olmayan bir koleksiyon id'si gönderilirse 422 PLUS_COLLECTION_ERROR ("Bu koleksiyon size ait değil.") döner.

GET /api/v1/plus/collections

Koleksiyonlarınızı kayıt sayılarıyla birlikte listeler (sayfalama yok).

Örnek İstek

curl -X GET "https://kartfiyat.com/api/v1/plus/collections" \
  -H "Authorization: Bearer YOUR_API_KEY"

Örnek Yanıt

{
  "success": true,
  "data": [
    {
      "id": 18,
      "name": "Vintage Pokemon",
      "description": "1999-2003 arası kartlar",
      "visibility": "private",
      "items_count": 142
    }
  ]
}

GET /api/v1/plus/collections/{id}/items

Bir koleksiyondaki tüm kayıtları döner (en yeni önce).

Kayıt Alanları

Alan	Tip	Açıklama
id	integer	Koleksiyon kaydının id'si (güncelleme/silmede kullanılır)
item_id	integer	Ürün id'si
item_name / item_slug	string	Ürün adı ve slug'ı
group_label	string\|null	Kondisyon/grup etiketi (örn. `Ungraded`, `PSA 10`)
quantity	integer	Adet
purchase_price	float\|null	Alış fiyatı
sale_price	integer\|null	Satış fiyatı (tam sayıya yuvarlanır)
purchase_date	date\|null	Alış tarihi (YYYY-MM-DD)
card_uniq_id	string\|null	Kendi takip kodunuz / sertifika numarası (max: 100)
note	string\|null	Not (max: 1000)

Örnek Yanıt

{
  "success": true,
  "data": [
    {
      "id": 9012,
      "item_id": 12345,
      "item_name": "Charizard VMAX",
      "item_slug": "charizard-vmax-swsh020",
      "group_label": "Ungraded",
      "quantity": 2,
      "purchase_price": 8500.00,
      "sale_price": null,
      "purchase_date": "2026-05-14",
      "card_uniq_id": null,
      "note": "Kutuda saklanıyor"
    }
  ]
}

POST /api/v1/plus/collections/{id}/items

Koleksiyona yeni kayıt ekler. Başarılı istek 201 döner.

Gövde Parametreleri

Parametre	Tip	Zorunlu	Açıklama
item_id	integer	Evet	Sistemde kayıtlı ürün id'si
item_group_type_id	integer	Hayır	Kondisyon/grup tipi. Verilmezse `Ungraded` (yoksa ilk uygun tip) seçilir
quantity	integer	Hayır	Adet (varsayılan 1, max: 100.000)
purchase_price	numeric	Hayır	Alış fiyatı (min: 0)
sale_price	numeric	Hayır	Satış fiyatı (min: 0)
purchase_date	date	Hayır	Alış tarihi (YYYY-MM-DD)
card_uniq_id	string	Hayır	Takip kodu (max: 100)
note	string	Hayır	Not (max: 1000)

Örnek İstek

curl -X POST "https://kartfiyat.com/api/v1/plus/collections/18/items" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "item_id": 12345,
    "quantity": 2,
    "purchase_price": 8500,
    "purchase_date": "2026-05-14",
    "note": "Kutuda saklanıyor"
  }'

Örnek Yanıt

{
  "success": true,
  "message": "Ürün koleksiyona eklendi.",
  "data": {
    "id": 9012,
    "item_id": 12345,
    "item_name": "Charizard VMAX",
    "group_label": "Ungraded",
    "quantity": 2
  }
}

PATCH /api/v1/plus/collections/{id}/items/{itemId}

Koleksiyon kaydını günceller. itemId, ürün id'si değil koleksiyon kaydının id'sidir.

Yalnızca gönderilen alanlar güncellenir. Güncellenebilir alanlar: quantity, purchase_price, sale_price, purchase_date, card_uniq_id, note. Fiyat/tarih/not alanlarına null göndererek değeri temizleyebilirsiniz.

Örnek İstek

curl -X PATCH "https://kartfiyat.com/api/v1/plus/collections/18/items/9012" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 3, "sale_price": 13000}'

Örnek Yanıt

{
  "success": true,
  "message": "Koleksiyon kaydı güncellendi.",
  "data": {
    "id": 9012,
    "quantity": 3,
    "sale_price": 13000
  }
}

DELETE /api/v1/plus/collections/{id}/items/{itemId}

Kaydı koleksiyondan çıkarır.

Örnek Yanıt

{
  "success": true,
  "message": "Kayıt koleksiyondan çıkarıldı."
}

Hatalar

Hatalar 422 ile PLUS_COLLECTION_ERROR kodunu döner. Olası mesajlar: "Koleksiyon bulunamadı.", "Bu koleksiyon size ait değil.", "Koleksiyon kaydı bulunamadı.", "Ürün bulunamadı."

{
  "success": false,
  "error": {
    "code": "PLUS_COLLECTION_ERROR",
    "message": "Koleksiyon kaydı bulunamadı."
  }
}