> ## 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. # Utwórz zamówienie i pobierz przekierowanie do płatności > Zakłada zamówienie i sesję płatności; przekieruj kupującego na `redirectUrl`. Kilka pozycji (do 20) = grupa płatności: jedno zamówienie na pozycję (`orderIds`), jedna transakcja u operatora na sumę, `orderId` = `groupId` (wraca w `itemshop_order`). Limity kwot metody liczą się od sumy. Ponowienie z tym samym `Idempotency-Key` i tym samym ciałem zwraca to samo zamówienie/grupę. ## OpenAPI ````yaml /openapi.pl.json post /api/v2/storefront/v1/shops/{shopId}/checkout openapi: 3.0.0 info: title: ItemShop v2 API description: >- REST API platformy ItemShop v2 (NestJS + Fastify). Wszystkie ścieżki mają prefiks /api/v2. version: 2.0.0 contact: {} servers: - url: https://itemshop.dev description: Produkcja (API pod /api/v2, ten sam origin co panel) - url: http://localhost:3000 description: Lokalnie security: [] tags: [] paths: /api/v2/storefront/v1/shops/{shopId}/checkout: post: tags: - Storefront v1 summary: Utwórz zamówienie i pobierz przekierowanie do płatności description: >- Zakłada zamówienie i sesję płatności; przekieruj kupującego na `redirectUrl`. Kilka pozycji (do 20) = grupa płatności: jedno zamówienie na pozycję (`orderIds`), jedna transakcja u operatora na sumę, `orderId` = `groupId` (wraca w `itemshop_order`). Limity kwot metody liczą się od sumy. Ponowienie z tym samym `Idempotency-Key` i tym samym ciałem zwraca to samo zamówienie/grupę. operationId: createCheckout parameters: - name: shopId required: true in: path description: >- ID sklepu (ObjectId). Przyjmuje też `uniqueName`, aktywną własną domenę albo `.`. schema: type: string example: 664f1a2b3c4d5e6f7a8b9c0d - name: cf-turnstile-response in: header description: >- Token Cloudflare Turnstile. Opcjonalny; wymagany dopiero po serii prób z jednego IP (`CAPTCHA_REQUIRED`). required: false schema: type: string - name: Idempotency-Key in: header description: >- Losowy klucz próby (32–128 znaków `[A-Za-z0-9_-]`, np. UUID). Ten sam tylko przy identycznym ponowieniu. required: true schema: type: string example: 3b0f6f1e-9c2a-4d1b-8a52-1f0e2c7d9a44 requestBody: content: application/json: schema: $ref: '#/components/schemas/StorefrontCheckoutDto' responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/StorefrontCheckoutResponseDto' '400': description: >- `VALIDATION_FAILED`, `IDEMPOTENCY_KEY_REQUIRED`, `LEGAL_CONSENT_REQUIRED`, `DISCOUNT_INVALID`, `SHOP_PAYMENT_NOT_READY`, `PAYMENT_INIT_FAILED`, `RETURN_URL_NOT_ALLOWED`, `EMAIL_REQUIRED` (produkt z treścią cyfrową / digital product), `INVALID_QUANTITY` (>100 kluczy / keys)… content: application/json: schema: $ref: '#/components/schemas/StorefrontErrorDto' '403': description: Pochodzenie (Origin) spoza domen sklepu (`ORIGIN_NOT_ALLOWED`) content: application/json: schema: $ref: '#/components/schemas/StorefrontErrorDto' '404': description: >- Sklep/zasób nie istnieje albo sklep jest zablokowany (`SHOP_NOT_FOUND`, `PRODUCT_NOT_FOUND`, `ORDER_NOT_FOUND`) content: application/json: schema: $ref: '#/components/schemas/StorefrontErrorDto' '409': description: >- `LEGAL_DOCUMENTS_CHANGED`, `IDEMPOTENCY_KEY_REUSED`, `CHECKOUT_IN_PROGRESS`, `CHECKOUT_ATTEMPT_CLOSED`, `OUT_OF_STOCK` content: application/json: schema: $ref: '#/components/schemas/StorefrontErrorDto' '429': description: Przekroczony limit żądań (`RATE_LIMITED`) content: application/json: schema: $ref: '#/components/schemas/StorefrontErrorDto' components: schemas: StorefrontCheckoutDto: type: object properties: items: minItems: 1 maxItems: 20 description: >- Pozycje koszyka (1–20). Kilka pozycji = grupa płatności: jedno zamówienie na pozycję i jedna płatność na sumę (adr/0002) type: array items: $ref: '#/components/schemas/StorefrontCartItemDto' nick: type: string pattern: ^[a-zA-Z0-9_]{3,16}$ description: >- Nick gracza. Wymagany, gdy `shop.kind = game` (albo produkt dostarcza komendy z `{PLAYER}`) — inaczej `NICK_REQUIRED` example: Steve email: type: string format: email minLength: 3 maxLength: 254 description: >- E-mail kupującego. Wymagany bez nicku (sklep `general`) — wtedy identyfikuje kupującego; inaczej `EMAIL_REQUIRED` example: gracz@example.com discountCode: type: string minLength: 1 maxLength: 50 pattern: ^[A-Za-z0-9_-]+$ example: LATO10 consents: $ref: '#/components/schemas/StorefrontConsentsDto' paymentMethodCode: type: string minLength: 1 maxLength: 100 pattern: ^[^:]+$ description: Wymagany dla płatnych zamówień (z `payment-methods`) example: imoje paymentChannel: type: string minLength: 1 maxLength: 60 description: Kanał metody (z `payment-methods[].channel`) example: blik returnUrl: type: string format: uri minLength: 1 maxLength: 2048 description: >- Dokąd bramka odeśle kupującego. Musi być na domenie sklepu (lub podglądzie / localhost). Platforma ustawia parametr zapytania `itemshop_order=` i usuwa fragment (`#…`); czytaj go z `location.search`. Bez returnUrl — domyślna strona statusu sklepu na platformie. example: https://moj-sklep.pl/dziekujemy required: - items - consents StorefrontCheckoutResponseDto: type: object properties: success: type: boolean example: true data: $ref: '#/components/schemas/StorefrontCheckoutResultDto' required: - success - data StorefrontErrorDto: type: object properties: success: type: boolean example: false statusCode: type: number example: 404 code: enum: - VALIDATION_FAILED - BAD_REQUEST - NOT_FOUND - SHOP_NOT_FOUND - PRODUCT_NOT_FOUND - ORDER_NOT_FOUND - PRODUCT_UNAVAILABLE - PRODUCT_VARIANT_REQUIRED - INVALID_PRODUCT_VARIANT - INVALID_QUANTITY - OUT_OF_STOCK - CART_EMPTY - NICK_REQUIRED - EMAIL_REQUIRED - CART_TOO_LARGE - DISCOUNT_INVALID - LEGAL_CONSENT_REQUIRED - LEGAL_DOCUMENTS_CHANGED - SHOP_PAYMENT_NOT_READY - PAYMENT_INIT_FAILED - ORDER_BLOCKED - RETURN_URL_NOT_ALLOWED - VOUCHER_NOT_FOUND - VOUCHER_USED - VOUCHER_EXPIRED - IDEMPOTENCY_KEY_REQUIRED - IDEMPOTENCY_KEY_REUSED - CHECKOUT_ATTEMPT_CLOSED - CHECKOUT_IN_PROGRESS - CAPTCHA_REQUIRED - ORIGIN_NOT_ALLOWED - FORBIDDEN - UNAUTHORIZED - PAYLOAD_TOO_LARGE - CONFLICT - RATE_LIMITED - SERVICE_UNAVAILABLE - INTERNAL_ERROR type: string description: Maszynowy kod błędu — tłumacz po nim komunikat w UI example: SHOP_NOT_FOUND message: type: string description: >- Komunikat dla dewelopera (język nieustalony, nie pokazuj go kupującemu) example: Shop not found error: type: string description: To samo co `message` (zgodność z resztą API) example: Shop not found deprecated: true details: type: object description: Szczegóły walidacji timestamp: type: string format: date-time example: '2026-10-27T12:00:00.000Z' path: type: string example: /api/v2/storefront/v1/shops/moj-sklep required: - success - statusCode - code - message - error - timestamp - path StorefrontCartItemDto: type: object properties: productId: type: string example: 664f1a2b3c4d5e6f7a8b9c0d quantity: type: number minimum: 1 maximum: 100000 example: 1 default: 1 variantId: type: string description: >- `variants[].id` (wymagany jeden z variantId/variant dla pricingMode = variants) example: 664f1a2b3c4d5e6f7a8b9c11 variant: type: string minLength: 1 maxLength: 80 description: Nazwa wariantu (zamiast variantId) example: 30 dni required: - productId StorefrontConsentsDto: type: object properties: terms: type: boolean description: Akceptacja regulaminu sprzedawcy example: true immediateDelivery: type: boolean description: >- Połączona zgoda: żądanie natychmiastowej dostawy treści cyfrowej + przyjęcie do wiadomości utraty prawa odstąpienia example: true legalVersion: type: string pattern: ^[a-f0-9]{64}$ description: '`legal.version` sklepu, który pokazano kupującemu' example: a3f1c20000000000000000000000000000000000000000000000000000000000 required: - terms - immediateDelivery - legalVersion StorefrontCheckoutResultDto: type: object properties: orderId: type: string description: >- Identyfikator do strony statusu i `itemshop_order`: id zamówienia, a dla kilku pozycji — id grupy płatności example: 664f1a2b3c4d5e6f7a8b9c0d orderNumber: type: string description: Numer zamówienia albo grupy example: A1B2C3D4 statusKey: type: string description: >- Sekret strony statusu: `GET /orders/by-number/{orderNumber}/status?key=`. Pokaż go tylko kupującemu; wraca też w adresie powrotu jako `itemshop_key` example: k3m9x2p7qa status: type: string enum: - pending - paid - processing - completed - cancelled - failed - dispute example: pending groupId: type: string nullable: true description: Grupa płatności (kilka pozycji) — wtedy równa `orderId` example: null orderIds: description: Zamówienia pozycji w kolejności `items[]` example: - 664f1a2b3c4d5e6f7a8b9c0d type: array items: type: string redirectUrl: type: string description: Przekieruj tu kupującego (bramka albo strona statusu dla darmowych) example: https://pay.imoje.pl/… free: type: boolean description: Zamówienie darmowe (rabat 100%) — już opłacone, bez bramki example: false required: - orderId - orderNumber - statusKey - status - groupId - orderIds - redirectUrl - free ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.