B2B için Telegram Stars API: Stars ve Premium Satışı

Ürününüzün halihazırda müşterileri, bir ödeme sayfası veya Telegram kitlesi varsa, Telegram dijital ürünleri satmak için ayrı bir teslimat operasyonu kurmanız gerekmez. MyStars Fulfilment API, arka ucunuzun bir Telegram @username kullanıcısına teslim edilecek Telegram Stars ve Telegram Premium siparişlerini oluşturmasını ve takip etmesini sağlar.

Bu, yeniden satıcılar, Telegram botları ve Mini Apps, içerik üreticisi platformları, hediye hizmetleri, sadakat programları, ajanslar, pazar yerleri ve her müşteriyi manuel bir destek akışından geçirmeden ürünlerine Telegram üzerinden satın alma seçeneği eklemek isteyen işletmeler için pratik bir çözümdür.

Telegram Stars API'sini kimler kullanmalı?

Stars veya Premium, sattığınız ürünün bir parçasıysa — kendi ekibiniz için tek seferlik manuel bir satın alma değilse — Telegram Stars API kullanın.

Tipik B2B uygulamaları şunları içerir:

• Stars paketlerini veya Premium sürelerini diğer dijital ürünlerin yanında satan yeniden satıcı vitrinleri;
• Kullanıcı adı toplayan, güncel bir fiyat teklifi gösteren ve siparişi arka uca gönderen Telegram botları ve Mini Apps;
• Ücretli gönderi, bot işlemi veya Premium deneyiminden önce kitlelerinin bakiye yüklemesine yardımcı olan içerik üreticisi ve topluluk platformları;
• Kampanya ödülünü belirli bir alıcı için Telegram Stars veya Premium'a dönüştüren hediye ve sadakat ürünleri;
• Her müşteri talebini manuel olarak işlemek yerine tekrarlanabilir bir teslimat akışına ihtiyaç duyan ajanslar ve yönetilen hizmetler;
• Denetlenebilir bir sipariş kaydına ve teslimat tamamlandığında bir olaya ihtiyaç duyan pazar yerleri.

API bir ön yüz bileşeni değil, bir teslimat katmanıdır. Ürününüz müşteri deneyimine, ödeme sayfasına ve ticari kurallara sahip olur. Sunucunuz, Telegram teslimat siparişinin fiyat teklifini almak, doğrulamak, oluşturmak, ödemek ve mutabakatını yapmak için MyStars'ı kullanır.

MyStars API üzerinden neler satabilirsiniz?

Mevcut katalog iki ürün türünü destekler:

• Telegram Stars — siparişte bir Stars miktarı kullanılır;
• Telegram Premium — siparişte ay cinsinden bir Premium süresi kullanılır.

Stars ve Premium, alıcıların farklı ihtiyaçlarını karşılar; bu yüzden bunları arayüzünüzde ayrı sunun. Stars; içerik üreticileri, kanallar, botlar ve dijital ürünler için harcanabilir bir Telegram bakiyesidir. Premium ise bir Telegram hesabı için abonelik hediyesidir. Müşteriniz API entegre etmek yerine Premium planlarını karşılaştırıyorsa, onu Telegram Premium ödeme sayfasına yönlendirin.

Paket boyutlarını, plan sürelerini, para birimlerini veya fiyatları istemci uygulamasında sabit kodlamayın. MyStars API dokümantasyonu, kataloğunuzun güncel API kurallarını izlemesi için canlı ürün, para birimi ve fiyatlandırma verileri sağlar.

API ile Telegram Stars nasıl satılır: B2B teslimat akışı

Güvenilir bir entegrasyon kısa ama bilinçli bir sıraya sahiptir. Sipariş arka ucunuzda oluşturulur; müşteri hiçbir zaman API anahtarını görmemeli veya hizmetinize ait zincir üstü ödeme talimatlarını yönetmemelidir.

1. Güncel kataloğu ve ödeme para birimlerini yükleyin. Entegrasyonunuz başlarken kullanılabilir ürünleri ve para birimlerini okuyun; bunları makul bir takvimle yenileyin. Bu, eski bir uygulama sürümünün kullanılamayan bir seçeneği sunmasını önler.
2. Canlı fiyat teklifi isteyin. Seçilen ürün, miktar veya süre ile ödeme para birimi için fiyatlandırma uç noktasına istek gönderin. Dönen tutarı ödenecek tutar olarak kullanın; fiyatı önbelleğe alınmış kur varsayımlarından oluşturmayın.
3. Ücret tahsil etmeden veya siparişi oluşturmadan önce alıcıyı kontrol edin. Alıcının Telegram @username bilgisini ve seçilen ürünü alıcı kontrolü uç noktasına gönderin. Stars alıcı kontrolü ile Premium uygunluk kontrolü birbirinin yerine kullanılamaz.
4. Tek bir idempotent sipariş oluşturun. Seçilen ürünü, alıcıyı, ödeme para birimini, webhook kullandığınızda geri çağrı URL'sini ve kendi dahili sipariş kimliğinizden üretilen sabit bir Idempotency-Key değerini gönderin.
5. Dönen ödeme talimatını aynen yerine getirin. Sipariş yanıtı hedef adresi, tutarı, notu, zinciri ve sona erme zamanını içerir. Ödeme hizmetiniz, uygulama yapılandırmasında saklanan bir cüzdan adresi veya not yerine bu değerleri aynen kullanmalıdır.
6. Nihai teslimat durumuyla mutabakat yapın. Yedek yol olarak sipariş durumu uç noktasını sorgulayın veya nihai durumu webhook'unuz üzerinden alın. Kendi müşteri siparişinizi yalnızca mutabakat kurallarınız karşılandığında tamamlandı olarak işaretleyin.

