> For the complete documentation index, see [llms.txt](https://docs.fstrk.io/knowledge_base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fstrk.io/knowledge_base/api/obshaya-informaciya/promokody.md).

# Промокоды

#### GET /api/partners/promocode-groups/

🔒 *bot-key или OAuth*

**Кратко:** Получить список групп промокодов.

**Параметры запроса:**

* `limit` (integer, опциональный), `offset` (integer, опциональный) — используется для пагинации

**Возвращает:** `200 OK` — постраничный список объектов `PromocodeGroup`: `uuid`, `name`.

<details>

<summary>Пример ответа:</summary>

{% code overflow="wrap" %}

```json
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string"
    }
  ]
}
```

{% endcode %}

</details>

**Ошибки:** 401 — ошибка авторизации.

**Пример запроса:**

bash

```bash
curl -X GET "https://dashboard.fstrk.io/api/partners/promocode-groups/?limit=50" \
  -H "bot-key: your_bot_key"
```

***

#### POST /api/partners/promocode-groups/

🔒 *bot-key или OAuth*

**Кратко:** Создать новую группу промокодов.

**Тело запроса:**

* `name` (string, обязательный) — название группы (максимум 1024 символа)

**Возвращает:** `201 Created` — объект `PromocodeGroup`.

**Ошибки:** 400 — некорректные данные; 401 — ошибка авторизации.

**Пример запроса:**

bash

```bash
curl -X POST https://dashboard.fstrk.io/api/partners/promocode-groups/ \
  -H "Content-Type: application/json" \
  -H "bot-key: your_bot_key" \
  -d '{
    "name": "Летняя акция 2026"
  }'
```

***

#### GET /api/partners/promocode-groups/{uuid}/

🔒 *bot-key или OAuth*

**Кратко:** Получить информацию о группе промокодов по UUID.

**Параметры пути:**

* `uuid` (string, обязательный) — UUID группы

**Возвращает:** `200 OK` — объект `PromocodeGroup`.

<details>

<summary>Пример ответа:</summary>

{% code overflow="wrap" %}

```json
{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string"
}
```

{% endcode %}

</details>

**Ошибки:** 401 — ошибка авторизации; 404 — группа не найдена.

**Пример запроса:**

bash

```bash
curl -X GET https://dashboard.fstrk.io/api/partners/promocode-groups/550e8400-e29b-41d4-a716-446655440000/ \
  -H "bot-key: your_bot_key"
```

***

#### PATCH /api/partners/promocode-groups/{uuid}/

🔒 *bot-key или OAuth*

**Кратко:** Отредактировать название группы промокодов.

**Параметры пути:**

* `uuid` (string, обязательный) — UUID группы

**Тело запроса:**

* `name` (string, опциональный) — новое название

**Возвращает:** `200 OK` — обновлённый объект `PromocodeGroup`.

<details>

<summary>Пример ответа:</summary>

{% code overflow="wrap" %}

```json
{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string"
}
```

{% endcode %}

</details>

**Ошибки:** 400 — некорректные данные; 401 — ошибка авторизации; 404 — группа не найдена.

**Пример запроса:**

bash

```bash
curl -X PATCH https://dashboard.fstrk.io/api/partners/promocode-groups/550e8400-e29b-41d4-a716-446655440000/ \
  -H "Content-Type: application/json" \
  -H "bot-key: your_bot_key" \
  -d '{
    "name": "Осенняя акция 2026"
  }'
```

***

#### DELETE /api/partners/promocode-groups/{uuid}/

🔒 *bot-key или OAuth*

**Кратко:** Удалить группу промокодов.

**Параметры пути:**

* `uuid` (string, обязательный) — UUID группы

**Возвращает:** `204`.

**Ошибки:** 401 — ошибка авторизации; 404 — группа не найдена.

**Пример запроса:**

bash

```bash
curl -X DELETE https://dashboard.fstrk.io/api/partners/promocode-groups/550e8400-e29b-41d4-a716-446655440000/ \
  -H "bot-key: your_bot_key"
```

***

#### GET /api/partners/promocodes/

🔒 *bot-key или OAuth*

**Кратко:** Получить список промокодов.

**Параметры запроса:**

* `limit` (integer, опциональный), `offset` (integer, опциональный)

**Возвращает:** `200 OK` — постраничный список объектов `PromocodeGet`.

**Ошибки:** 401 — ошибка авторизации.

**Пример запроса:**

bash

```bash
curl -X GET "https://dashboard.fstrk.io/api/partners/promocodes/?limit=100" \
  -H "bot-key: your_bot_key"
```

***

#### POST /api/partners/promocodes/

🔒 *bot-key или OAuth*

**Кратко:** Создать промокод вручную.

**Тело запроса:**

* `code` (string, обязательный) — код промокода (максимум 1024 символа)
* `group` (uuid, обязательный) — UUID группы промокодов
* `issued_chat` (uuid, опциональный) — UUID чата, которому выдаётся промокод
* `expires_at` (string, date-time, опциональный) — дата и время истечения

**Возвращает:** `201 Created` — объект `PromocodeCreatePatch`.

**Ошибки:** 400 — некорректные данные; 401 — ошибка авторизации.

**Пример запроса:**

bash

```bash
curl -X POST https://dashboard.fstrk.io/api/partners/promocodes/ \
  -H "Content-Type: application/json" \
  -H "bot-key: your_bot_key" \
  -d '{
    "code": "SUMMER2024",
    "group": "550e8400-e29b-41d4-a716-446655440000",
    "expires_at": "2024-09-01T00:00:00Z"
  }'
```

***

#### GET /api/partners/promocodes/{uuid}/

🔒 *bot-key или OAuth*

**Кратко:** Получить информацию о промокоде по UUID.

**Параметры пути:**

* `uuid` (string, обязательный) — UUID промокода

**Возвращает:** `200 OK` — объект `PromocodeGet`: `uuid`, `code`, `status` (`AVAILABLE` или `ISSUED`), `group`, `issued_chat`, `issued_at`, `expires_at`, `created_at`, `updated_at`.

**Ошибки:** 401 — ошибка авторизации; 404 — промокод не найден.

**Пример запроса:**

bash

```bash
curl -X GET https://dashboard.fstrk.io/api/partners/promocodes/550e8400-e29b-41d4-a716-446655440000/ \
  -H "bot-key: your_bot_key"
```

***

#### PATCH /api/partners/promocodes/{uuid}/

🔒 *bot-key или OAuth*

**Кратко:** Частично обновить промокод.

**Параметры пути:**

* `uuid` (string, обязательный) — UUID промокода

**Тело запроса (все поля опциональны):**

* `code` (string), `status` (`AVAILABLE` или `ISSUED`), `group` (object), `issued_chat` (object), `issued_at` (string, date-time), `expires_at` (string, date-time)

**Возвращает:** `200 OK` — обновлённый объект `PromocodeGet`.

**Ошибки:** 400 — некорректные данные; 401 — ошибка авторизации; 404 — промокод не найден.

**Пример запроса:**

bash

```bash
# Пометить промокод как выданный
curl -X PATCH https://dashboard.fstrk.io/api/partners/promocodes/550e8400-e29b-41d4-a716-446655440000/ \
  -H "Content-Type: application/json" \
  -H "bot-key: your_bot_key" \
  -d '{
    "status": "ISSUED",
    "issued_at": "2024-09-05T10:00:00Z"
  }'
```

***

#### DELETE /api/partners/promocodes/{uuid}/

🔒 *bot-key или OAuth*

**Кратко:** Удалить промокод.

**Параметры пути:**

* `uuid` (string, обязательный) — UUID промокода

**Возвращает:** `204 No Content`.

**Ошибки:** 401 — ошибка авторизации; 404 — промокод не найден.

**Пример запроса:**

bash

```bash
curl -X DELETE https://localhost:8080/api/partners/promocodes/550e8400-e29b-41d4-a716-446655440000/ \
  -H "bot-key: your_bot_key"
```

***

#### POST /api/partners/promocodes/generate/

🔒 *bot-key или OAuth*

**Кратко:** Автоматически сгенерировать промокод с заданными параметрами.

**Тело запроса:**

* `group` (uuid, обязательный) — UUID группы
* `chars_count` (integer, опциональный) — количество символов без префикса (5–10, по умолчанию 10)
* `is_add_integers` (boolean, опциональный) — добавлять цифры (по умолчанию `false`)
* `prefix` (string, опциональный) — префикс промокода
* `expires_at` (string, date-time, опциональный) — дата истечения

**Возвращает:** `200 OK`:

* `code` (string) — сгенерированный код

**Ошибки:** 400 — некорректные параметры; 401 — ошибка авторизации.

**Пример запроса:**

bash

```bash
curl -X POST https://localhost:8080/api/partners/promocodes/generate/ \
  -H "Content-Type: application/json" \
  -H "bot-key: your_bot_key" \
  -d '{
    "group": "550e8400-e29b-41d4-a716-446655440000",
    "chars_count": 8,
    "is_add_integers": true,
    "prefix": "FALL-",
    "expires_at": "2024-12-31T23:59:59Z"
  }'
```