Telegram Bot ve Mini App'ler için Fragment API SDK Rehberi

MyStars FaaS, Telegram Stars ve Premium ürünleri satan bot ve Mini App geliştiricilerine 'Fragment as a Service' modeliyle bir fulfilment katmanı sunuyor. Fikir basit: Telegram tarafındaki kullanıcı deneyimi ve sipariş veritabanı geliştiricide kalırken, fiyatlama, alıcı doğrulama, sipariş oluşturma ve durum bildirimleri resmi Node.js (@mystars-tg/faas-sdk) ve Python (mystars-faas) SDK'ları üzerinden yönetiliyor. Rehber, API anahtarının istemci tarafına asla konmaması gerektiğini vurgulayarak üç katmanlı bir mimari öneriyor: Telegram arayüzü, kendi backend'iniz ve MyStars FaaS katmanı.

Kod örnekleri hem TypeScript hem async Python için sipariş oluşturma akışını gösteriyor: önce güncel fiyat sorgulanıyor, ardından alıcı kullanıcı adının ürünü alabilir olup olmadığı kontrol ediliyor, uygun değilse sipariş açılmadan durduruluyor. Sipariş oluşturulurken kendi sisteminizden gelen sabit bir idempotency anahtarı kullanmak, ağ zaman aşımlarında yinelenen sipariş oluşmasını engelliyor. Ödeme para birimi enum'ları (ton, usdt_ton) ile kullanıcı arayüzünde gösterilecek isimler (Gram, TON ağındaki USDT) arasındaki fark da ayrıca belirtiliyor.

Üretime almadan önce webhook doğrulaması zorunlu tutuluyor: ham istek gövdesi alınmalı, X-Faas-Signature başlığı gizli anahtarla doğrulanmalı, sipariş kimliği ve durumuna göre tekrarlar elenmeli ve yerel sipariş yalnızca geçerli durum geçişlerinde güncellenmeli. Her iki SDK da webhook doğrulama yardımcıları sunuyor; buna ek olarak yedek bir polling/reconcile işi önerilerek webhook'ların kaçırdığı uç durumlar telafi ediliyor. Referans olarak paylaşılan Python blueprint bot, Postgres, Redis ve TON Center izleme ile birlikte tüm bu parçaların gerçek bir üründe nasıl bir araya geldiğini gösteriyor; ayrıca önerilen backend endpoint listesi (quote, recipient-check, orders, webhook, reconcile) küçük ölçekli bir entegrasyonun iskeletini oluşturuyor.