Abonelikler: Genel Bakış

Abonelik endpoint'leri, kullanıcı aboneliklerini kendi sisteminizden (faturalandırma/CRM) Loyetta'ya yansıtmanızı sağlar. Her abonelik, sizin sahip olduğunuz bir external_id ile anahtarlanır — yenileme, değiştirme, iptal etme veya meta güncelleme gibi sonraki her çağrıda bu değeri geri gönderirsiniz.

Tüm abonelik endpoint'leri superuser erişim tokeni (loy_sk_live_xxxx) gerektirir. Yalnızca backend'inizden çağırın. Superuser Genel Bakış sayfasına bakın.

Neden bu endpoint'ler aracılığıyla entegre etmelisiniz

Her abonelik değişikliği, gerçek zamanlı olarak dinamik segmentasyonu ve kampanya koşullarını besleyen bir yaşam döngüsü olayı (lifecycle event) kaydeder. Bu nedenle abonelik durumunu satırları doğrudan yazmak yerine bu endpoint'ler aracılığıyla yönetmelisiniz — kampanyaların kullanıcıları abone oldukları, yeniledikleri, değiştirdikleri veya iptal ettikleri anda ödüllendirmesini sağlayan şey bu olaylardır.

Ön Koşullar

Geçerli bir superuser erişim tokeni (super_user yetkisine sahip)
Referans verdiğiniz kullanıcı ve ürün tenant'ta zaten mevcut olmalı

Abone Ol ve Değiştir işlemlerinde ürünü ya product_id (Loyetta ULID) ya da sku (kendi ürün kodunuz) ile tanımlayın — hangisi elinizde varsa onu gönderin. İkisi birden gönderilirse product_id öncelikli olur.

Temel URL & Header'lar

https://{customer-id}.prod.loyetta.com/api/v1/superuser

Header	Değer	Zorunlu
`Authorization`	`Bearer loy_sk_live_xxxx`	Evet
`Content-Type`	`application/json`	Evet
`Accept`	`application/json`	Evet

`external_id`

external_id, abonelik için sizin tanımlayıcınızdır (ör. faturalandırma sisteminizdeki ID). Şu özelliklere sahiptir:

Abone olurken zorunlu ve benzersizdir.
Diğer her endpoint için arama anahtarıdır — yenileme, değiştirme, iptal ve meta işlemlerinin tümü aboneliği bir Loyetta ID'si veya URL yol parametresi ile değil, external_id ile bulur.

Enum'lar

Enum	Değerler
`period`	`daily`, `weekly`, `monthly`, `yearly`
`status` (sistem tarafından yönetilir)	`active`, `expired`, `cancelled`

status asla doğrudan ayarlanmaz. Abone olma/yenileme sırasında active, iptal sırasında cancelled olur. expired, platformun hedefleme (segmentasyon & kampanyalar) için tanıdığı bir durumdur ancak mevcut sürümde bu endpoint'ler tarafından ayarlanmaz.

Abonelik Nesnesi (yanıt)

json

{
  "id": "01JQ...",
  "external_id": "sub_12345",
  "product_id": "01JQ...",
  "user_id": "01JQ...",
  "status": "active",
  "period": "monthly",
  "started_at": "2026-03-26T00:00:00.000000Z",
  "ended_at": null,
  "due_at": "2026-04-26T00:00:00.000000Z"
}

Dahili olarak her abonelik ayrıca yenileme geçmişini (yenileme sayısı, son yenileme zaman damgası) ve serbest formatlı bir meta nesnesini de takip eder. Bunlar segmentasyon ve kampanya kurallarını besler ancak bu yanıt nesnesinde geri döndürülmez.

Endpoint'ler

Endpoint	Açıklama
Abone Ol — `POST /subscribe`	Yeni bir abonelik oluştur
Yenile — `POST /subscriptions/renew`	Bir sonraki döngü için yenile
Değiştir — `POST /subscriptions/change`	Farklı bir ürüne geç
İptal Et — `POST /subscriptions/cancel`	Bir aboneliği iptal et
Meta Güncelle — `POST /subscriptions/meta`	`meta` nesnesini değiştir

Yaşam Döngüsü Olayları

Her değişiklik bir abonelik yaşam döngüsü olayı kaydeder:

Olay	Tetikleyen
`subscribed`	`POST /subscribe`
`renewed`	`POST /subscriptions/renew`
`changed`	`POST /subscriptions/change`
`cancelled`	`POST /subscriptions/cancel`
`expired`	Sistem tarafından yönetilir

Hata Yanıtları

403 — Yasak (token super_user yetkisine sahip değil)

json

{
  "message": "Operation not allowed."
}

422 — İşlenemeyen İçerik (doğrulama başarısız)

json

{
  "message": "The given data was invalid.",
  "errors": {
    "field_name": ["Error message"]
  }
}

Yaygın doğrulama nedenleri: eksik zorunlu alan, mevcut olmayan bir user_id/product_id, abone olurken yinelenen bir external_id, yenileme/değiştirme/iptal/meta sırasında bilinmeyen bir external_id, geçersiz bir period veya started_at'tan sonra olmayan bir due_at.