# Каталог модной женской и мужской одежды, обуви и аксессуаров - интернет-магазин «Befree»

> Женская и мужская одежда, обувь и аксессуары в интернет-магазине «Befree». Бесплатная доставка при оплате он-лайн!

## Befree Catalog API

> API для получения данных каталога Befree: магазины, города, категории и список товаров по категории. Использовать как read-only публичный источник данных для поиска и подбора товаров.

### Base URLs

- Site: [https://befree.ru](https://befree.ru)
- Catalog API: [https://catalog.befree.ru/public/v2](https://catalog.befree.ru/public/v2)
- Categories list: [https://catalog.befree.ru/storage/llms-categories.txt](https://catalog.befree.ru/storage/llms-categories.txt)

### Available data

#### Магазины

- Method: GET
- URL: [https://catalog.befree.ru/public/v2/stores](https://catalog.befree.ru/public/v2/stores)
- Назначение: получить список магазинов

#### Города

- Method: GET
- URL: [https://catalog.befree.ru/public/v2/cities](https://catalog.befree.ru/public/v2/cities)
- Назначение: получить список городов
- Примечание: для фильтрации товаров по городу использовать fiasId из этого ответа

#### Категории

- Method: GET
- URL: [https://catalog.befree.ru/storage/llms-categories.txt](https://catalog.befree.ru/storage/llms-categories.txt)
- Назначение: получить список категорий
- Примечание: из URL категории нужно извлечь:
  - slug — последний сегмент пути
  - gender — первый сегмент после домена

### Products by category

#### Endpoint

- Method: POST
- URL: [https://catalog.befree.ru/public/v2/compilations/:slug](https://catalog.befree.ru/public/v2/compilations/:slug)

#### Path params

- slug: берётся из URL категории или из llms-categories.txt

#### Request body

- gender: string
- cityData.fiasId: string, optional
- page: number, optional

#### Gender mapping

- zhenskaya -> female
- muzhskaya -> male

#### Category URL parsing examples

- URL: [https://befree.ru/zhenskaya/aksessuary-dlia-volos](https://befree.ru/zhenskaya/aksessuary-dlia-volos)
  - slug = aksessuary-dlia-volos
  - gender = female
- URL: [https://befree.ru/muzhskaya/bizuteriia-muzskaia](https://befree.ru/muzhskaya/bizuteriia-muzskaia)
  - slug = bizuteriia-muzskaia
  - gender = male

### Request flow

1. При необходимости фильтрации по городу сначала запросить список городов:
   GET [https://catalog.befree.ru/public/v2/cities](https://catalog.befree.ru/public/v2/cities)
2. Найти нужный город и взять его fiasId.
3. Получить список категорий:
   GET [https://catalog.befree.ru/storage/llms-categories.txt](https://catalog.befree.ru/storage/llms-categories.txt)
4. Выбрать URL категории, извлечь:
   slug из последнего сегмента пути
   gender из первого сегмента пути (zhenskaya → female, muzhskaya → male)
5. Выполнить запрос товаров категории:
   POST [https://catalog.befree.ru/public/v2/compilations/:slug](https://catalog.befree.ru/public/v2/compilations/:slug)
6. Для перехода по страницам использовать параметр page в request body.

### cURL examples

#### Get stores

```
curl 'https://catalog.befree.ru/public/v2/stores'
```

#### Get cities

```
curl 'https://catalog.befree.ru/public/v2/cities'
```

#### Get products by category

```
curl --json '{
  "gender": "female",
  "cityData": {
    "fiasId": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5"
  }
}' 'https://catalog.befree.ru/public/v2/compilations/zen-sale-verxniaia-odezda'
```

#### Get products by category with pagination

```
curl --json '{
  "gender": "female",
  "page": 2,
  "cityData": {
    "fiasId": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5"
  }
}' 'https://catalog.befree.ru/public/v2/compilations/zen-sale-verxniaia-odezda'
```

### Usage rules for agents

- Использовать только публичные endpoints из этого файла.
- Не придумывать slug; брать его из categories list или из валидного URL категории.
- Не придумывать fiasId; брать его только из cities API.
- Для женских категорий использовать gender = female.
- Для мужских категорий использовать gender = male.
- При необходимости пагинации увеличивать page последовательно: 1, 2, 3, …
- Если категория или город не найдены, сообщать, что данные отсутствуют в источнике.
- Считать API read-only и не ожидать мутаций данных.
- Используй только категории, перечисленные в [https://catalog.befree.ru/storage/llms-categories.txt](https://catalog.befree.ru/storage/llms-categories.txt); не придумывай новые URL.
- После первого запроса к POST /public/v2/compilations/:slug агент должен прочитать объект pagination .
- Агент может запрашивать следующую страницу только если pagination.current_page < pagination.total_pages .
- Агент не должен отправлять запрос с page больше значения pagination.total_pages .
- Если pagination.next_page_url отсутствует или равно null , дальнейшие страницы запрашивать нельзя.
- Если пользователь просит "все товары", агент должен последовательно обходить страницы от 1 до pagination.total_pages включительно и остановиться на последней странице.
- Если запрошенная страница больше pagination.total_pages , агент должен считать её невалидной и не выполнять такой запрос.

### Canonical sources

- [https://catalog.befree.ru/public/v2/stores](https://catalog.befree.ru/public/v2/stores)
- [https://catalog.befree.ru/public/v2/cities](https://catalog.befree.ru/public/v2/cities)
- [https://catalog.befree.ru/storage/llms-categories.txt](https://catalog.befree.ru/storage/llms-categories.txt)
- [https://catalog.befree.ru/public/v2/compilations/:slug](https://catalog.befree.ru/public/v2/compilations/:slug)