> ## Documentation Index
> Fetch the complete documentation index at: https://andcze.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
go get github.com/itemshop/sdk-go
```

## Storefront (bez klucza)

```go theme={null}
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:             "steve@example.com",
	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)

```go theme={null}
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):

```go theme={null}
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](https://andcze.mintlify.site/pl/developers/webhooks.md)), więc SDK nie ma weryfikatora podpisów.

> **[Storefront API](https://andcze.mintlify.site/pl/developers/storefront-api.md)**
>
> Endpointy pod spodem SDK.

> **[Błędy i limity](https://andcze.mintlify.site/pl/developers/errors-and-limits.md)**
>
> Kody błędów i limity zapytań.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.