Uygulamalar
Go SDK
Go uygulamanızda kurulum akışını, oturum belirteçlerini, uygulama proxy'sini, webhook imzalarını ve içerik API'sini appsdk ile kullanın; kurulumları kendi veritabanınızda saklayın ve appsdktest ile test edin.
go.biticaret.com.tr/appsdk, bir uygulamanın platformla olan sözleşmelerinin kendi tarafını Go ile yazmanızı sağlar: platformun gönderdiği her şeyin imzasını doğrular, OAuth ile kurulumu yapar, mağazanın uygulama API'sini çağırır ve kurulumları saklar. Yalnızca standart kütüphaneye dayanır. Sözleşmelerin kendisi Uygulama API'si, webhook'lar ve uygulama proxy'si ve yönetim paneli sayfası sayfalarında anlatılır; bu sayfa onları Go'da nasıl kullanacağınızı gösterir.
Kurulum
Modül yayımlanma aşamasındadır; yayımlanana kadar başlamanın yolu CLI'nin Go şablonudur: biticaret app init my-app çalışan bir uygulama üretir (CLI). Aşağıdaki örnekler o şablondaki kodla aynı API'yi kullanır.
Kurulumları PostgreSQL'de saklamak için ayrı bir modül vardır: go.biticaret.com.tr/appsdk/store/postgres.
OAuth kurulum akışı
Akışın adımları Uygulama API'si sayfasındadır. SDK'da her adımın bir karşılığı vardır:
verifier := appsdk.Verifier{Secrets: []string{clientSecret}}
platform := appsdk.Platform{StoreDomain: "mybiticaret.com.tr"}
oauth := appsdk.OAuth{ClientID: clientID, ClientSecret: clientSecret, Scopes: scopes, RedirectURI: appURL + "/oauth/callback"}
// application_url: yönetim panelindeki Yükle ve Aç düğmelerinin açtığı imzalı bağlantı.
store, storeID, err := verifier.VerifyAppURL(r.URL.Query())
storeURL, err := platform.StoreURL(store)
state := rand.Text() // crypto/rand
http.SetCookie(w, &http.Cookie{Name: "oauth_state", Value: state, Path: "/oauth/callback", MaxAge: 600, HttpOnly: true, Secure: true, SameSite: http.SameSiteLaxMode})
http.Redirect(w, r, oauth.AuthorizeURL(storeURL, state), http.StatusFound)
// Geri çağrı, ayrı bir istek: imzalı sorguyu doğrulayın, state'i çerezle
// karşılaştırın, mağazayı imzalı sorgudan alın, kodu belirteçle değiştirin.
q := r.URL.Query()
err = verifier.VerifyQuery(q)
c, err := r.Cookie("oauth_state")
if err != nil || subtle.ConstantTimeCompare([]byte(c.Value), []byte(q.Get("state"))) != 1 {
// 400: kurulumu yeniden başlatın
}
storeURL, err := platform.StoreURL(q.Get("store"))
tok, err := oauth.Exchange(r.Context(), storeURL, q.Get("code"))
_, err = installs.Install(r.Context(), tok, q.Get("store"))state değerini tarayıcıya bağlı (yukarıdaki gibi çerezde) üretmek ve geri çağrıda karşılaştırmak uygulamanın işidir: yoksa başka birinin kurulumu satıcının oturumuna düşebilir. Geri çağrı mağazayı önceki istekten değil, kendi imzalı store değerinden alır. Akışın tamamı appsdktest/content_app_test.go içinde çalışır. Platform, uygulamanın gizli anahtarını ve belirteçleri yalnızca gerçek bir mağaza adresine göndermesini sağlar: StoreURL başka bir adresi reddeder.
Kurulumlar ve InstallationStore
Uygulama, kurulu olduğu her mağaza için bir Installation kaydı tutar: mağaza kimliği, mağaza adresi, kapsamlar, zaman damgaları ve mühürlenmiş erişim belirteci. Kayıtlar uygulamanın kendi depolamasındadır; SDK yalnızca InstallationStore arayüzünü ve üstüne kuralları koyan Installations türünü verir.
- Depolar. Testler ve veritabanı olmayan uygulamalar için
appsdk.NewMemoryStore()(kayıtlar süreçle birlikte gider). PostgreSQL içinpostgres.New(pool); tabloyu oluşturanpostgres.Schema'yı uygulamanızın ilk göçü olarak çalıştırın,store_id'ye başvuran kendi tablolarınızdan önce. Dilerseniz arayüzü kendi deponuz için uygulayın; her depoappsdktest.Storagesenaryolarını geçmelidir. - Mühürlü belirteç. Erişim belirteci depoya girmeden önce AES-256-GCM ile mühürlenir ve mağaza kimliğine bağlanır; depo onu yalnızca anlamsız baytlar olarak görür. Anahtarlar
ENCRYPTION_KEYSortam değişkeninden gelir; her girdiid:<64 onaltılık karakter>biçimindedir veappsdk.ParseEncryptionKeyile okunur. İlk anahtar yeni belirteçleri mühürler, hepsi açar; iki kez yazılan anahtar kimliği reddedilir. Anahtar döndürürken yenisini başa koyun, ardından bir kezResealAll(ctx)(ya da mağaza başınaReseal(ctx, storeID)) çalıştırın: her belirteci kaydın geri kalanına dokunmadan yeni anahtarla yeniden mühürler. Eski anahtarı yalnızca bu iş hatasız bittikten sonra kaldırın. - Mağaza kimlikle bulunur.
Active(ctx, storeID)kurulu mağazayı döndürür; kayıt yoksaErrNoInstallation, kaldırılmışsaErrUninstalledverir. Platformun gönderdiği her şey (oturum belirteci, proxy isteği, webhook) mağaza kimliğini taşır; kaydı adresle değil, bu kimlikle bulun. - Kaldırma ve silme. app/uninstalled webhook'unda
Uninstall(ctx, storeID, wh.TriggeredAt)çağrılır: kayıt kalır, yeniden kurulumdaInstalledAtkorunur. Yalnızca olay zamanından sonra kaydedilmemiş kurulum kaldırılmış sayılır; böylece eski bir app/uninstalled geç yeniden denendiğinde o arada yeniden kurulan mağaza etkilenmez. Dönenboolmağazanın artık kaldırılmış olup olmadığını söyler;falseise kendi kaldırma işlerinizi atlayın. store/redact webhook'undaDeletekaydı ve ona ON DELETE CASCADE ile başvuran satırlarınızı siler.UninstalledWebhookveStoreRedactWebhookikisi için de bağlanmaya hazır yollardır (bkz. Webhook'lar).
var keys []appsdk.EncryptionKey
for _, s := range strings.Split(os.Getenv("ENCRYPTION_KEYS"), ",") {
k, err := appsdk.ParseEncryptionKey(s)
if err != nil {
log.Fatal(err)
}
keys = append(keys, k)
}
installs, err := appsdk.NewInstallations(postgres.New(pool), keys...)
rec, err := installs.Active(ctx, storeID)
token, err := installs.Token(rec) // API çağrıları için açılmış belirteç
client := &appsdk.Client{StoreURL: storeURL, Token: token}Bir kaydı okuyup sonra yazdığınız yerde işlemi kendi işleminizde yapın ve satırı önce kilitleyin:
err := pgx.BeginFunc(ctx, pool, func(tx pgx.Tx) error {
st := postgres.New(tx)
if _, err := st.Lock(ctx, storeID); err != nil && !errors.Is(err, appsdk.ErrNoInstallation) {
return err
}
_, err := installs.With(st).Install(ctx, tok, store)
return err
})Lock satırı işlem bitene kadar kilitler (FOR NO KEY UPDATE): aynı mağazaya aynı anda gelen iki kurulum ya da kaldırma birbirini ezmez, yabancı anahtar denetimleri ise engellenmez. Her kod değişimi öncekini hemen iptal ettiği için, API çağrısı yapan kod belirteci her seferinde kayıtlı olandan okumalıdır.
Oturum belirteçleri
Yönetim panelindeki sayfanız App Bridge ile bir oturum belirteci gönderir (uygulama proxy'si ve yönetim paneli sayfası). Sunucuda belirteci yönetim panelinden gelmiş bir belirteç olarak doğrulayın, sonra mağazayı belirteçteki store_id ile bulun:
// adminOrigin yapılandırmanızdan gelir, örneğin "https://admin.biticaret.com.tr".
tok, err := verifier.VerifyAdminSessionToken(appsdk.BearerToken(r), clientID, adminOrigin)
rec, err := installs.ForSession(r.Context(), tok)Ödeme sayfası arayüz uzantıları da aynı gizli anahtar ve aynı aud ile imzalı belirteç alır; ama onlarda iss mağazadır, sub ise alıcı. VerifyAdminSessionToken bunları reddeder: iss değerinin adminOrigin olmasını, sub içinde bir personel kimliğini ve store_id ister. ForSession yalnızca onun döndürdüğü AdminSessionToken türünü alır; başka yolla denetlenmiş bir belirteç derlenmez. Ödeme sayfası uzantısının sunucusu VerifyCheckoutSessionToken(token, clientID) (iss, dest ile aynı olmalı; sub müşteridir, misafirde boş) ve ForCheckoutSession kullanır; yönetim paneli belirteci orada reddedilir. İkisi de ErrBadSessionToken ya da ErrExpiredSessionToken döndürür: 401 ile yanıtlayın.
ForSession mağaza kimliği olmayan belirteç için ErrBadSessionToken döndürür (401 ile yanıtlayın); kurulu olmayan mağaza için ErrNoInstallation ya da ErrUninstalled döndürür (403). appsdk.EmbeddedPage yönetim paneli sayfasının kabuğunu sunar: tasarım sistemi, App Bridge ve uygulamanızın static klasörü, yalnızca yönetim panelinin çerçeveleyebileceği bir politikayla.
Uygulama proxy'si
Vitrinden gelen /apps/<altyol> istekleri uygulamanıza imzalı bir sorguyla ulaşır:
pr, err := verifier.VerifyProxy(r.URL.Query())
rec, err := installs.ForProxy(r.Context(), pr)ProxyRequest mağaza adresini, StoreID'yi ve oturum açmış müşterinin kimliğini (ziyaretçi için 0) taşır. ForProxy mağazayı imzalı store_id ile bulur; kurulu olmayan mağaza için ErrNoInstallation ya da ErrUninstalled döner (404 ile yanıtlayın). İmza hataları ErrNoSignature, ErrBadSignature ve ErrStaleSignature'dır (401); imzalı sorguda geçerli bir store_id yoksa ErrBadProxyQuery döner.
Webhook'lar
Konular, başlıklar ve yeniden denemeler webhook'lar sayfasındadır. VerifyWebhook, X-Biticaret-Signature taşımayan teslimatı reddeder (ErrWebhookSignature). Tek bir konuya ayrılmış uç nokta VerifyWebhookTopic ile imzayı ve konuyu birlikte doğrular; başka bir konu için alınmış imza bu adreste kabul edilmez. İmza appsdk.SignatureTolerance (5 dakika) içinde olmalıdır; gizli anahtar döndürürken Secrets birden çok anahtar alır.
mux.Handle("POST /webhooks/app-uninstalled", installs.UninstalledWebhook(secrets...))
mux.Handle("POST /privacy/store-redact", installs.StoreRedactWebhook(secrets...))
mux.Handle("POST /webhooks/orders-paid", appsdk.WebhookHandler{
Topic: appsdk.TopicOrdersPaid,
Secrets: secrets,
Handle: func(ctx context.Context, storeID int64, wh appsdk.Webhook) error {
return orders.Record(ctx, storeID, wh.Body)
},
})WebhookHandler imzayı ve konuyu VerifyWebhookTopic ile doğrular, gövdedeki store_id'yi okur ve Handle'ı çalıştırır. Doğrulanmayan imza ya da konuya 401, store_id'siz gövdeye 400, Handle nil ya da ErrNoInstallation döndürürse 200, başka her hatada 500 yanıtını verir; OnError 200 dışındaki her yanıtı günlüğünüz için duyar. Elle doğrulamak isterseniz VerifyWebhookTopic'i kendiniz çağırın. Webhook yapısı gövdeyi, konuyu, olay kimliğini ve mağaza adresini verir. Aynı olay birden fazla gelebilir; işleyiciniz tekrar çalışmaya dayanıklı olmalıdır, 200 dışındaki her yanıt yeniden denemeye yol açar. Her uygulamanın yanıtlaması gereken kişisel veri konuları için sabitler hazırdır (TopicCustomersDataRequest, TopicCustomersRedact, TopicStoreRedact).
İçerik API'si istemcisi
Client, bir mağazanın uygulama API'sini kurulumun belirteciyle çağırır. Sayfalı listeler bir pageInfo imleci alır ve sonraki imleci döndürür; appsdk.Retryable(err) hatanın sonradan yeniden denenebilir olup olmadığını söyler.
c := &appsdk.Client{StoreURL: storeURL, Token: token}
products, next, err := c.ListProducts(ctx, "", 100)
p, err := c.GetProduct(ctx, productID)
variants, err := c.ProductVariants(ctx, p)
_, err = c.SetMetafield(ctx, appsdk.Metafield{
OwnerType: appsdk.OwnerProduct, OwnerID: p.ID,
Namespace: appsdk.AppNamespace("my-app", "seo"), Key: "title",
Type: "single_line_text", Value: json.RawMessage(`"Merhaba"`),
})Ürünler, varyantlar, koleksiyonlar, stok, indirimler, meta alanlar, ödeme uygulaması uç noktaları ve diğerleri için yöntemler vardır; her çağrının gerektirdiği izinler Uygulama API'si sayfasındadır.
appsdktest ile test
go.biticaret.com.tr/appsdk/appsdktest, bir mağazanın sahte platformunu sunar: OAuth uç noktalarını ve uygulama API'sini yanıtlar, uygulamanıza platformun yaptığı gibi imzalı istekler gönderir ve uygulamanın yaptığı her çağrıyı kaydeder.
p := appsdktest.New(t)
p.RedirectURI = app.URL + "/oauth/callback"
// Uygulamayı p.ClientID, p.ClientSecret, p.AppSDK() ve p.Transport() ile yapılandırın.
res, err := http.Get(p.AppURLLink(app.URL + "/app")) // kurulumu başlatır
res, err = p.SendWebhook(app.URL, appsdk.TopicOrdersPaid, map[string]any{"id": 1})
p.Uninstall() // mağaza uygulamayı kaldırırp.CallbackURL(state) imzalı bir OAuth geri çağrısı, p.SessionToken(staffID) bir oturum belirteci üretir. SDK'daki appsdktest/content_app_test.go, bu yolla sınanan eksiksiz bir içerik uygulamasıdır: kurulum, oturum belirteciyle bir yönetim sayfası çağrısı, app/uninstalled ve store/redact. Hazır denetimler de vardır: appsdktest.Storage{Store: s}.Run(t) her InstallationStore için; appsdktest.SessionStore oturum belirteciyle çalışan, appsdktest.ProxyStore uygulama proxy'si olan uygulamalar için. İkisi de uygulamanın mağazayı adresten değil kimlikten bulduğunu ve kaldırılmış mağazayı reddettiğini sınar.