openapi: 3.1.0
info:
  title: Wedkarz.pro REST API
  version: 1.1.0
  description: 'Kompletne API marketplace Wedkarz.pro. Wersja 1.1 dodaje integracje ERP/WMS: masowe aktualizacje stanów i
    cen, delta sync przez updated_since, external_id oraz rozszerzone webhooki działające także dla zamówień składanych przez
    WWW. API stosuje także dodatkowe limity ochronne dla logowania, rejestracji, odświeżania sesji, checkoutu oraz endpointów
    bulk. Odpowiedzi 429 mogą zawierać nagłówek Retry-After.'
  contact:
    name: Wedkarz.pro
    url: https://wedkarz.pro
servers:
- url: https://wedkarz.pro/api
  description: Produkcja
tags:
- name: Ogólne
- name: Autoryzacja
- name: Konto
- name: Katalog
- name: Sprzedawcy
- name: Zakupy
- name: Alerty
- name: Wiadomości
- name: Zestawy
- name: API sprzedawcy
- name: Synchronizacja ERP / WMS
  description: Bulk stock/price, external_id i synchronizacja różnicowa dla ERP, WMS i PIM.
- name: Zestawy społeczności
- name: Webhooks
paths:
  /v1:
    get:
      summary: Informacje o API
      description: Informacje o API
      tags:
      - Ogólne
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/health:
    get:
      summary: Stan dostępności API
      description: Pozwala sprawdzić, czy publiczne API odpowiada prawidłowo.
      tags:
      - Ogólne
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/auth/register:
    post:
      summary: Rejestracja kupującego
      description: Rejestracja kupującego
      tags:
      - Autoryzacja
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
            examples:
              default:
                value: {}
  /v1/auth/login:
    post:
      summary: Logowanie i pobranie tokenów
      description: Logowanie i pobranie tokenów Logowanie ma adaptacyjną ochronę przed brute-force i credential stuffingiem;
        kilka błędnych prób nie blokuje konta, a przy większej serii API może zwrócić 429 z Retry-After.
      tags:
      - Autoryzacja
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
            examples:
              default:
                value: {}
  /v1/auth/refresh:
    post:
      summary: Odświeżenie access tokena
      description: Odświeżenie access tokena
      tags:
      - Autoryzacja
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshRequest'
            examples:
              default:
                value: {}
  /v1/auth/logout:
    post:
      summary: Unieważnienie bieżącego tokena
      description: Unieważnienie bieżącego tokena
      tags:
      - Autoryzacja
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
  /v1/me:
    get:
      summary: Profil zalogowanego użytkownika
      description: Profil zalogowanego użytkownika
      tags:
      - Konto
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
    patch:
      summary: Edycja profilu
      description: Edycja profilu
      tags:
      - Konto
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                phone:
                  type: string
                password:
                  type: string
                  minLength: 8
            examples:
              default:
                value: {}
  /v1/me/addresses:
    get:
      summary: Adresy dostawy
      description: Adresy dostawy
      tags:
      - Konto
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
    post:
      summary: Dodaj adres dostawy
      description: Dodaj adres dostawy
      tags:
      - Konto
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressRequest'
            examples:
              default:
                value: {}
  /v1/me/addresses/{id}:
    patch:
      summary: Edytuj adres dostawy
      description: Edytuj adres dostawy
      tags:
      - Konto
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressRequest'
            examples:
              default:
                value: {}
      parameters:
      - name: id
        in: path
        required: true
        description: ID adresu
        schema:
          type: integer
    delete:
      summary: Usuń adres dostawy
      description: Usuń adres dostawy
      tags:
      - Konto
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: ID adresu
        schema:
          type: integer
  /v1/me/favorites:
    get:
      summary: Ulubione produkty
      description: Ulubione produkty
      tags:
      - Konto
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
    post:
      summary: Dodaj produkt do ulubionych
      description: Dodaj produkt do ulubionych
      tags:
      - Konto
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - product_id
              properties:
                product_id:
                  type: integer
                  example: 123
            examples:
              default:
                value: {}
  /v1/me/favorites/{productId}:
    delete:
      summary: Usuń z ulubionych
      description: Usuń z ulubionych
      tags:
      - Konto
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      parameters:
      - name: productId
        in: path
        required: true
        description: ID oferty
        schema:
          type: integer
  /v1/me/alerts:
    get:
      summary: Alerty cenowe i dostępności
      description: Alerty cenowe i dostępności
      tags:
      - Alerty
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
    post:
      summary: Utwórz lub zaktualizuj alert
      description: Utwórz lub zaktualizuj alert
      tags:
      - Alerty
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertRequest'
            examples:
              default:
                value: {}
  /v1/me/alerts/{id}:
    delete:
      summary: Wyłącz alert
      description: Wyłącz alert
      tags:
      - Alerty
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: ID alertu
        schema:
          type: integer
  /v1/me/notifications:
    get:
      summary: Powiadomienia użytkownika
      description: Powiadomienia użytkownika
      tags:
      - Konto
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      parameters:
      - name: page
        in: query
        required: false
        description: Strona
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Liczba rekordów
        schema:
          type: integer
  /v1/me/notifications/{id}/read:
    patch:
      summary: Oznacz powiadomienie jako przeczytane
      description: Oznacz powiadomienie jako przeczytane
      tags:
      - Konto
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: ID powiadomienia
        schema:
          type: integer
  /v1/me/messages:
    get:
      summary: Wiadomości
      description: Wiadomości
      tags:
      - Wiadomości
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
    post:
      summary: Wyślij wiadomość
      description: Wyślij wiadomość
      tags:
      - Wiadomości
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - recipient_id
              - subject
              - body
              properties:
                recipient_id:
                  type: integer
                order_id:
                  type: integer
                  nullable: true
                subject:
                  type: string
                body:
                  type: string
            examples:
              default:
                value: {}
  /v1/categories:
    get:
      summary: Lista/drzewo kategorii
      description: Lista/drzewo kategorii
      tags:
      - Katalog
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      parameters:
      - name: tree
        in: query
        required: false
        description: true = drzewo kategorii
        schema:
          type: boolean
  /v1/categories/{id}:
    get:
      summary: Szczegóły kategorii
      description: Szczegóły kategorii
      tags:
      - Katalog
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      parameters:
      - name: id
        in: path
        required: true
        description: ID kategorii
        schema:
          type: integer
  /v1/categories/{id}/products:
    get:
      summary: Produkty kategorii
      description: Produkty kategorii
      tags:
      - Katalog
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      parameters:
      - name: id
        in: path
        required: true
        description: ID kategorii
        schema:
          type: integer
      - name: page
        in: query
        required: false
        description: Numer strony
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Liczba rekordów
        schema:
          type: integer
  /v1/brands:
    get:
      summary: Lista marek
      description: Lista marek
      tags:
      - Katalog
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      parameters:
      - name: page
        in: query
        required: false
        description: Numer strony
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Liczba rekordów
        schema:
          type: integer
      - name: q
        in: query
        required: false
        description: Wyszukiwanie
        schema:
          type: string
  /v1/brands/{slug}:
    get:
      summary: Szczegóły marki
      description: Szczegóły marki
      tags:
      - Katalog
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      parameters:
      - name: slug
        in: path
        required: true
        description: Slug marki
        schema:
          type: string
  /v1/products:
    get:
      summary: Aktywne oferty produktów
      description: Aktywne oferty produktów
      tags:
      - Katalog
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      parameters:
      - name: page
        in: query
        required: false
        description: Numer strony
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Liczba rekordów
        schema:
          type: integer
      - name: q
        in: query
        required: false
        description: Nazwa/EAN/SKU/marka/opis
        schema:
          type: string
      - name: ean
        in: query
        required: false
        description: Dokładny EAN
        schema:
          type: string
      - name: category
        in: query
        required: false
        description: ID kategorii
        schema:
          type: integer
      - name: brand
        in: query
        required: false
        description: Nazwa marki
        schema:
          type: string
      - name: seller
        in: query
        required: false
        description: ID sprzedawcy
        schema:
          type: integer
      - name: available
        in: query
        required: false
        description: Tylko dostępne
        schema:
          type: boolean
      - name: price_from
        in: query
        required: false
        description: Cena od
        schema:
          type: number
      - name: price_to
        in: query
        required: false
        description: Cena do
        schema:
          type: number
      - name: sort
        in: query
        required: false
        description: popular|price_asc|price_desc|newest|rating|name
        schema:
          type: string
  /v1/products/{id}:
    get:
      summary: Szczegóły oferty produktu
      description: Szczegóły oferty produktu
      tags:
      - Katalog
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      parameters:
      - name: id
        in: path
        required: true
        description: ID oferty
        schema:
          type: integer
  /v1/products/{id}/reviews:
    get:
      summary: Opinie produktu
      description: Opinie produktu
      tags:
      - Katalog
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      parameters:
      - name: id
        in: path
        required: true
        description: ID oferty
        schema:
          type: integer
      - name: page
        in: query
        required: false
        description: Numer strony
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Liczba rekordów
        schema:
          type: integer
    post:
      summary: Dodaj opinię po zakupie
      description: Dodaj opinię po zakupie
      tags:
      - Katalog
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReviewRequest'
            examples:
              default:
                value: {}
      parameters:
      - name: id
        in: path
        required: true
        description: ID oferty
        schema:
          type: integer
  /v1/products/{id}/bought-together:
    get:
      summary: Co kupili inni do produktu
      description: Co kupili inni do produktu
      tags:
      - Katalog
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      parameters:
      - name: id
        in: path
        required: true
        description: ID produktu
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: 1-12 wyników
        schema:
          type: integer
  /v1/catalog-products:
    get:
      summary: Wspólny katalog EAN
      description: Wspólny katalog EAN
      tags:
      - Katalog
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      parameters:
      - name: page
        in: query
        required: false
        description: Numer strony
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Liczba rekordów
        schema:
          type: integer
      - name: q
        in: query
        required: false
        description: Wyszukiwanie
        schema:
          type: string
      - name: category
        in: query
        required: false
        description: Kategoria
        schema:
          type: integer
      - name: brand
        in: query
        required: false
        description: Marka
        schema:
          type: string
  /v1/catalog-products/{id}:
    get:
      summary: Szczegóły produktu katalogowego
      description: Szczegóły produktu katalogowego
      tags:
      - Katalog
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      parameters:
      - name: id
        in: path
        required: true
        description: ID produktu katalogowego
        schema:
          type: integer
  /v1/ean/{ean}:
    get:
      summary: Produkt katalogowy i wszystkie oferty dla EAN
      description: Produkt katalogowy i wszystkie oferty dla EAN
      tags:
      - Katalog
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      parameters:
      - name: ean
        in: path
        required: true
        description: EAN/GTIN
        schema:
          type: string
  /v1/search:
    get:
      summary: Wyszukiwanie pełnotekstowe ofert
      description: Wyszukiwanie pełnotekstowe ofert
      tags:
      - Katalog
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      parameters:
      - name: page
        in: query
        required: false
        description: Numer strony
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Liczba rekordów
        schema:
          type: integer
      - name: q
        in: query
        required: true
        description: Fraza min. 2 znaki
        schema:
          type: string
  /v1/sellers:
    get:
      summary: Publiczni sprzedawcy
      description: Publiczni sprzedawcy
      tags:
      - Sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      parameters:
      - name: page
        in: query
        required: false
        description: Numer strony
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Liczba rekordów
        schema:
          type: integer
      - name: q
        in: query
        required: false
        description: Nazwa/opis
        schema:
          type: string
  /v1/sellers/{id}:
    get:
      summary: Publiczny profil sprzedawcy
      description: Publiczny profil sprzedawcy
      tags:
      - Sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      parameters:
      - name: id
        in: path
        required: true
        description: ID sprzedawcy
        schema:
          type: integer
  /v1/sellers/{id}/products:
    get:
      summary: Produkty sprzedawcy
      description: Produkty sprzedawcy
      tags:
      - Sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      parameters:
      - name: id
        in: path
        required: true
        description: ID sprzedawcy
        schema:
          type: integer
      - name: page
        in: query
        required: false
        description: Numer strony
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Liczba rekordów
        schema:
          type: integer
  /v1/bundles:
    get:
      summary: Publiczne gotowe zestawy
      description: Publiczne gotowe zestawy
      tags:
      - Zestawy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/bundles/{id}:
    get:
      summary: Szczegóły zestawu
      description: Szczegóły zestawu
      tags:
      - Zestawy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      parameters:
      - name: id
        in: path
        required: true
        description: ID zestawu
        schema:
          type: integer
  /v1/cart:
    get:
      summary: Koszyk API kupującego
      description: Koszyk API kupującego
      tags:
      - Zakupy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
    delete:
      summary: Wyczyść koszyk
      description: Wyczyść koszyk
      tags:
      - Zakupy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
  /v1/cart/items:
    post:
      summary: Dodaj produkt do koszyka
      description: Dodaj produkt do koszyka
      tags:
      - Zakupy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartItemRequest'
            examples:
              default:
                value: {}
  /v1/cart/items/{productId}:
    patch:
      summary: Zmień ilość produktu
      description: Zmień ilość produktu
      tags:
      - Zakupy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - quantity
              properties:
                quantity:
                  type: integer
                  minimum: 0
            examples:
              default:
                value: {}
      parameters:
      - name: productId
        in: path
        required: true
        description: ID oferty
        schema:
          type: integer
    delete:
      summary: Usuń produkt z koszyka
      description: Usuń produkt z koszyka
      tags:
      - Zakupy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      parameters:
      - name: productId
        in: path
        required: true
        description: ID oferty
        schema:
          type: integer
  /v1/cart/shipping-methods:
    get:
      summary: Dostępne metody dostawy dla koszyka
      description: Dostępne metody dostawy dla koszyka
      tags:
      - Zakupy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
  /v1/checkout:
    post:
      summary: Utwórz zamówienie i płatność
      description: Tworzy zamówienie z aktywnego koszyka API. Nagłówek Idempotency-Key chroni przed podwójnym utworzeniem
        zamówienia.
      tags:
      - Zakupy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutRequest'
            examples:
              default:
                value: {}
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        description: Unikalny klucz dla bezpiecznego ponowienia checkoutu.
        schema:
          type: string
          example: order-2026-08-24-001
  /v1/orders:
    get:
      summary: Zamówienia kupującego
      description: Zamówienia kupującego
      tags:
      - Zakupy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      parameters:
      - name: page
        in: query
        required: false
        description: Numer strony
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Liczba rekordów
        schema:
          type: integer
  /v1/orders/{id}:
    get:
      summary: Szczegóły zamówienia
      description: Szczegóły zamówienia
      tags:
      - Zakupy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: ID zamówienia
        schema:
          type: integer
  /v1/orders/{id}/returns:
    post:
      summary: Utwórz zwrot
      description: Utwórz zwrot
      tags:
      - Zakupy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReturnRequest'
            examples:
              default:
                value: {}
      parameters:
      - name: id
        in: path
        required: true
        description: ID zamówienia
        schema:
          type: integer
  /v1/orders/{id}/disputes:
    post:
      summary: Otwórz spór/zgłoszenie
      description: Otwórz spór/zgłoszenie
      tags:
      - Zakupy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DisputeRequest'
            examples:
              default:
                value: {}
      parameters:
      - name: id
        in: path
        required: true
        description: ID zamówienia
        schema:
          type: integer
  /v1/seller:
    get:
      summary: Profil zalogowanego sprzedawcy
      description: Profil zalogowanego sprzedawcy
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
    patch:
      summary: Edytuj profil sprzedawcy
      description: Edytuj profil sprzedawcy
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            examples:
              default:
                value: {}
  /v1/seller/products:
    get:
      summary: Oferty sprzedawcy
      description: Oferty sprzedawcy
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      parameters:
      - name: page
        in: query
        required: false
        description: Numer strony
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Liczba rekordów
        schema:
          type: integer
      - name: q
        in: query
        required: false
        description: Nazwa/EAN/SKU/marka
        schema:
          type: string
      - name: status
        in: query
        required: false
        description: Filtr statusu
        schema:
          type: string
      - name: updated_since
        in: query
        required: false
        description: 'Delta sync: tylko rekordy zmienione po tej dacie ISO 8601.'
        schema:
          type: string
          format: date-time
      - name: updated_after_id
        in: query
        required: false
        description: Kursor pomocniczy dla rekordów z tym samym updated_at.
        schema:
          type: integer
      - name: external_id
        in: query
        required: false
        schema:
          type: string
      - name: ean
        in: query
        required: false
        schema:
          type: string
      - name: sku
        in: query
        required: false
        schema:
          type: string
    post:
      summary: Wystaw produkt/ofertę
      description: Wystaw produkt/ofertę
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SellerProductCreate'
            examples:
              default:
                value: {}
  /v1/seller/products/{id}:
    get:
      summary: Szczegóły własnej oferty
      description: Szczegóły własnej oferty
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: ID oferty
        schema:
          type: integer
    patch:
      summary: Cena, stan, opis, status oferty
      description: Cena, stan, opis, status oferty
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SellerProductUpdate'
            examples:
              default:
                value: {}
      parameters:
      - name: id
        in: path
        required: true
        description: ID oferty
        schema:
          type: integer
    delete:
      summary: Wyłącz ofertę
      description: Wyłącz ofertę
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: ID oferty
        schema:
          type: integer
  /v1/seller/products/{id}/images:
    post:
      summary: Wgraj zdjęcia produktu multipart/form-data
      description: 'Pole multipart: images[]. JPG/PNG/WebP, max 5 MB/szt., maksymalnie 8 zdjęć na produkt.'
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: ID oferty
        schema:
          type: integer
  /v1/seller/products/{id}/stats:
    get:
      summary: Statystyki zainteresowania i sugestia ceny
      description: Statystyki zainteresowania i sugestia ceny
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: ID oferty
        schema:
          type: integer
  /v1/seller/analytics:
    get:
      summary: Zbiorcze statystyki sklepu
      description: Zbiorcze statystyki sklepu
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      parameters:
      - name: days
        in: query
        required: false
        description: 1-365 dni
        schema:
          type: integer
  /v1/seller/orders:
    get:
      summary: Zamówienia sprzedawcy
      description: Zamówienia sprzedawcy
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      parameters:
      - name: page
        in: query
        required: false
        description: Numer strony
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Liczba rekordów
        schema:
          type: integer
      - name: status
        in: query
        required: false
        description: Status
        schema:
          type: string
      - name: updated_since
        in: query
        required: false
        description: 'Delta sync: tylko zamówienia zmienione po tej dacie.'
        schema:
          type: string
          format: date-time
      - name: updated_after_id
        in: query
        required: false
        schema:
          type: integer
      - name: external_id
        in: query
        required: false
        schema:
          type: string
      - name: number
        in: query
        required: false
        schema:
          type: string
      - name: created_since
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: include_items
        in: query
        required: false
        description: Dodaj pozycje zamówienia do listy.
        schema:
          type: boolean
          default: false
  /v1/seller/orders/{id}:
    get:
      summary: Szczegóły części zamówienia
      description: Szczegóły części zamówienia
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: ID seller_order
        schema:
          type: integer
    patch:
      summary: Zmień status i tracking
      description: Zmień status i tracking
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SellerOrderUpdate'
            examples:
              erp_assignment:
                value:
                  external_id: ERP-ZAM-2026-991
              shipping:
                value:
                  status: shipped
                  tracking_number: '1234567890'
      parameters:
      - name: id
        in: path
        required: true
        description: ID seller_order
        schema:
          type: integer
  /v1/seller/shipping-methods:
    get:
      summary: Metody wysyłki sprzedawcy
      description: Metody wysyłki sprzedawcy
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
    post:
      summary: Dodaj metodę wysyłki
      description: Dodaj metodę wysyłki
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShippingMethodRequest'
            examples:
              default:
                value: {}
  /v1/seller/shipping-methods/{id}:
    patch:
      summary: Edytuj metodę wysyłki
      description: Edytuj metodę wysyłki
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShippingMethodRequest'
            examples:
              default:
                value: {}
      parameters:
      - name: id
        in: path
        required: true
        description: ID metody
        schema:
          type: integer
    delete:
      summary: Usuń metodę wysyłki
      description: Usuń metodę wysyłki
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: ID metody
        schema:
          type: integer
  /v1/seller/payouts:
    get:
      summary: Wypłaty i saldo
      description: Wypłaty i saldo
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
  /v1/seller/settlements:
    get:
      summary: Miesięczne rozliczenia
      description: Miesięczne rozliczenia
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
  /v1/seller/bundles:
    get:
      summary: Zestawy sprzedawcy
      description: Zestawy sprzedawcy
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
    post:
      summary: Utwórz zestaw sprzedawcy
      description: Utwórz zestaw sprzedawcy
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BundleRequest'
            examples:
              default:
                value: {}
  /v1/seller/bundles/{id}:
    patch:
      summary: Edytuj zestaw sprzedawcy
      description: Edytuj zestaw sprzedawcy
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BundleRequest'
            examples:
              default:
                value: {}
      parameters:
      - name: id
        in: path
        required: true
        description: ID zestawu
        schema:
          type: integer
    delete:
      summary: Usuń zestaw sprzedawcy
      description: Usuń zestaw sprzedawcy
      tags:
      - API sprzedawcy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: ID zestawu
        schema:
          type: integer
  /v1/community/bundles:
    get:
      summary: Moje zestawy społeczności
      description: Moje zestawy społeczności
      tags:
      - Zestawy społeczności
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
    post:
      summary: Utwórz zestaw społeczności
      description: Utwórz zestaw społeczności
      tags:
      - Zestawy społeczności
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BundleRequest'
            examples:
              default:
                value: {}
  /v1/community/bundles/{id}:
    patch:
      summary: Edytuj zestaw społeczności
      description: Edytuj zestaw społeczności
      tags:
      - Zestawy społeczności
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BundleRequest'
            examples:
              default:
                value: {}
      parameters:
      - name: id
        in: path
        required: true
        description: ID zestawu
        schema:
          type: integer
    delete:
      summary: Usuń zestaw społeczności
      description: Usuń zestaw społeczności
      tags:
      - Zestawy społeczności
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: ID zestawu
        schema:
          type: integer
  /v1/webhooks:
    get:
      summary: Lista webhooków
      description: Lista webhooków
      tags:
      - Webhooks
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
    post:
      summary: Dodaj webhook HTTPS
      description: Dodaj webhook HTTPS
      tags:
      - Webhooks
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRequest'
            examples:
              default:
                value: {}
  /v1/webhooks/{id}:
    patch:
      summary: Edytuj webhook
      description: Edytuj webhook
      tags:
      - Webhooks
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRequest'
            examples:
              default:
                value: {}
      parameters:
      - name: id
        in: path
        required: true
        description: ID webhooka
        schema:
          type: integer
    delete:
      summary: Usuń webhook
      description: Usuń webhook
      tags:
      - Webhooks
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: ID webhooka
        schema:
          type: integer
  /v1/webhooks/{id}/test:
    post:
      summary: Wyślij test webhooka
      description: Wyślij test webhooka
      tags:
      - Webhooks
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: ID webhooka
        schema:
          type: integer
  /v1/auth/seller-register:
    post:
      summary: Rejestracja konta sprzedawcy
      description: Tworzy użytkownika seller oraz profil sprzedawcy ze statusem pending. Publikacja produktów wymaga późniejszego
        zatwierdzenia sprzedawcy przez administratora.
      tags:
      - Autoryzacja
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SellerRegisterRequest'
      responses:
        '201':
          description: Sprzedawca utworzony
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/seller/products/bulk:
    patch:
      summary: Masowa aktualizacja ofert
      description: Aktualizuje do 500 produktów jednym requestem. Obsługuje cenę, stan, status, SKU, external_id, opis i czas
        realizacji. Odpowiedź zawiera wynik każdej pozycji.
      tags:
      - Synchronizacja ERP / WMS
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkProductsRequest'
            examples:
              erp_sync:
                value:
                  atomic: false
                  items:
                  - external_id: ERP-1001
                    stock: 12
                    price: 149.99
                  - ean: '5901234567890'
                    stock: 0
                  - product_id: 123
                    set_external_id: SUBIEKT-7788
                    price: 99.9
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/seller/inventory/bulk:
    patch:
      summary: Masowa synchronizacja magazynu
      description: Wariant bulk zoptymalizowany do aktualizacji stock i external_id. Do 500 pozycji na request.
      tags:
      - Synchronizacja ERP / WMS
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkProductsRequest'
            examples:
              erp_sync:
                value:
                  atomic: false
                  items:
                  - external_id: ERP-1001
                    stock: 12
                    price: 149.99
                  - ean: '5901234567890'
                    stock: 0
                  - product_id: 123
                    set_external_id: SUBIEKT-7788
                    price: 99.9
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/seller/prices/bulk:
    patch:
      summary: Masowa synchronizacja cen
      description: Wariant bulk zoptymalizowany do aktualizacji price i external_id. Zmiany ceny trafiają do historii ceny/Omnibus.
      tags:
      - Synchronizacja ERP / WMS
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkProductsRequest'
            examples:
              erp_sync:
                value:
                  atomic: false
                  items:
                  - external_id: ERP-1001
                    stock: 12
                    price: 149.99
                  - ean: '5901234567890'
                    stock: 0
                  - product_id: 123
                    set_external_id: SUBIEKT-7788
                    price: 99.9
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/seller/sync:
    get:
      summary: Delta sync produktów i zamówień
      description: Jednym żądaniem zwraca produkty i zamówienia zmienione od wskazanego punktu. Pierwsze wywołanie może użyć
        updated_since. Kolejne strony powinny korzystać z niezależnych kursorów products_since/products_after_id oraz orders_since/orders_after_id,
        aby żadna kolekcja nie pominęła rekordów.
      tags:
      - Synchronizacja ERP / WMS
      security:
      - bearerAuth: []
      parameters:
      - name: updated_since
        in: query
        required: false
        description: Wspólny punkt startowy dla produktów i zamówień. Alternatywnie podaj osobno products_since i orders_since.
        schema:
          type: string
          format: date-time
      - name: orders_since
        in: query
        required: false
        description: Osobny kursor czasu zamówień; przy kolejnej stronie użyj next_updated_since z orders_sync.
        schema:
          type: string
          format: date-time
      - name: products_since
        in: query
        required: false
        description: Osobny kursor czasu produktów; przy kolejnej stronie użyj next_updated_since z products_sync.
        schema:
          type: string
          format: date-time
      - name: products_after_id
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
      - name: orders_after_id
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 200
      - name: product_status
        in: query
        required: false
        schema:
          type: string
      - name: order_status
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/seller/products/external/{externalId}:
    get:
      summary: Pobierz produkt po external_id
      description: Lookup rekordu po identyfikatorze zewnętrznego ERP/WMS.
      tags:
      - Synchronizacja ERP / WMS
      security:
      - bearerAuth: []
      parameters:
      - name: externalId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/seller/orders/external/{externalId}:
    get:
      summary: Pobierz zamówienie po external_id
      description: Lookup rekordu po identyfikatorze zewnętrznego ERP/WMS.
      tags:
      - Synchronizacja ERP / WMS
      security:
      - bearerAuth: []
      parameters:
      - name: externalId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: opaque
  schemas:
    Envelope:
      type: object
      properties:
        data: {}
        meta:
          type: object
        links:
          type: object
        request_id:
          type: string
          format: uuid
    RegisterRequest:
      type: object
      required:
      - name
      - email
      - password
      properties:
        name:
          type: string
          example: Jan Kowalski
        email:
          type: string
          format: email
          example: jan@example.com
        password:
          type: string
          minLength: 8
          example: BardzoMocneHaslo123!
        phone:
          type: string
          example: '+48123123123'
    LoginRequest:
      type: object
      required:
      - email
      - password
      properties:
        email:
          type: string
          format: email
        password:
          type: string
        device_name:
          type: string
          example: ERP magazyn
    RefreshRequest:
      type: object
      required:
      - refresh_token
      properties:
        refresh_token:
          type: string
    AddressRequest:
      type: object
      properties:
        label:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        company:
          type: string
        street:
          type: string
        postal_code:
          type: string
        city:
          type: string
        phone:
          type: string
        is_default:
          type: boolean
    AlertRequest:
      type: object
      required:
      - ean
      - type
      properties:
        ean:
          type: string
          example: '5901234123457'
        type:
          type: string
          enum:
          - price
          - availability
        target_price:
          type: number
          format: float
          example: 199.99
    ReviewRequest:
      type: object
      required:
      - rating
      - comment
      properties:
        rating:
          type: integer
          minimum: 1
          maximum: 5
        comment:
          type: string
    CartItemRequest:
      type: object
      required:
      - product_id
      properties:
        product_id:
          type: integer
          example: 123
        quantity:
          type: integer
          minimum: 1
          example: 2
    CheckoutRequest:
      type: object
      required:
      - first_name
      - last_name
      - street
      - postal_code
      - city
      - email
      - phone
      - shipping_method
      properties:
        first_name:
          type: string
        last_name:
          type: string
        company:
          type: string
        street:
          type: string
        postal_code:
          type: string
        city:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        payment_provider:
          type: string
          example: payu_marketplace
        shipping_method:
          type: object
          additionalProperties:
            type: integer
          description: Mapa seller_id -> shipping_method_id
        pickup_point_code:
          type: object
          additionalProperties:
            type: string
        pickup_point_name:
          type: object
          additionalProperties:
            type: string
        pickup_point_address:
          type: object
          additionalProperties:
            type: string
    ReturnRequest:
      type: object
      required:
      - seller_order_id
      - reason
      properties:
        seller_order_id:
          type: integer
        reason:
          type: string
        details:
          type: string
    DisputeRequest:
      type: object
      required:
      - seller_order_id
      - subject
      - description
      properties:
        seller_order_id:
          type: integer
        subject:
          type: string
        description:
          type: string
    SellerProductCreate:
      type: object
      required:
      - ean
      - price
      - stock
      properties:
        ean:
          type: string
        price:
          type: number
        stock:
          type: integer
        sku:
          type: string
        status:
          type: string
          enum:
          - active
          - draft
          - inactive
        description:
          type: string
        dispatch_min_days:
          type: integer
        dispatch_max_days:
          type: integer
        name:
          type: string
          description: Wymagane tylko dla EAN spoza katalogu
        category_id:
          type: integer
          description: Wymagane tylko dla EAN spoza katalogu
        brand:
          type: string
        shipping_weight:
          type: number
        attributes:
          type: object
          additionalProperties: true
        external_id:
          type:
          - string
          - 'null'
          maxLength: 190
          description: Identyfikator produktu/oferty w zewnętrznym ERP/WMS. Unikalny w obrębie sprzedawcy.
    SellerProductUpdate:
      type: object
      properties:
        price:
          type: number
        stock:
          type: integer
        sku:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
          - active
          - draft
          - inactive
          - pending
        low_stock_threshold:
          type: integer
        dispatch_min_days:
          type: integer
        dispatch_max_days:
          type: integer
        external_id:
          type:
          - string
          - 'null'
          maxLength: 190
          description: Identyfikator produktu/oferty w zewnętrznym ERP/WMS. Unikalny w obrębie sprzedawcy.
    ShippingMethodRequest:
      type: object
      properties:
        name:
          type: string
        code:
          type: string
        provider_code:
          type: string
        delivery_type:
          type: string
        price:
          type: number
        free_from:
          type: number
        active:
          type: boolean
    BundleRequest:
      type: object
      required:
      - name
      - items
      properties:
        name:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
          - draft
          - active
        items:
          type: array
          minItems: 2
          maxItems: 30
          items:
            type: object
            required:
            - product_id
            properties:
              product_id:
                type: integer
              quantity:
                type: integer
                minimum: 1
                maximum: 99
    WebhookRequest:
      type: object
      required:
      - url
      - events
      properties:
        url:
          type: string
          format: uri
          example: https://erp.example.com/webhooks/wedkarz
        events:
          type: array
          items:
            type: string
            enum:
            - '*'
            - order.created
            - order.updated
            - seller_order.created
            - seller_order.status.updated
            - product.created
            - product.updated
            - product.price.updated
            - product.stock.updated
            - product.status.updated
            - products.bulk.updated
            - webhook.test
          description: Subskrybowane zdarzenia. Webhooki zamówień są generowane również dla zakupów wykonanych przez zwykłą
            stronę WWW, nie tylko API.
        description:
          type: string
        status:
          type: string
          enum:
          - active
          - inactive
    CategoryRequest:
      type: object
      properties:
        parent_id:
          type: integer
          nullable: true
        name:
          type: string
        slug:
          type: string
        sort:
          type: integer
        active:
          type: boolean
    BrandRequest:
      type: object
      properties:
        name:
          type: string
        slug:
          type: string
        description:
          type: string
        dispatch_min_days:
          type: integer
        dispatch_max_days:
          type: integer
        active:
          type: boolean
        sort:
          type: integer
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
        request_id:
          type: string
          format: uuid
    SellerRegisterRequest:
      type: object
      required:
      - name
      - email
      - password
      - shop_name
      - legal_name
      - tax_id
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 8
        phone:
          type: string
        shop_name:
          type: string
        legal_name:
          type: string
        tax_id:
          type: string
          description: NIP
        regon:
          type: string
        address:
          type: string
        warehouse_street:
          type: string
        warehouse_postal_code:
          type: string
        warehouse_city:
          type: string
        bank_account:
          type: string
    SellerOrderUpdate:
      type: object
      properties:
        status:
          type: string
          enum:
          - awaiting_payment
          - paid
          - processing
          - ready
          - packed
          - shipped
          - delivered
          - cancelled
          - returned
        tracking_number:
          type: string
        external_id:
          type:
          - string
          - 'null'
          maxLength: 190
          description: ID zamówienia/części zamówienia w zewnętrznym systemie sprzedawcy.
      minProperties: 1
    BulkProductItem:
      type: object
      description: Produkt można wskazać przez product_id, ean, match_sku, match_external_id, external_id lub sku. Do jawnej
        zmiany identyfikatorów użyj set_sku / set_external_id.
      properties:
        product_id:
          type: integer
        ean:
          type: string
        sku:
          type: string
        match_external_id:
          type: string
        external_id:
          type:
          - string
          - 'null'
          description: Może być selektorem, a gdy produkt wskazano innym polem — nową wartością external_id.
        set_external_id:
          type:
          - string
          - 'null'
          description: Jawna nowa wartość external_id.
        price:
          type: number
          minimum: 0.01
        stock:
          type: integer
          minimum: 0
        status:
          type: string
          enum:
          - active
          - draft
          - inactive
          - pending
        low_stock_threshold:
          type: integer
          minimum: 0
        description:
          type: string
        dispatch_min_days:
          type: integer
          minimum: 0
        dispatch_max_days:
          type: integer
          minimum: 0
        match_sku:
          type: string
          description: Jawny SKU używany tylko do znalezienia produktu.
        set_sku:
          type: string
          description: Nowa wartość SKU. Użyj, gdy chcesz zmienić SKU bez niejednoznaczności selektora.
    BulkProductsRequest:
      type: object
      required:
      - items
      properties:
        atomic:
          type: boolean
          default: false
          description: true = cała paczka zostanie wycofana, jeśli choć jedna pozycja jest błędna.
        items:
          type: array
          minItems: 1
          maxItems: 500
          items:
            $ref: '#/components/schemas/BulkProductItem'
  responses:
    BadRequest:
      description: Błędne żądanie
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Brak/niepoprawny token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: Błąd walidacji
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Przekroczono limit żądań lub aktywna jest czasowa ochrona przed nadużyciami.
      headers:
        Retry-After:
          description: Liczba sekund do kolejnej dozwolonej próby.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'