Telegram Uygulamaları ve Botları için Fragment API SDK Rehberi

Telegram ticareti fikirlerinin çoğu prototipten sonra aynı duvara çarpar: botu veya Mini App’i yapmak kolaydır, ancak Stars ve Premium teslimatı için hâlâ güvenilir bir backend akışı gerekir. Geliştiricilerin Fragment API aramasının nedeni budur.

MyStars FaaS bu eksik katmanı sunar. FaaS, Fragment as a Service anlamına gelir: Telegram ürününüz kullanıcı deneyimini ve sipariş veritabanını korurken MyStars, teslimat akışını API, resmî SDK’lar ve imzalı durum güncellemeleri üzerinden sunar.

Bu rehberi, yalnızca başka bir API genel bakışı okumak yerine gerçek bir Telegram uygulaması, bot, pazar yeri, içerik üretici aracı veya bayi akışı bağlamak istediğinizde kullanın.

Temiz mimari: Önde Telegram API, arkada Fragment API

Sınırı basit tutun.

Telegram API katmanınız, kullanıcıların görebildiği bölümleri yönetir: bot komutları, satır içi klavyeler, Mini App ekranları, sipariş kartları, mesajlar ve destek yanıtları.

Sunucu katmanınız, iş mantığınızdan sorumludur: yerel siparişler, marj, dolandırıcılık kuralları, yönetici kontrolleri, veritabanı yazımları ve destek kanıtları.

MyStars FaaS katmanı, Fragment as a Service akışını yönetir: fiyatlandırma, alıcı kontrolleri, sipariş oluşturma, ödeme talimatları ve teslimat durumu.

Bu ayrım güvenlik açısından önemlidir. MyStars API anahtarını Telegram Mini App frontend’ine koymayın. İstemci backend’inizle, backend’iniz de MyStars ile konuşmalıdır.

Kullandığınız altyapı için SDK’yı yükleyin

Node.js ve TypeScript backend’leri için resmî @mystars-tg/faas-sdk paketini kullanın:

npm install @mystars-tg/faas-sdk

Python backend’leri için resmî mystars-faas paketini kullanın:

pip install mystars-faas

Her iki paket de resmî MyStars FaaS SDK’sı olarak yayımlanır ve geliştiricileri etkileşimli API dokümantasyonu sayfasına yönlendirir. Güncel paket dokümantasyonu, SDK örneklerini API referansıyla karşılaştırırken yararlı olan FaaS API v1.9.0 uyumluluğunu açıklar.

TypeScript ile ilk backend rotasını oluşturun

İlk rota her şeyi yapmaya çalışmamalıdır. Fiyat teklifi alan, alıcıyı kontrol eden ve kendi yerel sipariş kimliğinizden tek bir teslimat siparişi oluşturan yalnızca sunucu taraflı bir eylemle başlayın.

Koddan önce, yaptığı işin sade dille özeti şöyledir:

• MYSTARS_API_KEY kullanarak backend’de bir MyStars istemcisi oluşturur;
• seçilen Stars miktarının güncel fiyatını MyStars’tan ister;
• Telegram kullanıcı adının ürünü alıp alamayacağını kontrol eder;
• hatalı bir sipariş oluşturmaktansa alıcı uygun değilse erken durur;
• idempotency için kendi kararlı localOrderId değerinizi temel alarak teslimat siparişi oluşturur;
• uygulamanızın ödeme talimatını saklayıp göstermesi için fiyat teklifini ve MyStars sipariş nesnesini döndürür.

import { MyStarsClient } from "@mystars-tg/faas-sdk";

const client = MyStarsClient.production(process.env.MYSTARS_API_KEY!);

export async function createStarsOrder(input: {
  username: string;
  quantity: number;
  localOrderId: string;
}) {
  const quote = await client.getPricing({
    type: "stars",
    quantity: input.quantity,
    payment_currency: "ton",
  });

  const recipient = await client.checkRecipient({
    type: "stars",
    recipient: { username: input.username },
  });

  if (!recipient.eligible) {
    return { ok: false, message: recipient.telegram_message };
  }

  const order = await client.createOrder(
    {
      type: "stars",
      recipient: { username: input.username },
      quantity: input.quantity,
      payment_currency: "ton",
      callback_url: "https://your-app.example.com/webhooks/mystars",
    },
    { idempotencyKey: `local-${input.localOrderId}` },
  );

  return { ok: true, quote, order };
}

Önemli bölüm idempotency anahtarıdır. Kendi sisteminizden gelen kararlı bir değer kullanın. Sipariş sunucu tarafında oluşturulduktan sonra HTTP isteği zaman aşımına uğrarsa, yinelenen bir sipariş oluşturmaktansa aynı anahtarla tekrar deneyin.

