# Как создать первый счёт

> Два способа: вручную из кабинета за два поля или одним запросом к API. Первый счёт разумно сделать в песочнице и там же симулировать оплату.

## Коротко

Счёт создаётся двумя способами. **Вручную из кабинета**: в разделе [Счета](https://qut.kz/app/invoices/) указываете сумму и нажимаете **Создать счёт** — сразу появляются QR и ссылка на оплату. **Через API**: отправляете `POST https://api.qut.kz/api/v1/invoices`. Первый раз делайте это в режиме песочницы: настоящие деньги не двигаются, а оплату можно симулировать самому.

## Сначала песочница

Вверху кабинета стоит отметка режима: **SANDBOX** или **LIVE**. Первый счёт лучше создать в режиме SANDBOX:

- Kaspi не вызывается, подключать кассира не нужно
- Настоящие деньги не двигаются, никому ничего не уходит
- Счёт не считается в лимиты и не запускает [пробный период](/kb/ru/trial-period)
- Оплату можно симулировать самостоятельно

Как только вы создадите первый счёт в боевом режиме, начнётся отсчёт 7 дней пробного периода — поэтому переключайтесь, когда будете готовы.

## Способ 1: вручную из кабинета

1. Откройте раздел [Счета](https://qut.kz/app/invoices/)
2. Выберите тип счёта: **QR / ссылка** или **Счёт на телефон (приложение Kaspi)**
3. Впишите сумму в тенге
4. При желании заполните описание («Описание (60 символов)») и номер заказа («№ заказа (необязательно)»)
5. Для счёта на телефон укажите номер клиента в формате `7XXXXXXXXXX`
6. Нажмите **Создать счёт**

Готово. В списке появится новая строка, а по ссылке **Страница оплаты** можно открыть то, что увидит покупатель. Ссылку отправляют в WhatsApp, Telegram, директ — куда угодно.

В режиме песочницы рядом со счётом есть кнопка **[Sandbox] оплачен** — нажмёте, и счёт будет помечен как оплаченный, а webhook уйдут так же, как в бою.

Этот способ работает без кода: [Нет программиста — как начать](/kb/ru/no-developer).

## Способ 2: через API

Сначала в разделе [Интеграции](https://qut.kz/app/integrations/) в блоке **API-ключи** создайте ключ. Ключ **показывается один раз** — скопируйте его сразу. В режиме песочницы ключ начинается с `qp_test_…`.

```bash
curl -X POST https://api.qut.kz/api/v1/invoices \
  -H "X-API-Key: qp_test_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{
    "amount": 2500,
    "kind": "qr",
    "description": "Заказ №1001",
    "externalOrderId": "1001",
    "customer": { "name": "Асан", "phone": "77010000000" }
  }'
```

В ответе придёт 201 и в нём:

| Поле | Зачем |
|---|---|
| `id` | Идентификатор счёта, нужен для запроса статуса |
| `status` | Начальный статус |
| `payUrl` | Страница оплаты, её отправляют покупателю |
| `qrUrl`, `qrImageUrl`, `deepLink` | QR и ссылка, открывающая приложение Kaspi |
| `expiresAt` | До какого момента счёт действителен |

Покупателю достаточно дать `payUrl` — на этой странице есть и QR, и кнопка перехода в Kaspi.

Заголовок `Idempotency-Key` лучше делать уникальным для каждого счёта (подойдёт номер заказа). Если запрос с тем же ключом повторится, новый счёт не создастся — вернётся прежний.

Симуляция оплаты в песочнице: `POST /api/v1/invoices/{id}/simulate` с телом `{ "status": "paid" }`.

Полная документация: https://api.qut.kz/docs

## Где посмотреть результат

- **Кабинет → Счета** — список, фильтры, поиск, статус каждого счёта
- **Кабинет → Обзор** — последние счета и выручка за сегодня
- `GET /api/v1/invoices/{id}` — сам счёт, его события и возвраты
- Webhook — уведомление приходит на ваш адрес в момент смены статуса
- Telegram-бот — команды `/last` и `/today`

Что где лежит в кабинете: [Что где находится в кабинете](/kb/ru/cabinet-tour).

## Если первый счёт не создаётся

| Признак | Причина |
|---|---|
| API отвечает 401 | Ключа нет, он указан неверно или не задан заголовок `X-API-Key` |
| API отвечает 403 | У ключа не хватает прав либо тариф неактивен |
| В боевом режиме счёт не создаётся | Кассир Kaspi не подключён или привязка оборвалась |
| Пишет, что ключ недействителен | Ключ не соответствует режиму: ключом песочницы работаете в боевом |
| Сумма не принимается | В QR-счёте максимум 2 знака после запятой, в счёте на телефон — целые тенге |

## Вопросы и ответы

**Нужен ли кассир, чтобы создать счёт?** В песочнице — нет. В боевом режиме — да, кассир Kaspi должен быть подключён.

**Сколько живёт QR?** Окно сканирования у Kaspi около трёх минут, точное время смотрите в поле `expiresAt` ответа. Если время вышло, создайте новый счёт.

**А если у покупателя нет приложения Kaspi?** Счёт на телефон до него не дойдёт — дайте QR или ссылку `payUrl`.

**Счета из песочницы переедут в боевой режим?** Нет. Режимы раздельные, тестовые счета остаются в песочнице.

**Можно создать несколько счетов одним запросом?** Да, `POST /api/v1/invoices/bulk` принимает от 1 до 100 счетов за раз. В кабинете это кнопка **Массово (CSV)**.