Uygulama Geliştirme

Tecof partner uygulamaları, mağazaların panelden tek tıkla kurduğu üçüncü taraf uygulamalardır. Bir uygulama, mağaza onay verdiği kapsamlarla (scope) Tecof verisini okur ve yazar, webhook ile olayları dinler, panel ekranlarına kendi işlemlerini (aksiyon) ekler, panel içinde iframe arayüzüyle çalışır ve isterse ücretli plan satar. Uygulamanın geliri, partner programının aylık hak ediş akışıyla geliştiriciye ödenir.

Model, ikas App Development'a yakındır: Admin App + Actions + App Bridge + CLI + plan satışı + aylık hak ediş.

Uygulama Türleri#

Her iki türde de uygulama kendi sunucusunda çalışır: ya Tecof'un yönettiği barındırmada (hosting: "tecof", tecof app deploy) ya da sizin altyapınızda (hosting: "external").

Yetenekler#

Mimari#

flowchart LR
    subgraph Panel["Tecof Paneli - app.tecof.com"]
        UI["Uygulama sayfası / aksiyon penceresi"]
    end
    subgraph App["Uygulamanız - appUrl"]
        FE["iframe arayüzü + @tecof/app-bridge"]
        BE["Sunucu rotaları + @tecof/app-sdk"]
    end
    API[("Tecof API - api.tecof.com")]

    UI -- "launch URL + oturum JWT'si (60 sn)" --> FE
    FE -- "postMessage (App Bridge)" --> UI
    FE -- "Authorization: Bearer oturum token'ı" --> BE
    BE -- "client_credentials -> tcfi_ (1 saat)" --> API
    BE -- "/api/v1/* (Bearer tcfi_)" --> API
    API -- "Webhook + API aksiyonu (X-Tecof-Signature)" --> BE

Üç güven sınırı vardır:

1. Panel → iframe: Panel uygulamaya yalnız 60 saniyelik, istemci sırrınızla imzalı bir oturum JWT'si verir. Panel oturumu (JWT) ve mağazanın secretKey'i platform uygulamalarına asla verilmez.
2. Uygulama → Tecof API: Sunucunuz istemci kimliği + sırrıyla kurulum token'ı alır. Token yalnız kurulu olduğu mağazanın verisine, mağazanın onayladığı kapsamlarla erişir; mağaza kimliği token'dan çözülür.
3. Tecof → uygulama: Webhook ve API aksiyonu istekleri X-Tecof-Signature ile imzalanır; 5 dakikalık tekrar saldırısı penceresi vardır.

Kimlik Bilgileri Özeti#

Ayrıntılar: Kimlik Doğrulama ve Kapsamlar.

Geliştirme Yaşam Döngüsü#

flowchart LR
    A["Partner hesabı"] --> B["tecof login"]
    B --> C["tecof app init"]
    C --> D["Test mağazasında geliştirme<br/>tecof app dev"]
    D --> E["tecof app push + promote<br/>ya da tecof app deploy"]
    E --> F["İncelemeye gönderim<br/>draft -> in-review"]
    F --> G["approved: yayın<br/>public / private"]
    G --> H["Kurulumlar + plan satışları"]
    H --> I["Aylık hak ediş<br/>partner ödeme akışı"]

1. Partner hesabı. Uygulamalar bir partner hesabına aittir. Partner başvurusunda program olarak uygulama geliştirme (programs: ["apps"]) seçilir; ajans programı kapalı olsa bile uygulama geliştirici programı (varsayılan açık) yeterlidir. Geliştirici olmak için partner kaydınız ve partner üyeliğiniz active olmalıdır.
2. CLI girişi. tecof login cihaz akışıyla tarayıcıda onay ister ve kişisel hesabınıza bağlı bir CLI token'ı alır (30 gün; 14 gün kullanılmazsa düşer). Uygulama komutları her istekte aktif partner üyeliğinizi doğrular.
3. Proje. tecof app init şablondan proje açar; uygulama yapılandırması tecof.app.json dosyasındadır.
4. Test mağazasında geliştirme. Onaysız uygulama yalnız testStores listesindeki (ekip üyesi olduğunuz) mağazalara kurulur. tecof app dev yerel sunucunuzu başlatıp tünelle açar; test mağazası kurulumlarında iframe, webhook'lar ve API aksiyonları bu adrese gider.
5. Dağıtım. tecof app push yalnız değişen dosyaları Tecof barındırmasına (GitHub org reposu + Vercel projesi) yükleyip staged bir sürüm açar; tecof app promote vN onu yeniden derlemeden canlıya alır, tecof app rollback önceki canlı sürüme döner. tecof app deploy tüm kaynağı yükleyip doğrudan yayınlamaya devam eder. İlk yayında <slug>.apps.… alt alan adı bağlanır. Kendi sunucunuzda barındırıyorsanız hosting: "external" + appUrl kullanırsınız.
6. İnceleme. draft → in-review → approved ya da rejected. Gönderim için ikon, açıklamalar, destek e-postası, gizlilik politikası, https adres ve en az bir yüzey gerekir; ücretli plan içeren uygulama, partner doğrulaması (KYC/IBAN) onaylı değilse incelemeye gönderilemez.
7. Yayın. approved + public uygulama katalogda görünür. private dağıtım katalogda görünmez, yalnız doğrudan kurulum bağlantısıyla kurulur.
8. Kazanç. Plan satışlarının KDV hariç tutarının varsayılan %80'i, 14 günlük iade penceresi sonunda partner defterinize yazılır ve aylık partner ödeme akışıyla ödenir.

Eski (legacy) entegrasyon modeli#

Tecof’un ilk birinci parti uygulamaları integration: "legacy" sözleşmesiyle yazılmıştı: iframe’e sorgu dizesiyle secretKey ve panel token’ı verilir, ayarlar /api/store/option üzerinden okunur, webhook X-App-Secret / X-Webhook-Secret ile doğrulanırdı. Bu model yeni uygulamalara açık değildir ve bu dokümantasyonda anlatılmaz. Tecof’un kendi uygulamaları (fatura, kargo, pazaryeri, SMS…) bu bölümde anlatılan platform sözleşmesine (integration: "platform", @tecof/app-sdk, @tecof/app-ui) taşınmaktadır; örnek için Logo İşbaşı ve Fatura uygulamaları.

Bu Bölümün Sayfaları#

Değişiklik Notları#