# Uygulama Geliştirme

> Partner uygulamalarına genel bakış: uygulama türleri, yetenekler, mimari, kimlik bilgileri ve geliştirmeden yayına yaşam döngüsü.
>
> Kaynak: https://tecof-app-dev.vercel.app/app-development · Bölüm: Uygulama geliştirme · Son güncelleme: 2018-10-20

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ş.

> **Durum (11.10.2026):** Platform backend'i uygulandı. `@tecof/cli`, `@tecof/app-sdk`, `@tecof/app-bridge` ve `@tecof/invoice-kit` npm'de yayımlandı (0.1.0). Artımlı push ve sürüm komutları (`tecof app push|versions|promote|rollback`) `@tecof/cli` 0.2.0 ile gelir; [Geliştirici Alanları (Spaces)](/spaces) sayfasına bakın. Bu bölümdeki uç adları ve alanlar platform sözleşmesini izler; "gelecek" ya da "v2" diye işaretlenen özellikler henüz yoktur.

---

## Uygulama Türleri

| Tür | `embedded` | Ne yapar | Örnek |
| :--- | :--- | :--- | :--- |
| Panel içi (embedded) uygulama | `true` | Panelde iframe arayüzü açar, kendi menü başlıklarını (`navigation`) ekler, App Bridge ile panelle konuşur | Fatura listesi ekranı olan bir muhasebe uygulaması |
| Arka plan (headless) uygulama | `false` | Arayüzü yoktur; webhook alır, API çağırır. Ayarlarını panelin yerel ayar formundan (`settings`) alabilir, `api` tipi aksiyon sunabilir | Stok senkronu, sipariş aktarımı |

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