Bazı satırlar özellikle dikkat gerektirir:

• MyStarsClient.production(...), isteğin canlı MyStars API’sine gittiği anlamına gelir; gerçek trafiğe hazır olana kadar kendi sisteminizde test/yerel bir sipariş kullanın.
• getPricing(...), backend’inize güncel bir teklif verir. Bot arayüzünde fiyatları sabit kodlamayın.
• payment_currency: "ton", bu SDK örneğinde yerel ödeme yolu için API enum/adıdır. Ürün arayüzünüzde bu yolu Gram veya Gram (ex. TON) olarak etiketleyin. TON adını blokzincir/ağ için kullanın.
• checkRecipient(...), alıcıyı yerine getirilemeyecek bir kullanıcı adı veya ürün için ödeme yapmaktan korur.
• callback_url, MyStars’ın oluşturma sonrasında sipariş durumu güncellemelerini gönderebileceği adrestir.
• idempotencyKey, yinelenen sipariş korumasıdır. Tarayıcıda rastgele üretilen bir değerden değil, veritabanı siparişinizden gelmelidir.

Aynı akışı async Python ile oluşturun

Python ekipleri genellikle async kod ister; çünkü Telegram bot çatısı zaten async’tir. Python SDK bunu doğrudan destekler.

Bu örnek, TypeScript rotasıyla aynı işi Python’da yapar:

• istek süresince async bir MyStars istemcisi açar;
• usdt_ton ile Premium teklifi ister;
• sipariş oluşturmadan önce alıcıyı kontrol eder;
• alıcı Premium alamıyorsa güvenli bir hata mesajı döndürür;
• durum güncellemeleri için callback URL içeren siparişi oluşturur;
• botunuzun bunları saklayıp kullanıcıya sonraki adımı göstermesi için teklifi ve siparişi döndürür.

from mystars_faas import AsyncMyStarsClient

async def create_premium_order(username: str, months: int, local_order_id: str):
    async with AsyncMyStarsClient.production(MYSTARS_API_KEY) as client:
        quote = await client.get_pricing(
            type="premium",
            months=months,
            payment_currency="usdt_ton",
        )

        recipient = await client.check_recipient(username, type="premium")
        if not recipient.eligible:
            return {"ok": False, "message": recipient.telegram_message}

        order = await client.create_order(
            type="premium",
            recipient=username,
            months=months,
            payment_currency="usdt_ton",
            callback_url="https://your-app.example.com/webhooks/mystars",
            idempotency_key=f"local-{local_order_id}",
        )

        return {"ok": True, "quote": quote, "order": order}

Bunu üretime taşırken kesin para birimi işlemleri kullanın, API anahtarını ortam değişkeninde saklayın ve ödeme talimatını döndüğü şekliyle aynen saklayın. Talimat memo/comment içeriyorsa bunu yeniden yazabileceğiniz metin değil, veri olarak değerlendirin.

Daha az deneyimli bir geliştirici için temel fikir şudur: Kod örneği tam bir bot değildir. Kullanıcı bir ürünü seçtikten sonra botunuzun çağırdığı backend bölümüdür. Telegram botu, bu fonksiyonun etrafında kendi handler’larına, düğmelerine, veritabanı yazımlarına ve kullanıcı mesajlarına yine ihtiyaç duyar.

Yayına almadan önce webhook doğrulaması ekleyin

Fragment API tarzı bir entegrasyon, sipariş oluşturma çalıştığında tamamlanmış sayılmaz. Uygulamanızın güvenilir bir durum yoluna da ihtiyacı vardır.

Minimum webhook işleyicisi:

1. Ham istek gövdesini alın.
2. X-Faas-Signature başlığını okuyun.
3. İmzayı webhook gizli anahtarınızla doğrulayın.
4. MyStars sipariş kimliği ve durumuna göre yinelenenleri ayıklayın.
5. Yerel siparişinizi yalnızca geçiş geçerliyse güncelleyin.
6. Telegram botunuz veya Mini App üzerinden kullanıcıyı bilgilendirin.

TypeScript SDK, constructEvent, Express middleware ve Fastify desteği gibi webhook yardımcılarını belgeler. Python SDK, WebhookVerifier ile yaygın Python web çatısı entegrasyonlarını içerir.

Yedek olarak bir polling veya reconcile işi tutun. Webhooklar hızlı yoldur; gece 3’te bir ağ uç durumu ortaya çıktığında sizi kurtaran şey mutabakattır.

Blueprint botu çalışan bir referans olarak kullanın

