geliştirici belgeleri

Go SDK

Go şablonunun kullandığı uygulama SDK'sı: kurulum, tipli çağrılar, imza doğrulama ve sahte platformla test.

appsdk, bir uygulamanın platformla konuşmak için ihtiyaç duyduğu her şeyi taşıyan Go paketidir: OAuth kurulumu, imza doğrulama, /api/v1 için tipli bir istemci ve sözleşmelerin tipleri. Yalnızca standart kitaplığa dayanır.

Go şablonu (biticaret app init) SDK'nın bir kopyasını sdk/ klasöründe getirir ve go.mod onu oraya bağlar:

require github.com/biticaret/biticaret v0.0.0-00010101000000-000000000000

replace github.com/biticaret/biticaret => ./sdk
import "github.com/biticaret/biticaret/pkg/appsdk"

sdk/ klasörünü düzenlemeyin; yeni bir şablon yeni bir kopya getirir.

Aşağıdaki örnekler şablonun main.go dosyasındandır veya onun yanında derlenir.

Kurmak

Üç değer uygulamanın her yerinde kullanılır:

s := &server{
	clientID:    clientID,
	adminOrigin: env("ADMIN_ORIGIN", "https://admin.biticaret.com.tr"),
	platform:    appsdk.Platform{StoreDomain: env("STORE_DOMAIN", "mybiticaret.com.tr")},
	verifier:    appsdk.Verifier{Secrets: []string{secret}},
	oauth:       appsdk.OAuth{ClientID: clientID, ClientSecret: secret, Scopes: scopes, RedirectURI: appURL + callbackPath},
	tokens:      map[int64]string{},
}

Kurulum akışı

application_url işleyicisi imzalı sorguyu doğrular ve mağaza sahibini izin ekranına gönderir:

store, storeID, err := s.verifier.VerifyAppURL(r.URL.Query())
if err != nil {
	http.Error(w, "Bu bağlantı platformdan gelmiyor ya da süresi doldu.", http.StatusUnauthorized)
	return
}
storeURL, err := s.platform.StoreURL(store)
if err != nil {
	http.Error(w, "Mağaza adresi geçersiz.", http.StatusBadRequest)
	return
}
http.Redirect(w, r, s.oauth.AuthorizeURL(storeURL, state), http.StatusFound)

Geri dönüş işleyicisi imzayı ve state değerini denetler, sonra kodu jetona çevirir:

q := r.URL.Query()
if err := s.verifier.VerifyQuery(q); err != nil {
	http.Error(w, "Bu bağlantı platformdan gelmiyor ya da süresi doldu.", http.StatusUnauthorized)
	return
}
tok, err := s.oauth.Exchange(r.Context(), storeURL, q.Get("code"))
if err != nil {
	log.Printf("code exchange for %s: %v", store, err)
	http.Error(w, "Yükleme tamamlanamadı; yeniden deneyin.", http.StatusBadGateway)
	return
}
s.mu.Lock()
s.tokens[tok.StoreID] = tok.AccessToken
s.mu.Unlock()

Jetonu tok.StoreID ile saklayın. Her takas önceki jetonu iptal eder: her takastan geleni kaydedin.

Tipli bir çağrı

Client bir mağazanın API'sini o kurulumun jetonuyla çağırır:

func productTitles(ctx context.Context, storeURL, token string) ([]string, error) {
	c := &appsdk.Client{StoreURL: storeURL, Token: token}
	var titles []string
	pageInfo := ""
	for {
		products, next, err := c.ListProducts(ctx, pageInfo, 100)
		if err != nil {
			return nil, err
		}
		for _, p := range products {
			titles = append(titles, p.Title)
		}
		if next == "" {
			return titles, nil
		}
		pageInfo = next
	}
}

storeURL, Platform.StoreURL çıktısıdır. HTTPClient boşsa istemci 15 saniyelik zaman aşımı kullanır; yönlendirmeleri hiç izlemez.

İstemci 429 yanıtında Retry-After kadar bekler (en çok MaxRateLimitWait, 10 saniye) ve yeniden dener (en çok 3 kez; sonra 429 bir *appsdk.APIError olur). Platformun diğer retleri *appsdk.APIError olarak döner:

