API документация каталога

Эта страница предназначена для программиста, интегратора, AI-сервиса, маркетплейса, ERP/CRM или внешней системы, которая хочет читать каталог сайта программно через HTTP API.

Базовый сайт: https://price.ashybulakstroy.kz

1. Основные ссылки

URL	Назначение
/api	Эта человеко-понятная документация
/docs	Swagger UI / интерактивное тестирование
/openapi.json	Машинно-читаемая OpenAPI-схема
/llms.txt	AI-friendly карта API и sitemap
/sitemap.xml	Главный sitemap index

2. Endpoint: поиск

GET /api/search

Используется для поиска товара по текстовому запросу, SKU, названию, ключевым словам.

Параметр	Тип	Описание
`q`	string	Поисковая строка
`limit`	integer	Ограничение числа результатов
`instock`	0/1	Только товары в наличии
`prefix`	0/1	Префиксный режим, если поддержан в проекте

https://price.ashybulakstroy.kz/api/search?q=бетон&limit=5

3. Endpoint: карточка товара

GET /api/item/{sku}

Возвращает подробную карточку товара по SKU.

https://price.ashybulakstroy.kz/api/item/998528

4. Endpoint: каталог постранично

GET /api/catalog

Этот endpoint возвращает список товаров каталога постранично. Он нужен для синхронизации каталога, выгрузки в партнёрские системы, индексации AI-агентами и безопасной загрузки больших объёмов данных.

Параметр	Тип	Описание
`page`	integer	Номер страницы, начиная с 1
`limit`	integer	Размер страницы
`instock`	0/1	Только товары в наличии
`order_by`	string	Колонка сортировки, если она есть в таблице

https://price.ashybulakstroy.kz/api/catalog?page=1&limit=100

Пример ответа

{
  "page": 1,
  "limit": 100,
  "total": 20000,
  "total_pages": 200,
  "has_prev": false,
  "has_next": true,
  "items": [
    {
      "sku": "998528",
      "name": "Перфоратор SDS Plus 800W",
      "price": 32500,
      "stock": 7,
      "in_stock": true,
      "currency": "KZT",
      "url": "/item/998528"
    }
  ]
}

5. Для чего нужен /api/catalog

полная синхронизация каталога внешней системой;
выгрузка большого каталога без перегрузки сервера;
AI-indexing / crawling;
обновление цен, остатков и карточек по страницам.

6. SEO и AI файлы

Файл	Роль
`/robots.txt`	Правила обхода сайта роботами
`/sitemap.xml`	Индекс sitemap-файлов
`/sitemap-products.xml`	Индекс sitemap-файлов товаров
`/sitemap-catalog.xml`	Страницы каталога API
`/sitemap-categories.xml`	Страницы категорий, если категории есть
`/llms.txt`	Сводка для AI и LLM-агентов

Для стабильных интеграций желательно в будущем перейти на версионирование, например: /api/v1/search, /api/v1/item/{sku}, /api/v1/catalog.

7. Пример на Python

import requests

r = requests.get(
    "https://price.ashybulakstroy.kz/api/catalog",
    params={"page": 1, "limit": 100},
    timeout=30,
)
r.raise_for_status()
data = r.json()
print(data["items"][:3])

8. Пример на JavaScript

const res = await fetch("https://price.ashybulakstroy.kz/api/catalog?page=1&limit=100");
const data = await res.json();
console.log(data.items);