| Yetenek | Ne sağlar | Sayfa |
| :--- | :--- | :--- |
| API erişimi | Kurulum token'ı (`tcfi_…`) ile `/api/v1` üzerinden sipariş, müşteri, ürün, envanter okuma; Tools API ile yazma | [Uygulama API’si](/app-api) |
| Webhook'lar | Sipariş, ürün, müşteri, içerik olayları ve uygulama yaşam döngüsü olayları; zaman damgalı HMAC imzası | [Webhook'lar](/app-webhooks) |
| Aksiyonlar | Sipariş, ürün ve müşteri ekranlarına (detay + toplu işlem) iframe ya da API işlemi ekleme | [Aksiyonlar](/app-actions) |
| App Bridge | iframe ile panel arasında güvenli mesajlaşma: oturum token'ı, bildirim, onay penceresi, yönlendirme | [App Bridge](/app-bridge) |
| CLI ve barındırma | `tecof` CLI ile giriş, proje oluşturma, tünelle geliştirme, GitHub + Vercel'e dağıtım; `tecof app push` ile artımlı push, numaralı sürümler, yeniden derlemeden canlıya alma ve anında geri alma | [Hızlı Başlangıç](/app-quickstart), [Sürümler ve Geri Alma](/versions-and-rollback) |
| Vault | API anahtarı, parola gibi sırları kurulum başına şifreli saklama; uygulamanın kendi veritabanına ihtiyacı kalmaz | [Ayarlar, Vault ve Metafield'lar](/app-data) |
| Ayarlar ve yerel ayar formu | Kurulum başına JSON ayarlar; panelin "Ayarlar" sekmesinde otomatik form | [Ayarlar, Vault ve Metafield'lar](/app-data) |
| Metafield'lar | Sipariş, ürün, müşteri ya da mağazaya bağlı uygulama verisi; panelde gösterim | [Ayarlar, Vault ve Metafield'lar](/app-data) |
| Uygulamalar arası olaylar | Bildirilmiş olayları yayınlama ve başka uygulamaların olaylarına abone olma | [Uygulamalar Arası İletişim](/app-interop) |
| Ücretli planlar | Aylık/yıllık plan, deneme süresi, iyzico ile tahsilat, %80 geliştirici payı | [Ücretlendirme ve Hak Ediş](/app-billing) |

---

## Mimari

```mermaid
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

| Kimlik | Biçim | Ömür | Nerede kullanılır |
| :--- | :--- | :--- | :--- |
| İstemci kimliği | `tcfa_…` | Kalıcı, herkese açık | Token isteği, oturum JWT'sinin `aud` alanı, kurulum bağlantısı |
| İstemci sırrı | `tcfs_…` | Döndürülene kadar; yalnız oluşturma/döndürmede **bir kez** gösterilir | Token isteği, imza doğrulama, oturum JWT'si doğrulama (yalnız sunucuda) |
| Kurulum token'ı | `tcfi_…` | 1 saat | `/api/v1/*` çağrıları (`Authorization: Bearer`) |
| Oturum token'ı | JWT (HS256) | 60 saniye | iframe arayüzünden kendi sunucunuza giden istekler |
| Geliştirici (CLI) token'ı | `tcfd_…` | Cihaz oturumu 30 gün (14 gün kullanılmazsa düşer); kapsamlı CI token'ı 1–365 gün | `tecof` CLI, geliştirici API'si (`/api/developer`) ve alanlar (Spaces). Bkz. [Güvenlik ve CI](/dev-security) |

Ayrıntılar: [Kimlik Doğrulama ve Kapsamlar](/app-auth).

---

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

```mermaid
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şı](/app-example-isbasi) ve [Fatura uygulamaları](/app-invoicing).

---

## Bu Bölümün Sayfaları

| Sayfa | İçerik |
| :--- | :--- |
| [Hızlı Başlangıç: Tecof CLI](/app-quickstart) | Kurulum, giriş, proje yapısı, tünelle geliştirme, dağıtım, `tecof.app.json` referansı |
| [Tasarım Kimliği](/app-ui) | `@tecof/app-ui` kurulumu, kabuk ve bileşenler, durum sözlüğü, ekran düzenleri, metin tonu |
| [Formlar ve Şema](/app-forms) | İstemci ve sunucuda tek şema, `AppForm`, `SecretField`, `validateOnServer` |
| [Sürümler, Canlıya Alma ve Geri Alma](/versions-and-rollback) | `tecof app push` sürümleri, staged ve production, canlıya alma ve geri alma kuralları, portaldaki **Sürümler** sekmesi |
| [Güvenlik ve CI](/dev-security) | CLI kimlik bilgileri, kapsamlı CI token'ları, GitHub Actions örneği, ajan modu |
| [Kimlik Doğrulama ve Kapsamlar](/app-auth) | Kapsam listesi, kurulum token'ı, oturum token'ı, imzalar, sır döndürme |
| [Uygulama API’si](/app-api) | `/api/v1` zarfı, sayfalama, hız sınırları, kaynak şekilleri, Tools API, uygulamaya özel uçlar |
| [Webhook'lar](/app-webhooks) | Abonelik, olay kataloğu, teslimat biçimi, yeniden deneme, idempotency |
| [Aksiyonlar](/app-actions) | Yerleşimler, iframe ve API aksiyonları, yerelde test |
| [App Bridge](/app-bridge) | Mesaj protokolü, bağlam nesnesi, React sağlayıcısı |
| [Ayarlar, Vault ve Metafield'lar](/app-data) | Ayarlar, şifreli sırlar, yerel ayar formu, metafield'lar |
| [Uygulamalar Arası İletişim](/app-interop) | Uygulama olayları, paylaşılan metafield'lar, keşif kataloğu |
| [Ücretlendirme ve Hak Ediş](/app-billing) | Planlar, KDV, abonelik durumları, gelir paylaşımı, ödeme |
| [Yayınlama ve İnceleme](/app-publishing) | İnceleme durumları, dağıtım, kontrol listesi, askıya alma |
| [Örnek Uygulama: Logo İşbaşı](/app-example-isbasi) | Uçtan uca örnek: otomatik fatura, Vault, metafield, aksiyon, olay yayını |

---

## Değişiklik Notları

| Tarih | Değişiklik |
| :--- | :--- |
| 11.10.2026 | Spaces: `tecof app push`, `versions`, `promote`, `rollback` ile artımlı push, numaralı sürümler, yeniden derlemeden canlıya alma ve anında geri alma; `tecof app deploy` çalışmaya devam ediyor |
| 11.10.2026 | CLI oturumu kişisel hesaba bağlandı: onay adresi `/cli`, cihaz token'ı 30 gün (14 gün kullanılmazsa düşer), token işletim sistemi anahtarlığında; partner üyeliği yalnız uygulama uçlarında aranır. Kapsamlı CI token'ları eklendi |
| 10.10.2026 | Platform backend'i uygulandı; bu bölümdeki sözleşme ayrıntıları (yaşam döngüsü olay verileri, yeniden deneme sayısı, `devUrl` davranışı, inceleme kapısı, abonelik geçişleri) kesinleşti |
| 10.10.2026 | Düzeltme: kaldırılan bir uygulama aynı mağazaya yeniden kurulamıyordu; artık yeniden kurulum eski kaydı canlandırır |
| 10.10.2026 | Düzeltme: webhook yeniden denemeleri ve elle yeniden gönderim 8 KB'ta kırpılmış (bozuk) JSON gönderiyordu; artık tam gövde (≤ 256 KB) gönderilir |