func shopName(ctx context.Context, c *appsdk.Client) (string, error) {
	shop, err := c.GetShop(ctx)
	if appsdk.IsAPIErrorCode(err, http.StatusUnauthorized, "invalid_token") {
		// Jeton iptal edilmiş: uygulama kaldırılmış ya da yeni bir takas yapılmış.
		return "", err
	}
	if err != nil {
		return "", err
	}
	return shop.Name, nil
}

appsdk.Retryable(err), aynı çağrının sonra başarılı olup olamayacağını söyler: 400, 409 ve 422 kesindir, diğerleri yeniden denenebilir.

Client şu kaynakların yöntemlerini taşır (adresler ve izinler: Uygulama API'si):

Kaynak Yöntemler
Mağaza GetShop
Ürünler ListProducts, GetProduct, CreateProduct, UpdateProduct, ListProductVariants, ProductVariants (250'den fazla varyantı olan bir ürünün bütün varyantları), SetVariantCost, SetVariantShipping
Koleksiyonlar ListCollections, GetCollection
Stok ListLocations, ListInventoryLevels, ListInventoryHistory, AdjustInventoryLevel, MoveInventoryLevel
Siparişler ListOrders, GetOrder, CreateRefund, CreateFulfillment, CancelFulfillment, CreateFulfillmentEvent, CaptureOrder, CaptureOrderAsStaff
Müşteriler GetCustomer, SetCustomerTags, ListMarketingAudience, SetMarketingConsent
Müşteri segmentleri ListCustomerSegments, GetCustomerSegment, ListSegmentCustomers
İndirimler CreateDiscountCode, GetDiscountCode, DeleteDiscountCode
Hediye kartları ListGiftCards, GetGiftCard, CreateGiftCard (kartın kodu yalnızca bu yanıtta gelir), UpdateGiftCard, DisableGiftCard
Taslak siparişler ve kanallar ListDraftOrders, GetDraftOrder, CreateDraftOrder, UpdateDraftOrder, DeleteDraftOrder, CompleteDraftOrder, SendDraftInvoice, CreateChannelOrder
Şirketler ListCompanies, GetCompany, CreateCompany, UpdateCompany, DeleteCompany, CreateCompanyLocation, UpdateCompanyLocation, DeleteCompanyLocation, CreateCompanyContact, UpdateCompanyContact, DeleteCompanyContact
Meta alanlar SetMetafield, DeleteMetafield
Meta nesneler ListMetaobjectDefinitions, GetMetaobjectDefinition, CreateMetaobjectDefinition, UpdateMetaobjectDefinition, DeleteMetaobjectDefinition, ListMetaobjects, GetMetaobject, CreateMetaobject, UpdateMetaobject, DeleteMetaobject
Çeviriler GetTranslations, SetTranslations
SMS SendSMS, ReportSMSStatus
Web pikselleri GetPixelSettings, SetPixelSettings
Faturalandırma ListPlans, CreateAppSubscription, GetAppSubscription, ListAppSubscriptions, ActiveAppSubscription, ActivePlan, CancelAppSubscription, CreateUsageRecord, CreateAppCredit, ListAppCredits
Webhook teslimleri ListWebhookDeliveries, ReplayWebhookDelivery
Ödeme uygulamaları ConfigurePaymentsApp, ResolvePayment, RejectPayment, PendPayment, ResolveFollowUp, RejectFollowUp

pageInfo alan listeler (ListProducts, ListCollections, ListGiftCards, ListMetaobjects gibi) bir sayfa ve sonraki sayfanın page_info imlecini döner; son sayfada imleç boştur.

Webhook doğrulamak

VerifyWebhookTopic, tek konuya hizmet eden bir adres içindir: imzayı denetler ve imzalı konu beklenen konu değilse isteği reddeder. Şablonun bütün webhook'ları şu sarmalayıcıdan geçer:

func (s *server) webhook(topic string, h func(storeID int64, body []byte) error) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		wh, err := appsdk.VerifyWebhookTopic(r, topic, s.verifier.Secrets...)
		if err != nil {
			appsdk.WriteError(w, http.StatusUnauthorized, "invalid_signature", "the signature or topic doesn't match")
			return
		}
		var head struct {
			StoreID int64 `json:"store_id"`
		}
		if json.Unmarshal(wh.Body, &head) != nil || !appsdk.ValidID(head.StoreID) {
			appsdk.WriteError(w, http.StatusBadRequest, "invalid_json", "want a JSON body with store_id")
			return
		}
		if err := h(head.StoreID, wh.Body); err != nil {
			log.Printf("webhook %s for store %d: %v", topic, head.StoreID, err)
			appsdk.WriteError(w, http.StatusInternalServerError, "internal_error", "the app couldn't handle the webhook")
			return
		}
		w.WriteHeader(http.StatusOK)
	}
}
mux.HandleFunc("POST /webhooks/app-uninstalled", s.webhook(appsdk.TopicAppUninstalled, s.forget))
mux.HandleFunc("POST /privacy/customers-data-request", s.webhook(appsdk.TopicCustomersDataRequest, nothingKept))

