{
  "openapi": "3.1.0",
  "info": {
    "title": "Moskito public catalog and prepared carts",
    "version": "1.0.0",
    "description": "Discover localized products and create an expiring customer-confirmed cart link. Does not create or pay for an order. Amounts are minor CZK units including VAT. No platform registration is implied."
  },
  "servers": [
    {
      "url": "https://www.moskito.cz"
    }
  ],
  "externalDocs": {
    "url": "https://www.moskito.cz/en/agent-shopping"
  },
  "paths": {
    "/api/products": {
      "get": {
        "operationId": "findProducts",
        "summary": "Find published, visible, stocked product variants with valid retail prices",
        "parameters": [
          {
            "name": "locale",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "cs",
                "en",
                "de",
                "sk",
                "pl"
              ],
              "default": "cs"
            },
            "description": "Catalog language; missing translations are excluded"
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "description": "Substring of localized name or variant SKU"
          },
          {
            "name": "sku",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "description": "Exact variant SKU"
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 24
            },
            "description": "Page size"
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Page number"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated products; use available_quantity for unreserved stock and variant_sku to prepare a cart",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "variant_id": {
                            "type": "string"
                          },
                          "variant_sku": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          },
                          "available_quantity": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "prepared_cart_eligible": {
                            "type": "boolean"
                          },
                          "price": {
                            "type": "object",
                            "properties": {
                              "amount_minor": {
                                "type": "integer"
                              },
                              "currency": {
                                "type": "string",
                                "const": "CZK"
                              },
                              "includes_vat": {
                                "type": "boolean",
                                "const": true
                              }
                            }
                          }
                        }
                      }
                    },
                    "next_page_url": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "errors": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/product-filters": {
      "get": {
        "operationId": "getProductFilters",
        "parameters": [
          {
            "name": "locale",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "cs",
                "en",
                "de",
                "sk",
                "pl"
              ],
              "default": "cs"
            },
            "description": "Language of filter values"
          }
        ],
        "responses": {
          "200": {
            "description": "Available parameter filters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "errors": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/prepared-carts": {
      "get": {
        "operationId": "describePreparedCarts",
        "responses": {
          "200": {
            "description": "Capabilities and limits",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "prepareCart",
        "summary": "Create a one-hour shopping link without reserving stock or creating an order",
        "description": "Customer confirms on the returned localized page. 20 distinct variants maximum. 10 requests/minute/IP. No shipping/payment fees in item prices. Links can be consumed once. Do not send personal information. Platform eligibility for products and gifts must be checked independently.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "items"
                ],
                "properties": {
                  "locale": {
                    "type": "string",
                    "enum": [
                      "cs",
                      "en",
                      "de",
                      "sk",
                      "pl"
                    ],
                    "default": "cs"
                  },
                  "items": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 20,
                    "items": {
                      "type": "object",
                      "required": [
                        "sku",
                        "quantity"
                      ],
                      "properties": {
                        "sku": {
                          "type": "string",
                          "maxLength": 100,
                          "description": "Exact variant_sku from catalog"
                        },
                        "quantity": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 99
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Prepared link (bearer capability, keep private)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "url",
                    "expires_at",
                    "items"
                  ],
                  "properties": {
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "locale": {
                      "type": "string",
                      "enum": [
                        "cs",
                        "en",
                        "de",
                        "sk",
                        "pl"
                      ],
                      "default": "cs"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "currency": {
                      "type": "string",
                      "const": "CZK"
                    },
                    "requires_customer_confirmation": {
                      "type": "boolean",
                      "const": true
                    },
                    "stock_reserved": {
                      "type": "boolean",
                      "const": false
                    },
                    "shipping_included": {
                      "type": "boolean",
                      "const": false
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "errors": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded; retry after the Retry-After header interval"
          }
        }
      }
    }
  }
}