Kreosus API

Kreosus üretici API'si, üretici panelinizdeki verileri kendi kodunuza açar: destekçiler, ödemeler, abonelikler, istatistikler ve ödeme talepleri. Gönderi yazabilir, yayımlayabilir ve silebilir. İstekler ve yanıtlar HTTPS üzerinden JSON'dur.

Temel Adres: https://kreosus.com/api/v1
OpenAPI: kreosus.com/api/v1/openapi.json
Anahtarlar: API Erişimi

Hızlı Başlangıç

Üretici panelinizde API Erişimi sayfasını açın ve bir anahtar oluşturun. Kodunuz gönderi yazacaksa gönderi seçeneğini işaretleyin.
Anahtarı hemen kopyalayın. Anahtarı yalnızca bir kez gösteririz ve yalnızca özetini saklarız.
Anahtarı her istekte X-API-Key başlığıyla gönderin.

curl "https://kreosus.com/api/v1/profile" \
  -H "X-API-Key: $KREOSUS_API_KEY"

Kimlik Doğrulama

Anahtarınızı X-API-Key başlığıyla gönderin. Bir profilin aynı anda tek anahtarı olur. Yeni anahtar oluşturmak eskisini hemen geçersiz kılar, iptal etmek de öyle. Eksik veya yanlış anahtar 401 alır. Bir IP adresinden bir dakikada 20 başarısız denemeden sonraki denemeler 429 alır.

Her yanıt bir X-Request-Id başlığı taşır. Bize bir istekle ilgili yazarken bu değeri ekleyin.

İzinler

Her anahtar okuyabilir. Gönderi yazmak için posts:write izni gerekir. Bu izni anahtarı oluştururken seçersiniz. Anahtarın izni dışındaki bir istek INSUFFICIENT_SCOPE koduyla 403 alır ve error.details.required_scope gereken izni söyler.

`read`	Profilinizi, destekçilerinizi, ödemelerinizi, aboneliklerinizi, istatistiklerinizi, ödeme taleplerinizi ve gönderilerinizi okur.
`posts:write`	Gönderi oluşturur, düzenler, yayımlar ve siler.

Hatalar

Başarısız bir istek bir HTTP durum kodu ve bir JSON gövdesiyle yanıtlanır. error.code değişmez, kodunuzu ona göre kurun. error.message insanlar içindir ve değişebilir. Hatalı parametre error.field_errors içinde adıyla yer alır.

{
  "status": false,
  "error": {
    "message": "…",
    "code": "INVALID_FORMAT",
    "field_errors": { "from": "…" }
  }
}

`400`	`VALIDATION_FAILED, INVALID_FORMAT`	Bir parametre veya gövde alanı geçerli değil.
`401`	`AUTHENTICATION_REQUIRED`	Anahtar eksik veya geçersiz.
`403`	`INSUFFICIENT_SCOPE, PERMISSION_DENIED`	Anahtarın izni yok veya profil gönderi paylaşamıyor.
`404`	`RESOURCE_NOT_FOUND`	Uç nokta veya gönderi yok veya gönderi size ait değil.
`405`	`INVALID_REQUEST`	Uç nokta bu yöntemi kabul etmiyor. Allow başlığı kabul ettiği yöntemi söyler.
`409`	`RESOURCE_CONFLICT`	Gönderi zaten yayında.
`422`	`IDEMPOTENCY_KEY_REUSED`	Idempotency-Key daha önce başka bir istekle kullanıldı.
`429`	`RATE_LIMIT_EXCEEDED`	Çok fazla istek. Retry-After başlığındaki süre kadar bekleyin.

Hız Sınırları

Her uç noktanın profil başına kendi kotası vardır ve bir dakika üzerinden sayılır: okumalar için 30, istatistikler için 15, yazmalar için 10 istek. Aşağıda her uç noktanın kotası yazar.

Geçerli bir anahtarla yapılan her isteğin yanıtı kalan kotanızı X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıklarıyla bildirir. Reset, pencerenin kaç saniye sonra yenileneceğini gösterir. 429 yanıtındaki Retry-After başlığı kaç saniye beklemeniz gerektiğini söyler.

Listeler, Tarihler ve Tutarlar