Bu sıra, bir B2B Telegram Stars API entegrasyonunu basit bir satın alma bağlantısından ayırır: her adım ürün ekibiniz tarafından saklanabilir, güvenle yeniden denenebilir, gözlemlenebilir ve desteklenebilir.

Arka ucunuzun saklaması gereken veriler

Müşteriye görünen sipariş için tek doğruluk kaynağı veritabanınızdır. Gizli bilgileri açığa çıkarmadan bir siparişi desteğe açıklamak, güvenli bir işlemi yeniden denemek ve bir blok zinciri ödemesiyle mutabakat yapmak için yeterli bilgiyi saklayın.

En azından şunları tutun:

• kendi dahili sipariş kimliğiniz ve MyStars sipariş kimliği;
• o siparişi oluşturmak için kullanılan idempotency anahtarı;
• ürün türü, Stars miktarı veya Premium süresi ve alıcı kullanıcı adı;
• fiyat teklifi verilen para birimi, tutar, zincir, sona erme zamanı ve ödeme notu;
• mutabakattan sonra zincir üstü işlem karması;
• ödeme durumunuz, MyStars sipariş durumu, webhook yükü veya sorgulama zaman damgası ve nihai teslimat sonucu.

Bir Idempotency-Key önemlidir çünkü gerçek sistemler yeniden dener. POST /v1/orders sonrasındaki ağ zaman aşımı, hiçbir şey olmadığının kanıtı değildir. Aynı sabit anahtarla yeniden denemek, arka ucunuzun aynı müşteri satın alımı için ikinci bir teslimat siparişi oluşturmadan toparlanmasını sağlar.

Webhook'lar, sorgulama ve sipariş yaşam döngüsü

Müşteriniz önce ürününüze ödeme yapabilir; hizmetiniz ise MyStars talimatını daha sonra yerine getirir. Bu, birbirine karıştırılmaması gereken üç operasyonel durum oluşturur:

1. müşteri sizin ürününüze ödeme yaptı;
2. hizmetiniz MyStars siparişi için zincir üstü ödemeyi gönderdi;
3. MyStars, Stars veya Premium'u Telegram alıcısına teslim etti.

Bir sipariş oluşturulduğunda, ödeme bloğu ve sona erme zamanı ile awaiting_payment olarak dönebilir. Mutabakat ve teslimat ilerledikçe, sisteminizin nihai sonucu alması için güvenilir bir yola ihtiyacı vardır.

Normal teslimat güncellemeleri için webhook geri çağrısı kullanın ve durum sorgulamasını kurtarma yolu olarak saklayın. Gelen webhook isteklerinin arka ucunuz tarafından işlendiğini doğrulayın, bunları MyStars sipariş kimliğiyle ilişkilendirin ve webhook işlemesini de idempotent hâle getirin. Yinelenen bir geri çağrı yinelenen bir ödül vermemeli, ikinci bir makbuz düzenlememeli veya ikinci bir para iadesi iş akışını tetiklememelidir.

Ödeme mutabakatı: GRAM (TON) ve TON üzerindeki USDT

MyStars API siparişleri GRAM (TON) veya USDT (TON) ile mutabakata bağlanabilir. Bunlar, istemci tarafındaki ödeme sayfasına gelişigüzel kopyalanacak alanlar değil, arka uç ödeme işlemleridir.

Her sipariş için API yanıtından dönen para birimini, zinciri, adresi, tutarı, notu ve sona erme zamanını okuyun. Önceki bir siparişin ödeme ayrıntılarını yeniden kullanmayın. Yanlış tutar, yorum, ağ veya süresi geçmiş talimatla yapılan ödeme mutabakatı başarısız olabilir.

Cüzdan imzalama ve API çağrılarını sunucu tarafında tutun. Bir tarayıcı paketi, Telegram Mini App, herkese açık depo veya istemci günlüğünde X-Api-Key, cüzdan seed'i ya da otomatik mutabakat kimlik bilgilerini asla yayımlamayın.

