{
  "openapi": "3.1.0",
  "info": {
    "title": "AWW — публичный API данных",
    "version": "1.0.0",
    "summary": "Комиссии Kaspi.kz и тарифы доставки, сервисы автоматизации с ценами, глоссарий и индекс материалов — в JSON.",
    "description": "Read-only API без ключа, с открытым CORS, над наборами, которые публикует этот сайт: что даёт продавцу платформа AWW и сколько это стоит; комиссии Kaspi.kz по 21 категориям вместе с тарифами доставки; 22 сервисов автоматизации и репрайсинга для продавцов Kaspi с ценами (15 подробно); глоссарий из 161 терминов на трёх языках; индекс всех материалов сайта. Те же цифры, что рендерятся на страницах — второй копии нет. Повторное использование — CC BY 4.0 со ссылкой на источник.",
    "contact": {
      "email": "support@aww.kz",
      "url": "https://aww.kz/contact/"
    },
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    },
    "termsOfService": "https://aww.kz/terms/"
  },
  "servers": [
    {
      "url": "https://aww.kz/api/v1",
      "description": "Статические файлы, отдаёт nginx на origin"
    }
  ],
  "paths": {
    "/index.json": {
      "get": {
        "operationId": "getIndex",
        "summary": "Точка входа: все эндпоинты, счётчики строк, лицензия",
        "responses": {
          "200": {
            "description": "Описание API",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/aww.json": {
      "get": {
        "operationId": "getAww",
        "summary": "Что AWW делает для продавца Kaspi, цена и ограничения",
        "description": "Возможности платформы с адресом страницы у каждой, условия бесплатного доступа, платформы, лимиты и блок not_included — чего продукт не делает. Оценок не содержит; два сравнения в how_it_compares вычисляются из services.json.",
        "responses": {
          "200": {
            "description": "Описание продукта",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/kaspi-fees.json": {
      "get": {
        "operationId": "getKaspiFees",
        "summary": "Комиссии Kaspi.kz по категориям и тарифы доставки",
        "description": "Те же ставки, по которым считает калькулятор на /calc/. Сверено 2026-06-16.",
        "responses": {
          "200": {
            "description": "Ставки комиссий, сбор за обработку данных и тарифы доставки",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KaspiFees"
                }
              }
            }
          }
        }
      }
    },
    "/services.json": {
      "get": {
        "operationId": "getServices",
        "summary": "Сколько стоит автоматизация и репрайсинг для продавцов Kaspi",
        "description": "Ценовой срез рынка, снятый с официальных сайтов 2026-06-23. Набор опубликован AWW — одним из сервисов на этом рынке; это указано в поле published_by. Оценок конкурентов набор не содержит, только числа.",
        "responses": {
          "200": {
            "description": "Диапазон и медиана тарифов, годовая стоимость, и цена AWW",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceList"
                }
              }
            }
          }
        }
      }
    },
    "/glossary.json": {
      "get": {
        "operationId": "getGlossary",
        "summary": "Глоссарий терминов маркетплейсов, ru/en/kk",
        "responses": {
          "200": {
            "description": "Термины с короткими определениями и ссылками на разбор",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Glossary"
                }
              }
            }
          }
        }
      }
    },
    "/articles.json": {
      "get": {
        "operationId": "getArticles",
        "summary": "Индекс материалов: журнал, глоссарий, сравнения",
        "responses": {
          "200": {
            "description": "Индекс страниц с датами и URL",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/status.json": {
      "get": {
        "operationId": "getStatus",
        "summary": "Свежесть наборов данных",
        "description": "Не health-check: сравнивайте даты, а не код ответа.",
        "responses": {
          "200": {
            "description": "Даты и счётчики",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getOpenapi",
        "summary": "Этот документ",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "KaspiFees": {
        "type": "object",
        "required": [
          "commission_categories",
          "data_processing_fee",
          "delivery"
        ],
        "properties": {
          "verified": {
            "type": "string",
            "format": "date",
            "description": "Дата, на которую ставки сверены."
          },
          "commission_categories": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string",
                  "description": "Название категории так, как его называет Kaspi."
                },
                "commission_percent": {
                  "type": "number",
                  "description": "ВЕРХНЯЯ граница вилки, а не ставка из вашего договора. Kaspi публикует для части категорий диапазон (7–12%, 12–15%); здесь стоит худший для продавца край, потому что калькулятор обязан считать по нему. Точную ставку смотрите в кабинете продавца."
                },
                "commission_min_percent": {
                  "type": "number"
                },
                "commission_max_percent": {
                  "type": "number"
                },
                "is_range": {
                  "type": "boolean",
                  "description": "true, если Kaspi публикует вилку, а не одну ставку."
                },
                "display": {
                  "type": "string",
                  "description": "Как ставка печатается в таблице: «12%» или «12–15%»."
                }
              }
            }
          },
          "data_processing_fee": {
            "type": "object",
            "description": "Сбор за обработку данных. Берётся ДОПОЛНИТЕЛЬНО к комиссии категории и считается от цены товара, а не от прибыли и не от маржи.",
            "properties": {
              "rate": {
                "type": "number",
                "description": "Доля: 0.0075."
              },
              "percent": {
                "type": "number",
                "description": "То же в процентах: 0.75."
              },
              "base": {
                "type": "string"
              }
            }
          },
          "delivery": {
            "type": "object",
            "description": "Тарифы доставки в тенге, НДС уже включён. Ключи tariffs_kzt — режимы доставки, ключи внутри — ступени веса из weight_bands. Самовывоз и своя доставка не тарифицируются.",
            "properties": {
              "vat_included": {
                "type": "boolean"
              },
              "weight_bands": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "tariffs_kzt": {
                "type": "object"
              },
              "return_cost_share": {
                "type": "number",
                "description": "Доля стоимости доставки, в которую обходится возврат: 0.5."
              }
            }
          },
          "caveats": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "licence": {
            "type": "object",
            "description": "Условия повторного использования. Одинаковый блок во всех ответах.",
            "properties": {
              "name": {
                "type": "string",
                "const": "CC BY 4.0"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "attribution": {
                "type": "string"
              },
              "note": {
                "type": "string"
              }
            }
          }
        }
      },
      "ServiceList": {
        "type": "object",
        "description": "Ценовой срез рынка автоматизации Kaspi.kz. Набор содержит только числа с официальных сайтов: адресов сервисов, их собственных формулировок о себе и оценок их сильных сторон здесь нет — разбор каждой пары живёт на страницах /compare/, где у него есть контекст.",
        "properties": {
          "researched": {
            "type": "string",
            "format": "date"
          },
          "published_by": {
            "type": "object",
            "description": "Кто опубликовал набор, и раскрытие конфликта интересов."
          },
          "market": {
            "type": "object",
            "description": "Сведённая арифметика: минимум, медиана и максимум месячного тарифа по рынку, то же за год, и цена AWW. Это то, ради чего набор имеет смысл цитировать.",
            "properties": {
              "monthly_price_kzt": {
                "type": "object"
              },
              "annual_cost_kzt": {
                "type": "object"
              },
              "aww_monthly_price_kzt": {
                "type": "number",
                "const": 0
              },
              "price_hidden_for": {
                "type": "integer",
                "description": "Сколько сервисов не публикуют тариф до регистрации."
              }
            }
          },
          "aww": {
            "type": "object",
            "description": "Продукт, который публикует набор. Вынесен отдельно, а не подмешан в список."
          },
          "services": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "price_from": {
                  "type": "string",
                  "description": "Тариф так, как он опубликован сервисом, вместе с условием («10 000 ₸/мес, 200 товаров»)."
                },
                "price_from_kzt": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "То же число, пригодное для арифметики: нижняя граница опубликованного тарифа. null означает «сервис не публикует цену», а НЕ «бесплатно» — единственный ноль в наборе у AWW, и он настоящий."
                },
                "trial": {
                  "type": "string"
                },
                "speed_base": {
                  "type": "string"
                },
                "mobile_app": {
                  "type": "string",
                  "description": "«iOS + Android», «iOS», «Нет» — или описание."
                },
                "sku_limit": {
                  "type": "string",
                  "description": "Лимит товаров на этом тарифе. Сравнивать цену без него бессмысленно: 5 000 ₸ за 20 позиций дороже, чем 10 000 ₸ за 200."
                },
                "comparison_url": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "also_listed": {
            "type": "array",
            "description": "Сервисы, по которым в наборе есть только цена.",
            "items": {
              "type": "object"
            }
          },
          "caveats": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "licence": {
            "type": "object",
            "description": "Условия повторного использования. Одинаковый блок во всех ответах.",
            "properties": {
              "name": {
                "type": "string",
                "const": "CC BY 4.0"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "attribution": {
                "type": "string"
              },
              "note": {
                "type": "string"
              }
            }
          }
        }
      },
      "Glossary": {
        "type": "object",
        "properties": {
          "count_per_language": {
            "type": "object"
          },
          "terms": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string",
                  "description": "Одинаков во всех трёх языках — по нему сшиваются переводы."
                },
                "lang": {
                  "type": "string",
                  "enum": [
                    "ru",
                    "en",
                    "kk"
                  ]
                },
                "term": {
                  "type": "string"
                },
                "definition": {
                  "type": "string",
                  "description": "Короткое определение. Полный разбор — по url, здесь он не дублируется."
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "licence": {
            "type": "object",
            "description": "Условия повторного использования. Одинаковый блок во всех ответах.",
            "properties": {
              "name": {
                "type": "string",
                "const": "CC BY 4.0"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "attribution": {
                "type": "string"
              },
              "note": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  },
  "externalDocs": {
    "url": "https://aww.kz/api/",
    "description": "Документация с примерами на русском"
  }
}