Ayarlar, Vault ve Metafield'lar

Tecof, uygulamanızın kurulum başına veri saklamasını sağlayan üç katman sunar. Bu katmanlarla birçok uygulama kendi veritabanına ihtiyaç duymadan, örneğin Vercel üzerinde durumsuz (stateless) çalışabilir.

Ayarlar ve sırlar kapsam istemez; kurulumun kendisi yetkidir.

Ayarlar#

Kurulum başına tek bir JSON nesnesi.

const api = tecof.client(installationId);

const { settings } = await api.settings.get();
await api.settings.set({ invoiceMode: "issued", seriesPrefix: "ABC" }, { merge: true });

merge: true gönderilen anahtarları mevcut nesneyle birleştirir; merge olmadan nesne tamamen değiştirilir. Panelin yerel ayar formu da aynı ayar nesnesine yazar (birleştirerek; formda olmayan anahtarlar korunur). API'den yapılan yazmalar app.settings.updated olayı üretmez.

Vault (Sırlar)#

Üçüncü taraf API anahtarları ve parolalar için. Değerler Tecof'ta şifreli tutulur ve yalnız uygulamanızın kurulum token'ıyla okunabilir.

await api.secrets.set("isbasiPassword", passwordFromForm);
const { value: password } = await api.secrets.get("isbasiPassword"); // okuma lastReadAt'i damgalar
const list = await api.secrets.list();                     // yalnız anahtar adları ve meta
await api.secrets.delete("isbasiPassword");

Kurallar

Şifreleme tasarımı#

Vault, sızıntı durumunda bile şifreli metnin başka bir yerde kullanılamamasını hedefler:

Garantiler

• Değerler panel API'sine, istek günlüklerine, webhook yüklerine ve hata mesajlarına hiçbir zaman çıkmaz. Panel yalnız "ayarlı / ayarlı değil" bilgisini ve güncelleme zamanını görür.
• Okuma lastReadAt alanını damgalar; liste ucuyla hangi sırrın ne zaman okunduğunu izleyebilirsiniz.
• Uygulama kaldırıldığında kurulumun sırları anında silinir.

Kendi tarafınızda: sırrı yalnız ihtiyaç anında okuyun, günlüğe yazmayın, istemci (tarayıcı) koduna göndermeyin.

Yerel Ayar Formu#

tecof.app.json içine settings şeması eklerseniz panel, uygulama sayfasında bir "Ayarlar" sekmesi gösterir. Böylece ayar ekranı için arayüz yazmanız gerekmez; arka plan (headless) uygulamalar için de idealdir.

{
  "settings": [
    { "key": "username", "label": { "tr": "Kullanıcı adı", "en": "Username" }, "type": "text", "required": true },
    { "key": "password", "label": { "tr": "Parola", "en": "Password" }, "type": "secret", "required": true },
    { "key": "autoInvoice", "label": { "tr": "Ödenen siparişleri otomatik faturala", "en": "Auto-invoice paid orders" }, "type": "boolean" },
    { "key": "invoiceMode", "label": { "tr": "Fatura tipi", "en": "Invoice mode" }, "type": "select",
      "help": { "tr": "Kesilmiş fatura doğrudan alıcıya gider", "en": "Issued invoices are sent to the buyer" },
      "options": [
        { "value": "draft", "label": { "tr": "Taslak", "en": "Draft" } },
        { "value": "issued", "label": { "tr": "Kesilmiş", "en": "Issued" } }
      ] },
    { "key": "note", "label": { "tr": "Fatura notu", "en": "Invoice note" }, "type": "textarea" }
  ]
}

En fazla 30 alan tanımlanabilir.

Panel tarafı#

• secret alan için boş string = değiştirme; null = sil.
• Kayıttan sonra uygulamanıza app.settings.updated webhook'u gelir: data = { keys: [...], secretKeys: [...] }. Değer taşımaz. Olay yalnız bu panel kaydında üretilir.
• Uygulamanın kendi yazdığı anahtarlar (ör. billing) form kaydında silinmez; yalnız formdaki anahtarla aynı adı taşıyorsa üzerine yazılır.

Uygulama tarafı#

Formdaki sır olmayan değerler ayarlarda, secret değerler Vault'ta aynı key ile durur:

const api = tecof.client(installationId);
const { settings } = await api.settings.get();
const username = settings.username as string;
const { value: password } = await api.secrets.get("password");

app.settings.updated geldiğinde önbelleğinizdeki değerleri geçersiz kılın ya da bağlantıyı test edin (ör. üçüncü taraf API'ye giriş deneyip sonucu metafield veya ayarlarla bildirin).

Metafield'lar#

Metafield, bir kaynağa (sipariş, ürün, müşteri, mağaza) bağlı uygulama verisidir. Örneğin fatura uygulaması siparişe fatura numarasını, kargo uygulaması takip bağlantısını yazar. Metafield'lar panelde gösterilebilir ve başka uygulamalarla paylaşılabilir.

Alanlar#

Kapsam#

Okuma ve yazma, kaynağın okuma kapsamını ister:

Panelde gösterim#

panel.show: true olan metafield'lar ilgili detay sayfasındaki "Uygulamalar" kartında label ile listelenir; url tipi tıklanabilir bağlantı olarak gösterilir. Panel bu kartı GET /api/merchant/apps/metafields?ownerType=order&ownerId=… ile doldurur.

await api.metafields.set({
  ownerType: "order",
  ownerId: orderId,
  key: "invoiceNumber",
  type: "string",
  value: "ABC2026000000123",
  visibility: "shared",
  panel: { label: { tr: "İşbaşı fatura no", en: "İşbaşı invoice no" }, show: true },
});

await api.metafields.set({
  ownerType: "order",
  ownerId: orderId,
  key: "invoiceUrl",
  type: "url",
  value: "https://ornek-fatura-portali.example/fatura/ABC2026000000123",
  visibility: "private",
  panel: { label: { tr: "Faturayı görüntüle", en: "View invoice" }, show: true },
});

const mine = await api.metafields.list({ ownerType: "order", ownerId: orderId, namespace: "isbasi" });

Kaldırmada#

Uygulama kaldırıldığında panelde görünen metafield'lar gizlenir; veri 30 gün sonra temizlik işinde silinir.

Paylaşılan metafield'ların uygulamalar arası kullanımı için bkz. Uygulamalar Arası İletişim.