Kavramlar

Akış, staging, sahiplik, fiyat modeli ve metadata şeması

Hızlı Deneme

Kurulum gerektirmeyen en kolay yol — Swagger:

/api/docs adresini açın.
Sağ üstteki Authorize'a tıklayıp API anahtarınızı girin (Bearer ile).
Bir uca tıklayın → Try it out → gövdeyi düzenleyin → Execute.

Postman / Insomnia için hazır dosya indirmeyin — güncel uç listesini içe aktarın:

Postman → Import → Link.
Şu adresi yapıştırın: https://import.libraryturk.com/swagger/v1/swagger.json
İçe aktarılan istekler her zaman günceldir. Authorization başlığına Bearer <anahtarınız> ekleyin.

Anahtarınızı paylaşmayın/dosyaya gömmeyin. İçe aktarılan tanım yalnız yayıncı uçlarını içerir; yönetim uçları görünmez.

Genel Akış

Import API ile gönderdiğiniz hiçbir içerik kataloğa anında yansımaz. Akış şöyledir:

Gönder — kitap/dosya/metadata veya fiyat gönderirsiniz; anında bir trackingId alırsınız.
Staging — gönderiminiz bir bekleme alanına (inbox) düşer; durumu Alindi olur.
İşleme — LibraryTürk ekibi/ingestion gönderimi review eder, eşler ve uygular.
Sonuç — durumu uploads/{trackingId} ile sorgular veya bir webhook kaydederek sonucu otomatik alırsınız.

Staging (Neden Hemen Değişmez?)

Veri kalitesi ve güvenlik için tüm yazımlar staging'dir: doğrudan canlı kataloğa (tblEKitap vb.) yazılmaz. Bu, hatalı/eksik gönderimlerin kataloğu bozmasını engeller. Gönderiminiz review'dan geçtikten sonra uygulanır.

trackingId (Takip Kimliği)

Her başarılı gönderim bir trackingId (GUID) döndürür. Bununla durumu sorgularsınız: yüklemeler için GET /api/v1/import/uploads/{trackingId}, metadata talepleri için GET /api/v1/import/metadata-requests/{trackingId}, fiyatlar için GET /api/v1/import/price/submissions/{trackingId}.

Sahiplik

Bir kitaba işlem yaparken (kaynakça, fiyat, metadata talebi) bookId sizin yayıncınıza veya bir alt yayıncınıza ait olmalıdır. Aksi halde 404 dönülür (güvenlik gereği "var ama sizin değil" ile "hiç yok" ayırt edilmez). 404 alıyorsanız: bookId değerinin sizin yayıncınıza ait, aktif (silinmemiş) bir kitap olduğundan emin olun.

Durum Akışı

Durum	Anlam
`Alindi`	Gönderim alındı, staging'de bekliyor.
`Beklemede`	Metadata talebi review bekliyor.
`Islendi / Uygulandi`	Review tamam, kataloğa uygulandı.
`Hata`	İşlenemedi; gerekçe yanıtta/webhook'ta döner.

Fiyat Modeli

Beş bağımsız mutlak fiyat vardır (hiçbiri diğerinden hesaplanmaz):

Alan	Tip	Anlam
`price30`	number	30 günlük erişim fiyatı (TL).
`price90`	number	90 günlük erişim fiyatı.
`price365`	number	1 yıllık (365 gün) erişim fiyatı.
`price3Years`	number	3 yıllık erişim fiyatı.
`printedPrice`	number	Basılı kitap fiyatı.

Dört fiyat ucu farklı işler:

Uç	Ne yapar
`price/preview`	Bir oran (±%/±TL) uygulanınca oluşacak fiyatları gösterir — kaydetmez.
`price/book`	Tek kitaba mutlak fiyatları yazar.
`price/list`	Birden çok kitaba mutlak fiyat listesi yazar.
`price/bulk-rate`	Tüm kitaplara toplu oran (±%/±TL) uygular. Önce `preview` ile görün.

Metadata Şeması (ImportKitapMetadata)

POST /api/v1/import/book ucundaki metadata alanı bu şemada bir JSON'dur. Tüm alanlar opsiyoneldir; gönderilmeyenler boş geçilir. API yalnızca "geçerli JSON mu?" kontrol eder — eksik alan reddedilmez (LibraryTürk ekibi review'da eşler/tamamlar). Tanımsız ek alanlar da korunur.

Alan	Tip	Anlam
`title`	string	Kitap adı.
`isbn`	array	ISBN listesi: [{ "number": "978…", "type": "t" }]. type: "t"=basılı, "e"=elektronik.
`doi`	string	DOI (örn. 10.1234/abc).
`edition`	number	Baskı numarası.
`pageCount`	number	Sayfa sayısı.
`publicationDate`	date	Yayın tarihi — ISO 8601 (örn. 2026-01-15).
`languageId`	number	Dil kimliği (LibraryTürk dil listesi).
`categoryId`	number	Kategori kimliği.
`subjectId`	number	Bilim dalı / orta seviye konu (mezo).
`topicIds`	number[]	Alt konu kimlikleri.
`summary`	string	Kitap özeti (HTML kabul edilir; düz metne indirilir).
`tableOfContents`	string	İçindekiler.
`index`	string	Dizin.
`authors`	array	Yazarlar — alt şema aşağıda.
`keywords`	string[]	Anahtar kelimeler.
`price`	object	Fiyatlar — alt şema aşağıda.
`institutionalSale`	boolean	Kurumsal satışa açık mı.
`individualSale`	boolean	Bireysel satışa açık mı.
`publisherId`	number	Hedef yayıncı: kendiniz veya bir ALT yayıncınız. Boş bırakılırsa kitap, anahtarın yayıncısına atanır.

authors[] alt şeması

Alan	Tip	Anlam
`firstName`	string	Ad.
`lastName`	string	Soyad.
`orcid`	string	ORCID (örn. 0000-0002-1825-0097).
`organizationName`	string	Kurum adı.
`ror`	string	ROR kimliği (Research Organization Registry).
`isni`	string	ISNI kimliği.
`order`	number	Yazar sırası (1, 2, …).

price alt şeması

Alan	Tip	Anlam
`price30`	number	30 günlük erişim fiyatı (TL).
`price90`	number	90 günlük erişim fiyatı.
`price365`	number	1 yıllık (365 gün) erişim fiyatı.
`price3Years`	number	3 yıllık erişim fiyatı.
`printedPrice`	number	Basılı kitap fiyatı.

Örnek metadata JSON

JSON
{
  "title": "Üroloji Ders Kitabı",
  "isbn": [
    { "number": "9786051234567", "type": "t" },
    { "number": "9786051234574", "type": "e" }
  ],
  "doi": "10.1234/uroloji.2026",
  "edition": 2,
  "pageCount": 480,
  "publicationDate": "2026-01-15",
  "languageId": 1,
  "categoryId": 12,
  "subjectId": 45,
  "topicIds": [101, 102],
  "summary": "Kitabın kısa özeti…",
  "authors": [
    { "firstName": "Ahmet", "lastName": "Yılmaz", "orcid": "0000-0002-1825-0097", "order": 1 }
  ],
  "keywords": ["üroloji", "tıp"],
  "price": { "price30": 30, "price90": 45, "price365": 60, "price3Years": 90, "printedPrice": 120 },
  "institutionalSale": true,
  "individualSale": true,
  "publisherId": 53
}

Bu JSON, import/book isteğinde multipart/form-data içinde metadata alanına string olarak konur; file alanına da PDF eklenir.