Alıcı KYC'si olmaması: B2B açısından kesin anlamı

“Alıcı KYC'si yok” bir arama terimidir, ancak kesin bir dille kullanılmalıdır. Bu akışta MyStars teslimat ödeme sayfası, alıcının kimlik belgesi yüklemesini gerektirmez. Bu, ürün deneyimindeki sürtünmeyi azaltabilir.

Telegram Stars yeniden satıcı API entegrasyonu için lansman kontrol listesi

Özelliği müşterileriniz için görünür hâle getirmeden önce aşağıdakileri doğrulayın:

• API anahtarı yalnızca sunucu tarafı gizli bilgi yönetiminde saklanır ve döndürülebilir;
• ürün ve para birimi seçimleri sabit kodlu değerler yerine canlı API'den gelir;
• alıcı kontrolü, sipariş oluşturulmadan ve müşteriden nihai ücret alınmadan önce yapılır;
• her siparişin sabit bir dahili kimliği ve idempotency anahtarı vardır;
• ödeme, o sipariş için dönen tam adresi, tutarı, notu, zinciri ve sona erme zamanını kullanır;
• USDT, geçtiği her yerde yalnızca TON olarak etiketlenir;
• webhook işleme olayları doğrular, ilişkilendirir, günlüğe kaydeder ve güvenle tekilleştirir;
• sorgulama, kaçırılan veya geciken bir webhook'u kapsar;
• destek ekibiniz bir siparişi kendi kimliğiniz, MyStars sipariş kimliği, alıcı ve işlem karmasıyla bulabilir;
• para iadesi, dolandırıcılık, uyumluluk ve müşteri iletişimi kuralları lansmandan önce tanımlanır.

İstek biçimleri, yanıt alanları, SDK seçenekleri ve canlı API sözleşmesi için uygulama açısından tek doğruluk kaynağı olarak MyStars API dokümantasyonunu kullanın.

SSS

Kendi web sitem, botum veya Mini App'im üzerinden Telegram Stars satabilir miyim?

Evet. Ürününüz müşterinin seçimini ve alıcı kullanıcı adını toplayabilir; arka ucunuz ise Stars siparişini oluşturmak ve takip etmek için MyStars Fulfilment API'yi kullanır. API anahtarını ve mutabakat işlemlerini sunucu tarafında tutun.

Aynı API üzerinden Telegram Premium satabilir miyim?

Evet. API, ay cinsinden Premium süresiyle ayrı bir ürün türü olarak Telegram Premium teslimatını destekler. Premium hediye kısıtları Stars alıcı kontrollerinden farklı olabileceği için sipariş oluşturulmadan önce alıcı uygunluğunu kontrol edin.

API, Stars ve Premium için sabit bir fiyat listesi sağlıyor mu?

Sabit bir listeye güvenmek yerine canlı fiyat teklifi için fiyatlandırma uç noktasını kullanın. API yanıtı, seçilen sipariş için güncel tutar ve mutabakat para birimi açısından uygun kaynaktır.

Yinelenen Telegram Stars siparişlerini nasıl önlerim?

Her siparişi kendi dahili sipariş kimliğinize bağlı sabit bir Idempotency-Key ile oluşturun. Bir sunucu çalışanı zaman aşımı nedeniyle yeniden denerse, yeni bir anahtar üretmek yerine aynı anahtarı tekrar kullanın.

Hangi USDT ağı desteklenir?

Yalnızca TON / The Open Network üzerindeki USDT. Başka bir ağdaki USDT'yi uyumlu bir mutabakat yöntemi olarak göndermeyin veya sunmayın.

Alıcı KYC'si olmaması, işletmemin uyumluluk yükümlülüğü olmadığı anlamına mı gelir?

Hayır. Bu, şirketinizin yasal, finansal, dolandırıcılık, vergi, yaptırım, tüketiciyi koruma veya para iadesi sorumluluklarını değil, MyStars alıcı ödeme sayfası deneyimini açıklar.

B2B Telegram teslimat entegrasyonunuzu başlatın

Ürününüzün Telegram Stars veya Premium'u ölçekli biçimde satması gerekiyorsa, doğrulanabilir bir sipariş yaşam döngüsü etrafında geliştirin: canlı fiyat teklifi, alıcı kontrolü, idempotent sipariş oluşturma, tam zincir üstü mutabakat ve nihai webhook veya durum mutabakatı.

MyStars API dokümantasyonunu açın ve entegrasyona başlayın →

Kaynaklar ve kanıtlar

• MyStars FaaS — Fulfilment API dokümantasyonu: ürün kataloğu, canlı fiyatlandırma, alıcı kontrolleri, sipariş oluşturma, API kimlik doğrulaması, mutabakat talimatları, durum takibi ve webhook'lar.