{
  "openapi": "3.1.0",
  "info": {
    "title": "Aderlo.pl API",
    "version": "1.0.0",
    "summary": "Katalog, ceny, dostępność i warunki sklepu Aderlo.pl dla agentów AI.",
    "description": "Aderlo.pl is a Polish online store with 1% cashback on every purchase. Search products, check prices and availability, browse categories, read delivery and return terms, and — once the customer signs in — check the status of the customer's orders.\n\nCatalog endpoints are public and read-only. Orders are placed on the product page (`url`); there is no ordering endpoint. Account endpoints require an OAuth 2.1 access token issued to the signed-in customer.",
    "contact": {
      "name": "Aderlo.pl",
      "email": "kontakt@aderlo.pl",
      "url": "https://aderlo.pl"
    },
    "termsOfService": "https://aderlo.pl/regulamin"
  },
  "servers": [
    {
      "url": "https://aderlo.pl/api/v1"
    }
  ],
  "externalDocs": {
    "description": "llms.txt",
    "url": "https://aderlo.pl/llms.txt"
  },
  "tags": [
    {
      "name": "catalog",
      "description": "Produkty i kategorie"
    },
    {
      "name": "store",
      "description": "Dostawa, płatności, zwroty"
    },
    {
      "name": "account",
      "description": "Zamówienia zalogowanego klienta (OAuth)"
    }
  ],
  "paths": {
    "/products": {
      "get": {
        "tags": [
          "catalog"
        ],
        "operationId": "searchProducts",
        "summary": "Wyszukaj produkty",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "Fraza, najlepiej po polsku"
          },
          {
            "name": "min_price",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "max_price",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "in_stock",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "relevance",
                "newest",
                "price_asc",
                "price_desc"
              ]
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 48,
              "default": 12
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResult"
                }
              }
            }
          },
          "400": {
            "description": "Brak parametru q",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/products/{slug}": {
      "get": {
        "tags": [
          "catalog"
        ],
        "operationId": "getProduct",
        "summary": "Karta produktu",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          },
          "404": {
            "description": "Nie ma takiego produktu",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/categories": {
      "get": {
        "tags": [
          "catalog"
        ],
        "operationId": "listCategories",
        "summary": "Kategorie sklepu",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CategoryList"
                }
              }
            }
          }
        }
      }
    },
    "/categories/{slug}/products": {
      "get": {
        "tags": [
          "catalog"
        ],
        "operationId": "getCategoryProducts",
        "summary": "Produkty z kategorii",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CategoryProducts"
                }
              }
            }
          },
          "404": {
            "description": "Nie ma takiej kategorii",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/store/policies": {
      "get": {
        "tags": [
          "store"
        ],
        "operationId": "getStorePolicies",
        "summary": "Dostawa, płatności, zwroty i dane sprzedawcy",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StorePolicies"
                }
              }
            }
          }
        }
      }
    },
    "/account/orders": {
      "get": {
        "tags": [
          "account"
        ],
        "operationId": "listMyOrders",
        "summary": "Zamówienia zalogowanego klienta",
        "security": [
          {
            "oauth2": [
              "openid",
              "email",
              "profile"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderList"
                }
              }
            }
          },
          "401": {
            "description": "Brak lub nieważny token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/account/orders/{orderNumber}": {
      "get": {
        "tags": [
          "account"
        ],
        "operationId": "getMyOrder",
        "summary": "Szczegóły zamówienia klienta",
        "security": [
          {
            "oauth2": [
              "openid",
              "email",
              "profile"
            ]
          }
        ],
        "parameters": [
          {
            "name": "orderNumber",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "401": {
            "description": "Brak lub nieważny token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Nie ma takiego zamówienia na tym koncie",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "Konto klienta Aderlo (Supabase Auth, OAuth 2.1 z PKCE i dynamiczną rejestracją klienta).",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://lmatdmuinxggbtoqceuw.supabase.co/auth/v1/oauth/authorize",
            "tokenUrl": "https://lmatdmuinxggbtoqceuw.supabase.co/auth/v1/oauth/token",
            "refreshUrl": "https://lmatdmuinxggbtoqceuw.supabase.co/auth/v1/oauth/token",
            "scopes": {
              "openid": "Identyfikator klienta",
              "email": "Adres e-mail",
              "profile": "Imię i nazwisko"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "ProductSummary": {
        "type": "object",
        "required": [
          "slug",
          "name",
          "url",
          "price",
          "currency",
          "inStock"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Karta produktu w sklepie — tam klient składa zamówienie"
          },
          "price": {
            "type": [
              "number",
              "null"
            ],
            "description": "Kwota brutto w PLN, dwa miejsca po przecinku"
          },
          "regularPrice": {
            "type": [
              "number",
              "null"
            ],
            "description": "Cena przed obniżką, gdy produkt jest w promocji"
          },
          "currency": {
            "type": "string",
            "const": "PLN"
          },
          "inStock": {
            "type": "boolean"
          },
          "stockQuantity": {
            "type": "integer"
          },
          "imageUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "brand": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Product": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ProductSummary"
          },
          {
            "type": "object",
            "properties": {
              "description": {
                "type": "string"
              },
              "gtin": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "EAN/GTIN"
              },
              "images": {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "uri"
                }
              },
              "oversized": {
                "type": "boolean",
                "description": "Tylko kurier, własna stawka dostawy"
              },
              "variants": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ProductSummary"
                }
              }
            }
          }
        ]
      },
      "SearchResult": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProductSummary"
            }
          },
          "page": {
            "type": "integer"
          },
          "pageSize": {
            "type": "integer"
          },
          "hasMore": {
            "type": "boolean"
          }
        }
      },
      "Category": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "path": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "CategoryList": {
        "type": "object",
        "properties": {
          "categories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Category"
            }
          }
        }
      },
      "CategoryProducts": {
        "type": "object",
        "properties": {
          "category": {
            "$ref": "#/components/schemas/Category"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProductSummary"
            }
          },
          "page": {
            "type": "integer"
          },
          "totalPages": {
            "type": "integer"
          }
        }
      },
      "StorePolicies": {
        "type": "object",
        "additionalProperties": true
      },
      "OrderSummary": {
        "type": "object",
        "properties": {
          "orderNumber": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "processing",
              "shipped",
              "delivered",
              "cancelled",
              "refunded"
            ]
          },
          "statusLabel": {
            "type": "string"
          },
          "paymentStatus": {
            "type": [
              "string",
              "null"
            ]
          },
          "paymentStatusLabel": {
            "type": [
              "string",
              "null"
            ]
          },
          "total": {
            "type": [
              "number",
              "null"
            ],
            "description": "Kwota brutto w PLN, dwa miejsca po przecinku"
          },
          "currency": {
            "type": "string"
          },
          "placedAt": {
            "type": "string",
            "format": "date-time"
          },
          "deliveredAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "trackingUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Order": {
        "allOf": [
          {
            "$ref": "#/components/schemas/OrderSummary"
          },
          {
            "type": "object",
            "properties": {
              "shippingMethod": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "shippingCost": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Kwota brutto w PLN, dwa miejsca po przecinku"
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "quantity": {
                      "type": "integer"
                    },
                    "unitPrice": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "Kwota brutto w PLN, dwa miejsca po przecinku"
                    },
                    "total": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "Kwota brutto w PLN, dwa miejsca po przecinku"
                    },
                    "trackingNumber": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "OrderList": {
        "type": "object",
        "properties": {
          "orders": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderSummary"
            }
          }
        }
      }
    }
  }
}