MyStars Python blueprint botu, tüm hareketli parçaları birlikte görmek istediğinizde en iyi kaynaktır. Teslimat için mystars-faas==0.1.3, sağlık kontrolleri ve MyStars webhookları için aiohttp sunucusu, durum için Postgres ve Redis, zincir üstü ödemeler için TON Center izleme ve marj ile mutabakat için yönetici komutlarını kullanır.

Blueprint’i marka şablonu olarak görmeyin. Onu bir mühendislik haritası olarak kullanın:

• yerel siparişin nerede oluşturulacağı;
• alıcı kontrollerinin nerede çağrılacağı;
• marjın nerede uygulanacağı;
• ödemenin nerede izleneceği;
• teslimatın nerede çağrılacağı;
• sonlandırıcı bir durumdan sonra Telegram sipariş kartının nerede düzenleneceği.

MyStars GitHub hesabı SDK depolarını da yayımlar; böylece README’den daha derin bir hata ayıklama gerektiğinde kaynak kodu, örnekleri ve paket yapısını inceleyebilirsiniz.

Kendi uygulamanızda oluşturacağınız backend endpointleri

Küçük ama üretim düzeyinde bir entegrasyon genellikle şu rotalarla başlar:

POST /api/faas/quote
POST /api/faas/recipient-check
POST /api/orders
POST /webhooks/mystars
GET  /api/orders/:id
POST /api/admin/reconcile

Telegram botu veya Mini App, MyStars’ı doğrudan değil kendi /api/orders rotanızı çağırmalıdır. Rotanız daha sonra kullanıcıyı doğrulayabilir, yerel sipariş oluşturabilir, SDK’yı çağırabilir, dönen teslimat siparişini saklayabilir ve istemcinin ihtiyaç duyduğu yalnızca güvenli alanları geri gönderebilir.

Kullanıcıların tahmin etmemesi gereken ödeme ayrıntıları

Ürününüzde ödeme ekranı gösteriyorsanız, kesin olun. MyStars akışlarında USDT, TON üzerindeki USDT anlamına gelir. Diğer USDT ağları birbirinin yerine kullanılamaz. Yerel yol için güncel API örnekleri hâlâ payment_currency: "ton" kullanabilir; alıcıya gösterilen metinde token için Gram / GRAM (ex. TON), ağ için ise TON kullanın.

Ödeme zaman aşımını sabit kodlamak yerine siparişin expires_at alanını okuyun. Dokümanlar ödeme penceresinin 1 saate uzatıldığını belirtir ve expires_at doğruluk kaynağı olmaya devam eder.

Gerçek trafikten önce ne test edilmeli?

Kullanıcıları akışa almadan önce şu kontrolleri yapın:

• bir Stars siparişi ve bir Premium siparişi;
• uygun olmayan bir alıcı yolu;
• aynı idempotency anahtarıyla sipariş oluşturmayı yeniden deneme;
• geçerli ve geçersiz webhook imzaları;
• yinelenen webhook etkinliği teslimi;
• süresi geçmiş sipariş işleme;
• destek kanıtları: kullanıcı adı, yerel sipariş kimliği, MyStars sipariş kimliği, ödeme hash’i, memo/comment ve durum;
• marj, reconcile, iade, yayın ve manuel teslimat komutları için yalnızca yönetici erişimi.

Bu bölüm gösterişli değildir, ancak bir Telegram Stars botunu deneysel değil güvenilir hissettiren şey budur.

FAQ

Bu doğrudan herkese açık bir Fragment API mi?

MyStars FaaS, bir Fragment as a Service katmanıdır. Uygulamanız MyStars API’leri ve SDK’larıyla entegre olurken MyStars bu arayüzün arkasındaki teslimat akışını yönetir.

Bunu Telegram Mini App içinden kullanabilir miyim?

Evet. API anahtarını backend’inizde tutun. Mini App sunucunuzu, sunucunuz da MyStars FaaS’ı çağırmalıdır.

Hangi paketle başlamalıyım?

Node.js ve TypeScript için @mystars-tg/faas-sdk kullanın. Python ve async Telegram botları için mystars-faas kullanın.

Blueprint botuna ihtiyacım var mı?

Hayır; ancak ödemeler, yönetici komutları, mutabakat ve durum güncellemeleri içeren bayi tarzı bir bot oluşturuyorsanız yararlıdır.

En güvenli ilk kilometre taşı nedir?

Uçtan uca bir test oluşturun: teklif → alıcı kontrolü → yerel sipariş → MyStars siparişi → doğrulanmış webhook veya polling güncellemesi. Bu çalıştıktan sonra marj, iade politikası, yönetici araçları ve destek akışlarını ekleyin.

API referansı, SDK bağlantıları ve güncel sözleşme notları için MyStars dokümantasyonu ile başlayın.