Dönen Webhook değeri doğrulanmış Body, Topic, EventID, StoreDomain ve TriggeredAt alanlarını taşır; bu başlıkları kendiniz okumayın. Konu adları sabittir (appsdk.TopicOrdersPaid ve diğerleri).

Oturum jetonunu doğrulamak

Yönetim panelindeki sayfanız sunucunuzu App Bridge'in oturum jetonuyla çağırır:

tok, err := s.verifier.VerifySessionToken(appsdk.BearerToken(r), s.clientID)
if err == nil && tok.Issuer != s.adminOrigin {
	err = appsdk.ErrBadSessionToken
}
var store string
if err == nil {
	store, err = s.platform.StoreFromDest(tok.Dest)
}
if err != nil {
	appsdk.WriteError(w, http.StatusUnauthorized, "invalid_session_token", "Oturum doğrulanamadı.")
	return
}

tok.StoreID mağazanın kimliğidir; kaydınızı onunla bulun.

Sayfanın kendisi için SDK şunları verir: appsdk.EmbeddedPage (sayfanın hazır kabuğu, içerik güvenliği kuralıyla; Routes sayfayı ve yüklediği dosyaları bağlar), appsdk.ServeAppBridge ve appsdk.ServeAppPage (istemci kitaplığını ve sayfa parçalarını sunar), appsdk.AppBridgeVersion ve appsdk.AppPageVersion (bağlantıların ?v= değerleri), appsdk.NewStaticFiles (static/ klasörünü sürümlü adreslerle sunar), appsdk.DesignSystemHead, appsdk.DesignSystemCSP ve appsdk.AppLoading (Biticaret Design System'in bt-* öğeleri, onların içerik güvenliği kuralı ve yükleniyor durumu). Sayfanın nasıl kurulduğu: Yönetim panelinde uygulama sayfası.

Uygulama vekilini doğrulamak

func (s *server) proxy(w http.ResponseWriter, r *http.Request) {
	req, err := s.verifier.VerifyProxy(r.URL.Query())
	if err != nil {
		appsdk.WriteError(w, http.StatusUnauthorized, "invalid_signature", "the proxy signature doesn't match")
		return
	}
	// req.StoreID mağaza, req.CustomerID giriş yapmış müşteridir (ziyaretçi için 0).
	fmt.Fprintf(w, "store %d, customer %d", req.StoreID, req.CustomerID)
}

Sahte platformla test

appsdktest, bir uygulamanın testleri için sahte bir platformdur: bir mağaza için OAuth adreslerini ve /api/v1 kaynaklarını sunar, gönderdiklerini platform gibi imzalar ve uygulamanın yaptığı çağrıları kaydeder.

Paket platformun deposundadır (github.com/biticaret/biticaret/pkg/appsdk/appsdktest); şablonun sdk/ kopyası bugün onu içermez, yani bu örnek platformun deposundaki uygulamalarda derlenir.

func TestProductTitles(t *testing.T) {
	p := appsdktest.New(t)
	p.Scope = appsdk.ScopeReadProducts
	p.AddProduct(appsdk.Product{ID: 101, Title: "Rehber"})

	c := &appsdk.Client{StoreURL: p.StoreURL(), Token: p.CurrentToken(), HTTPClient: &http.Client{Transport: p.Transport()}}
	products, _, err := c.ListProducts(context.Background(), "", 25)
	if err != nil {
		t.Fatal(err)
	}
	if len(products) != 1 || products[0].Title != "Rehber" {
		t.Fatalf("products = %+v", products)
	}
}

Uygulamanın kendisini test etmek için:

Yönetim paneli sayfasının betiği için: