SDK Go

github.com/itemshop/sdk-go — storefront i klient API dla Go 1.23+, bez zależności.

github.com/itemshop/sdk-go — bez zależności (tylko net/http), Go ≥ 1.23 (iteratory iter.Seq2). Każda metoda przyjmuje context.Context i zwraca (wynik, error).

Pakiet	Do czego	Sekrety
storefront — storefront.New(shopIDOrDomain)	Storefront API v1: sklep, produkty, płatności, rabaty, kasa, status zamówienia, widżety	brak
itemshop — itemshop.NewClient(apiKey)	pełne API z kluczem + Sites API (client.Site)	klucz API (X-API-Key)

​

Instalacja

go get github.com/itemshop/sdk-go

​

Storefront (bez klucza)

sf := storefront.New("664f1a2b3c4d5e6f7a8b9c0d", storefront.WithLocale("pl"))
// or the shop's uniqueName / domain: storefront.New("sklep.example.com")

list, err := sf.Products.List(ctx, &storefront.ProductsListParams{Category: serverID})
// list.Products, list.Categories (category = the shop's server)
methods, err := sf.PaymentMethods.List(ctx)

res, err := sf.Checkout.Create(ctx, storefront.CheckoutInput{
	Items:             []storefront.CartItem{storefront.Item(list.Products[0].ID, 1)},
	Nick:              "Steve",               // game shops; general shops use Email
	Email:             "[e-mail]",
	AcceptTerms:       true,
	ImmediateDelivery: true,
	PaymentMethodCode: methods[0].Code,
	PaymentChannel:    "blik",                // methods[i].Channel
	ReturnURL:         "https://sklep.example.com/dziekujemy",
})
// redirect the buyer to res.RedirectURL; after the gateway:
returned, ok := storefront.ReturnedOrderFromReturnURL(returnedURL) // ?itemshop_order=<numer>&itemshop_key=<klucz>
if ok {
	status, err := sf.Orders.WaitPaidByNumber(ctx, returned.Number, returned.Key, 0)
	// albo sf.Orders.StatusByNumber(ctx, res.OrderNumber, res.StatusKey) zaraz po kasie
}

redemption, err := sf.Vouchers.Redeem(ctx, "KOD123", "Steve", turnstileToken)

• Checkout.Create sam uzupełnia consents.legalVersion z Shop.Legal.Version i zawsze wysyła Idempotency-Key (wygenerowany albo input.IdempotencyKey), więc ponowienie po zerwanym połączeniu nie utworzy drugiego zamówienia. Token Turnstile jest opcjonalny.
• Koszyk ma 1–20 pozycji (Items); dwie lub więcej tworzą jedną grupę płatności (GroupID, OrderIDs w wyniku), więcej niż 20 → CART_TOO_LARGE. Stare OrderIDFromReturnURL / Orders.Status obsługują wyłącznie zamówienia sprzed 3.0.
• Vouchers.Redeem nie jest ponawiany (poza 429).
• Widżety: sf.Widgets.RecentPurchases, TopSpenders, MonthlyGoal, OnlinePlayers — wyłączone przez właściciela zwracają puste wyniki, nie błąd.
• Pola nullable w typach odpowiedzi to wskaźniki.

​

Klient API (z kluczem)

client := itemshop.NewClient(os.Getenv("ITEMSHOP_API_KEY")) // empty key → $ITEMSHOP_API_KEY

product, err := client.Products.Create(ctx, shopID, api.CreateProductDto{
	Name: "VIP", Price: 19.99, ServerID: serverID,
	Commands: []string{"lp user {PLAYER} parent set vip"},
	IsActive: itemshop.Bool(true),
})

// pagination: an iterator over all pages, fetched lazily
for order, err := range client.Orders.All(ctx, shopID, &itemshop.OrdersListParams{Status: "paid"}) {
	if err != nil {
		return err
	}
	fmt.Println(*order.OrderNumber)
}

// site as code — the equivalent of `itemshop deploy`
dep, err := client.Site.Deploy(ctx, shopID, zipFile, itemshop.DeploymentProduction)

// AI Workspace
setup, err := client.Workspace.AgentSetup(ctx, shopID, "claude-code") // ready MCP config file

Serwisy: Shops, Servers, Products, PaymentMethods, PaymentErrors, Blacklist, Discounts, Vouchers, Stats, Uploads, Orders oraz ręczne Site, Templates, Workspace, Agents, Skills. Tokeny Workspace wymagają sesji panelu — kluczem API dostaniesz 401/403. Endpoint bez metody: client.Do(ctx, "GET", "/api/v2/…", nil, &out). Pola opcjonalne w typach api.* to wskaźniki — pomocniki itemshop.String/Bool/Float/Int/Ptr.

​

Błędy

Każdy błąd to *itemshop.Error (w pakiecie storefront ten sam typ):

var e *itemshop.Error
if errors.As(err, &e) {
	switch e.Code { // backend code (e.g. "LEGAL_CONSENT_REQUIRED") or an SDK code
	case itemshop.CodeRateLimited:
		time.Sleep(e.RetryAfter)
	case itemshop.CodeUnauthorized:
		// wrong / revoked key
	}
}
if errors.Is(err, itemshop.ErrNotFound) { /* matches by code or HTTP status */ }

Kody SDK: BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, VALIDATION_FAILED, RATE_LIMITED, SERVER_ERROR, NETWORK_ERROR, TIMEOUT, ABORTED… — te same co w SDK TypeScript.

​

Ponowienia, limity czasu, idempotencja

• Domyślnie 2 ponowienia (WithMaxRetries), backoff 300 ms·2ⁿ (maks. 5 s) z jitterem; Retry-After zastępuje opóźnienie.
• GET/HEAD i żądania z Idempotency-Key (Orders.Create, Checkout.Create, itemshop.WithIdempotencyKey) są ponawiane po błędach sieci, timeoutach i 408/425/429/500/502/503/504.
• Pozostałe zapisy — tylko po 429.
• WithTimeout ogranicza jedną próbę (domyślnie 30 s); context — całe wywołanie z ponowieniami.
• Opcje: WithBaseURL (lub $ITEMSHOP_API_BASE), WithHTTPClient, WithUserAgent, WithLocale, WithHeader.

​

Webhooki

Backend nie wysyła podpisanych webhooków do właścicieli sklepów (powiadomienia idą na Discord — zob. Webhooki), więc SDK nie ma weryfikatora podpisów.

Storefront API

Endpointy pod spodem SDK.

Błędy i limity

Kody błędów i limity zapytań.