Listeler page (1'den başlar) ve limit (1 ile 100 arası, varsayılan 20) alır. Yanıtta items, total, page, limit ve has_more bulunur. 100'den büyük limit 100 kayıt döndürür. Pozitif tam sayı olmayan page veya limit 400 alır.

from ve to bir tarih (2026-10-01) veya RFC 3339 zaman damgası (2026-10-01T09:30:00Z) alır. Tarih, İstanbul saatiyle bütün günü, zaman damgası tam o anı belirtir. Yalnızca son eşitlemenizden bu yana değişenleri almak için o eşitlemenin zamanını from olarak gönderin. Başka bir biçim 400 alır.

Tarih ve saatler İstanbul saatiyle (UTC+3) döner.

Her tutar iki kez gelir: amount: 12.5 gibi ondalıklı bir sayı olarak ve para biriminin en küçük biriminde (kuruş veya sent) tam sayı olarak, örneğin amount_minor: 1250. Tutarları toplarken veya karşılaştırırken adı _minor ile biten alanları kullanın, çünkü ondalıklı sayılar kuruşun bir kısmını kaybedebilir.

Koşullu İstekler

Her başarılı GET yanıtı bir ETag başlığı taşır. Bu değeri If-None-Match başlığıyla geri gönderin. Veri değişmediyse yanıt gövdesiz bir 304 olur. Böylece sık sorgulayan bir istemci daha az veri taşır. 304 yanıtı da kotadan düşer. Ödemeleri ve abonelikleri sorgulamadan öğrenmek için webhook kullanın.

curl -i "https://kreosus.com/api/v1/subscriptions?status=1" \
  -H "X-API-Key: $KREOSUS_API_KEY" \
  -H 'If-None-Match: W/"5d41402abc4b2a76b9719d911017c592"'

HTTP/2 304

Tekrar Oluşturmadan Yeniden Deneme

Gönderi oluşturma ve yayımlama istekleri bir Idempotency-Key başlığı kabul eder: UUID gibi en fazla 255 karakterlik benzersiz bir metin. Bağlantı koparsa aynı isteği aynı anahtarla yeniden gönderin. 24 saat boyunca ikinci bir gönderi oluşmaz, ilk yanıtı Idempotent-Replayed: true başlığıyla yeniden alırsınız. Aynı anahtar farklı bir gövdeyle 422 alır. Yalnızca başarılı yanıt saklanır: hata alan bir istek yeniden denendiğinde yeniden çalışır. İlk istek sürerken gönderilen tekrar, Retry-After başlığıyla 409 alır.

Hesap Verileri

Profil Bilgileri

GET/api/v1/profile

Profil bilgilerinizi, destek kademelerinizi ve aktif hedeflerinizi döndürür.

İzin read30 istek/dk

Yanıt

creator.idinteger
creator.titlestring
creator.urlstring
creator.currencystring
creator.imagestring | null
tiers[].idinteger
tiers[].titlestring
tiers[].descriptionstring
tiers[].amountnumber
tiers[].amount_minorinteger
tiers[].currencystring
goals[].idinteger
goals[].targetinteger
goals[].descriptionstring
goals[].imagestring | null

curl "https://kreosus.com/api/v1/profile" \
  -H "X-API-Key: $KREOSUS_API_KEY"

Destekçileri Listele

GET/api/v1/supporters

Bu profile ödeme yapmış herkes, toplamı en yüksek olan başta.

İzin read30 istek/dk

Parametreler

Ad	Tür	Varsayılan	Açıklama
`page`	integer	1	Sayfa numarası
`limit`	integer	20	Sayfa başına kayıt. (maks. 100)
`search`	string	-	İsim veya e-posta ile arama
`from`	string (date-time)	-	Başlangıç, tarih veya RFC 3339 zaman damgası.
`to`	string (date-time)	-	Bitiş, tarih veya RFC 3339 zaman damgası.

Yanıt

items[].idstring
items[].namestring
items[].emailstring
items[].total_amountnumber
items[].total_amount_minorinteger
items[].currencystring
items[].is_subscriberboolean
items[].first_payment_datestring
items[].vat_countrystring | null
items[].vat_percentnumber

curl "https://kreosus.com/api/v1/supporters?limit=10" \
  -H "X-API-Key: $KREOSUS_API_KEY"

Ödemeleri Listele

GET/api/v1/payments

Bu profile yapılan her ödeme, en yenisi başta, kesintileri ve net tutarıyla.

İzin read30 istek/dk

Parametreler

Ad	Tür	Varsayılan	Açıklama
`page`	integer	1	Sayfa numarası
`limit`	integer	20	Sayfa başına kayıt. (maks. 100)
`status`	integer	-	1 başarılı, 2 başarısız, 3 iade, 4 dolandırıcılık nedeniyle geri alındı. Şunlardan biri: 1, 2, 3, 4
`from`	string (date-time)	-	Başlangıç, tarih veya RFC 3339 zaman damgası.
`to`	string (date-time)	-	Bitiş, tarih veya RFC 3339 zaman damgası.

Yanıt

items[].idstring
items[].supporter_namestring
items[].supporter_emailstring
items[].amountnumber
items[].amount_minorinteger
items[].currencystring
items[].vat_amountnumber
items[].vat_amount_minorinteger
items[].stripe_feenumber
items[].stripe_fee_minorinteger
items[].platform_feenumber
items[].platform_fee_minorinteger
items[].net_amountnumber
items[].net_amount_minorinteger
items[].statusinteger
items[].messagestring | null
items[].is_subscriptionboolean
items[].datestring

curl "https://kreosus.com/api/v1/payments?from=2026-10-01T00:00:00%2B03:00&status=1" \
  -H "X-API-Key: $KREOSUS_API_KEY"

Abonelikleri Listele

GET/api/v1/subscriptions

Bu profile yapılan aylık abonelikler.

İzin read30 istek/dk

Parametreler

Ad	Tür	Varsayılan	Açıklama
`page`	integer	1	Sayfa numarası
`limit`	integer	20	Sayfa başına kayıt. (maks. 100)
`status`	integer	-	1 aktif, 0 iptal. Şunlardan biri: 0, 1

Yanıt

items[].idstring
items[].supporter_namestring
items[].supporter_emailstring
items[].amountnumber
items[].amount_minorinteger
items[].currencystring
items[].statusinteger
items[].subscription_datestring
items[].last_payment_datestring | null
items[].vat_countrystring | null
items[].vat_percentnumber
items[].total_paidnumber
items[].total_paid_minorinteger

curl "https://kreosus.com/api/v1/subscriptions?status=1" \
  -H "X-API-Key: $KREOSUS_API_KEY"

İstatistikler

GET/api/v1/statistics

Bütün günlerden oluşan bir aralığın toplamları, tüm zamanların toplamları ve güncel bakiye ile birlikte.

İzin read15 istek/dk

Parametreler

Ad	Tür	Varsayılan	Açıklama
`from`	string (date)	Son 30 gün	İlk gün (YYYY-AA-GG).
`to`	string (date)	Bugün	Son gün (YYYY-AA-GG).

Yanıt

currencystring
period.fromstring
period.tostring
total_amountnumber
total_amount_minorinteger
total_amount_all_timenumber
total_amount_all_time_minorinteger
total_transactionsinteger
total_transactions_all_timeinteger
new_subscribersinteger
new_subscribers_all_timeinteger
active_monthly_supportersinteger
one_time_supportersinteger
account_balancenumber
account_balance_minorinteger
stripe_feenumber
stripe_fee_minorinteger
platform_feenumber
platform_fee_minorinteger

curl "https://kreosus.com/api/v1/statistics?from=2026-01-01&to=2026-03-31" \
  -H "X-API-Key: $KREOSUS_API_KEY"

Ödeme Talepleri

GET/api/v1/payouts

Ödeme talepleriniz, en yenisi başta.

İzin read30 istek/dk

Parametreler

Ad	Tür	Varsayılan	Açıklama
`page`	integer	1	Sayfa numarası
`limit`	integer	20	Sayfa başına kayıt. (maks. 100)

Yanıt

items[].idstring
items[].amountnumber
items[].amount_minorinteger
items[].currencystring
items[].statusinteger
items[].payout_typestring | null
items[].create_datestring
items[].notestring | null

curl "https://kreosus.com/api/v1/payouts?limit=50" \
  -H "X-API-Key: $KREOSUS_API_KEY"

Gönderiler

Gönderileri Listele

GET/api/v1/posts

Yayındaki gönderileriniz veya taslaklarınız, en yenisi başta. Yalnızca destekçilerin açabildikleri dahil her gönderiyi tam görürsünüz.

İzin read30 istek/dk

Parametreler

Ad	Tür	Varsayılan	Açıklama
`page`	integer	1	Sayfa numarası
`limit`	integer	20	Sayfa başına kayıt. (maks. 100)
`status`	string	live	Yayındaki gönderiler veya taslaklar. Şunlardan biri: live, draft

Yanıt

items[].idinteger
items[].urlstring
items[].statusstring
items[].contentstring
items[].imagesstring[]
items[].visibilitystring
items[].visibility_scheduleobject[] | null
items[].locked_viewstring
items[].like_countinteger
items[].comment_countinteger
items[].created_atstring
items[].edited_atstring | null

curl "https://kreosus.com/api/v1/posts?status=draft" \
  -H "X-API-Key: $KREOSUS_API_KEY"

Gönderiyi Getir

GET/api/v1/posts/{id}

Adresindeki kimliğe göre gönderilerinizden veya taslaklarınızdan biri.

İzin read30 istek/dk

Parametreler

Ad	Tür	Varsayılan	Açıklama
`id`	integer	-	Gönderinin adresindeki kimlik.

Yanıt

post.idinteger
post.urlstring
post.statusstring
post.contentstring
post.imagesstring[]
post.visibilitystring
post.visibility_scheduleobject[] | null
post.locked_viewstring
post.like_countinteger
post.comment_countinteger
post.created_atstring
post.edited_atstring | null

curl "https://kreosus.com/api/v1/posts/1024" \
  -H "X-API-Key: $KREOSUS_API_KEY"

Gönderi Oluştur

POST/api/v1/posts

Gönderiyi hemen yayımlar veya taslak olarak kaydeder. Gönderide metin veya en az bir görsel olmalıdır. Panelden paylaşılan gönderide olduğu gibi anılan kullanıcılar bildirim alır. Yanıt, gönderiyle birlikte 201'dir.

İzin posts:write10 istek/dkIdempotency-Key kabul eder

JSON Gövdesi

Ad	Tür	Varsayılan	Açıklama
`content`	string	-	Metin, en fazla 10.000 karakter. Görsel göndermiyorsanız zorunludur.
`visibility`	string	public	Gönderiyi kimlerin açabileceği. Şunlardan biri: public, active_supporters, all_supporters, custom
`schedule`	array	-	custom görünürlükte, her biri öncekinden geniş en fazla 4 aşama: {"audience": "tier", "tier_id": 12, "days": 3}. audience tier, active_supporters, all_supporters veya public olur. Son aşama dışında her aşamada days (1 ile 365 arası) bulunur.
`locked_view`	string	teaser_countdown	custom görünürlükte, aşaması açılmamış kişilerin gördüğü: teaser_countdown, teaser veya hidden.
`images`	array	-	base64 veri adresi (data:image/jpeg;base64,...) olarak en fazla 4 görsel. Her birinin eni ve boyu 100 ile 4096 piksel arasında olmalıdır. Okuyamadığımız görsel eklenmez.
`draft`	boolean	false	true, yayımlamak yerine taslak kaydeder.

Yanıt

post.idinteger
post.urlstring
post.statusstring
post.contentstring
post.imagesstring[]
post.visibilitystring
post.visibility_scheduleobject[] | null
post.locked_viewstring
post.like_countinteger
post.comment_countinteger
post.created_atstring
post.edited_atstring | null

curl -X POST "https://kreosus.com/api/v1/posts" \
  -H "X-API-Key: $KREOSUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"content": "Yeni bölüm yayında!", "visibility": "all_supporters"}'

Gönderiyi Düzenle

PATCH/api/v1/posts/{id}

Yalnızca gönderdiğiniz alanları değiştirir. Göndermediğiniz alan değerini korur.

İzin posts:write10 istek/dk

Parametreler

Ad	Tür	Varsayılan	Açıklama
`id`	integer	-	Gönderinin adresindeki kimlik.

JSON Gövdesi

Ad	Tür	Varsayılan	Açıklama
`content`	string	-	Metin, en fazla 10.000 karakter. Görsel göndermiyorsanız zorunludur.
`visibility`	string	-	Gönderiyi kimlerin açabileceği. Şunlardan biri: public, active_supporters, all_supporters, custom
`schedule`	array	-	custom görünürlükte, her biri öncekinden geniş en fazla 4 aşama: {"audience": "tier", "tier_id": 12, "days": 3}. audience tier, active_supporters, all_supporters veya public olur. Son aşama dışında her aşamada days (1 ile 365 arası) bulunur.
`locked_view`	string	-	custom görünürlükte, aşaması açılmamış kişilerin gördüğü: teaser_countdown, teaser veya hidden.
`images`	array	-	base64 veri adresi (data:image/jpeg;base64,...) olarak en fazla 4 görsel. Her birinin eni ve boyu 100 ile 4096 piksel arasında olmalıdır. Okuyamadığımız görsel eklenmez.
`keep_images`	array	-	Korunacak mevcut görsellerin sırası (0'dan başlar). Tüm görselleri korumak için keep_images ve images alanlarını hiç göndermeyin. images içindeki yeni görseller korunanların ardından eklenir, toplam en fazla 4.

Yanıt

post.idinteger
post.urlstring
post.statusstring
post.contentstring
post.imagesstring[]
post.visibilitystring
post.visibility_scheduleobject[] | null
post.locked_viewstring
post.like_countinteger
post.comment_countinteger
post.created_atstring
post.edited_atstring | null

curl -X PATCH "https://kreosus.com/api/v1/posts/1024" \
  -H "X-API-Key: $KREOSUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Yeni bölüm yayında! Bağlantı açıklamada."}'

Gönderiyi Sil

DELETE/api/v1/posts/{id}

Bir gönderiyi veya taslağı siler. Bu işlem geri alınamaz.

İzin posts:write10 istek/dk

Parametreler

Ad	Tür	Varsayılan	Açıklama
`id`	integer	-	Gönderinin adresindeki kimlik.

Yanıt

idinteger
deletedboolean

curl -X DELETE "https://kreosus.com/api/v1/posts/1024" \
  -H "X-API-Key: $KREOSUS_API_KEY"

Taslağı Yayımla

POST/api/v1/posts/{id}/publish

Bir taslağı yayımlar. Zaten yayında olan bir gönderi 409 alır.

İzin posts:write10 istek/dkIdempotency-Key kabul eder

Parametreler

Ad	Tür	Varsayılan	Açıklama
`id`	integer	-	Gönderinin adresindeki kimlik.

Yanıt

post.idinteger
post.urlstring
post.statusstring
post.contentstring
post.imagesstring[]
post.visibilitystring
post.visibility_scheduleobject[] | null
post.locked_viewstring
post.like_countinteger
post.comment_countinteger
post.created_atstring
post.edited_atstring | null

curl -X POST "https://kreosus.com/api/v1/posts/1024/publish" \
  -H "X-API-Key: $KREOSUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Webhook Olayları

Bir ödeme ya da abonelik değiştiğinde Kreosus, imzalı bir JSON isteğini HTTPS adresinize gönderir. Böylece API'yi sürekli sorgulamanız gerekmez.

payment.succeeded payment.refunded payment.reversed subscription.created subscription.canceled ping

Olaylar: payment.succeeded, payment.refunded, payment.reversed, subscription.created, subscription.canceled. payment.reversed, ödemenin dolandırıcılık ya da kaybedilen bir ters ibraz nedeniyle geri alındığını bildirir. Bu olayda da payment.refunded olayındaki gibi erişimi sonlandırın. İşlemediğiniz olay türlerine de 2xx ile yanıt verin. Yeni olay türleri ekleyebiliriz ve sürekli başarısız olan bir olay webhook'u kapatır. data.object alanı, ilgili API uç noktasının döndürdüğü kaydın olay anındaki hâlidir.

Her isteğin Kreosus-Signature başlığı t=<zaman>,v1=<imza> biçimindedir. İmza, "<zaman>.<istek gövdesi>" metninin imza anahtarınızla HMAC-SHA256 özetidir. İmzayı doğrulayın ve 5 dakikadan eski zaman damgalarını reddedin.

import crypto from 'node:crypto';

// rawBody: the request body exactly as received, before any JSON parsing.
export function verifyKreosusSignature(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((part) => part.split('=')));
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  return fresh && v1?.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Alıcınız 5 saniye içinde 2xx ile yanıt vermezse gönderimi 1 dk, 5 dk, 30 dk, 1 sa, 3 sa, 6 sa, 12 sa ve 24 sa sonra yeniden deneriz. Aynı olay birden çok kez gelebilir. Kreosus-Event-Id başlığına göre tekrarları ayıklayın. Bir olay son denemede de iletilemezse ve bu sürede başka hiçbir olay iletilmediyse webhook'u kapatır ve size e-posta göndeririz. Kapalıyken yeni olay sıraya alınmaz. Bir test olayı iletildiğinde ya da adresi yeniden kaydettiğinizde webhook yeniden açılır.

Değişiklikler

2026-10-23: Gönderi uç noktaları, anahtar izinleri, ETag ve If-None-Match, Idempotency-Key, from ve to için RFC 3339 zaman damgaları, hatalı parametrelere 400, en küçük para biriminde tutarlar (_minor alanları) ve OpenAPI belgesi.
2026-10-18: Ödemeler ve abonelikler için imzalı webhook'lar. Her yanıtta kota başlıkları ve X-Request-Id.
2026-04-09: İlk sürüm: profil, destekçiler, ödemeler, abonelikler, istatistikler ve ödeme talepleri.