# Салон красоты и барбершоп

> Связка с системой записи, предоплата, клиент не пришёл, возврат. Путь без кода и путь через API, раздельный учёт по мастерам.

## Коротко

Для салона и барбершопа самый простой путь — **без кода**: администратор заходит в кабинет, выставляет счёт, показывает QR на экране или отправляет ссылку в WhatsApp. Этого достаточно, программист не нужен. Если у вас есть система записи (например, Altegio), её можно подключить через API и выставлять счёт на предоплату автоматически в момент записи. Нужен раздельный учёт по мастерам — либо отдельный API-ключ на мастера, либо поле `metadata`.

## Два пути — какой выбрать

| | Без кода | Через API |
|---|---|---|
| Кто делает | Администратор вручную | Ваша система записи сама |
| Что нужно | Только доступ в кабинет | Программист, сервер |
| Когда подходит | До 30-40 клиентов в день, предоплата редко | Много онлайн-записей, предоплата всегда |
| Время | Один счёт — 20 секунд |  Настраивается один раз |

Большинство салонов остаётся на первом варианте и поступает правильно. Реальная причина перейти на API одна: **брать предоплату при онлайн-записи без участия человека**.

## Схема работы по шагам

Полный порядок при работе с предоплатой:

| Шаг | Кто | Что происходит |
|---|---|---|
| 1 | Клиент | Записывается к мастеру на сайте или в приложении |
| 2 | Система записи | Ставит запись в статус «ждёт оплаты» |
| 3 | Ваш сервер | `POST /api/v1/invoices` — создаёт счёт на сумму предоплаты |
| 4 | Клиент | Открывает ссылку и подтверждает в Kaspi |
| 5 | Qut Pay | Отправляет на ваш адрес событие `invoice.paid` |
| 6 | Ваш сервер | Подтверждает запись, шлёт клиенту уведомление |
| 7 | В салоне | Остаток берёте на месте по QR |

Если клиент не оплатил предоплату за 30 минут, слот можно освободить — это решаете вы, логика на вашей стороне.

## Какой метод API используется

Основной метод один — создание счёта:

```
POST https://api.qut.kz/api/v1/invoices
X-API-Key: qp_live_…
Idempotency-Key: booking-48213-deposit

{
  "amount": 5000,
  "kind": "qr",
  "description": "Стрижка, предоплата",
  "externalOrderId": "booking-48213",
  "customer": { "name": "Айгуль", "phone": "77011234567" },
  "metadata": { "master": "aizhan", "service": "haircut", "bookingId": 48213 }
}
```

В ответе придут `payUrl` (ссылка клиенту), `qrImageUrl` (картинка на экран) и `expiresAt`.

Стройте `Idempotency-Key` из номера записи. Тогда, даже если система записи отправит запрос дважды, второй счёт не создастся — вернётся первый.

Если клиент точно пользуется Kaspi, укажите `"kind": "phone"` и `customer.phone`: счёт придёт прямо в его приложение Kaspi, показывать QR не нужно. Разница подробно: [QR-счёт или счёт по телефону](/kb/ru/qr-vs-phone).

## Вариант без кода — что доступно

Без программиста работает всё это:

- **Счёт вручную из кабинета.** Сумма, описание, телефон клиента — 20 секунд.
- **Постоянная ссылка на оплату.** Сделали один раз ссылку «Предоплата 5 000 ₸» и отправляете её в WhatsApp снова и снова: [Ссылки на оплату](/kb/ru/payment-links).
- **Telegram-бот.** Команда `/invoice` выставляет счёт с телефона, `/today` показывает выручку за день.
- **QR на экране.** На планшете ресепшена открываете QR счёта, клиент сканирует.

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

## Предоплата

Предоплата — единственный реально работающий способ защититься от неявки. Но её нужно правильно выстроить:

- **Сумма небольшая.** Хватает 20-30% от стоимости услуги. Если просить полную сумму вперёд, половина клиентов не запишется.
- **Условие объявлено заранее.** «Не пришли — предоплата не возвращается» или «предупредили за 24 часа — вернём»: любое правило должно быть написано до оплаты.
- **Предоплату вычитайте из остатка.** В салоне берите только остаток. Этот зачёт — в вашей системе, у нас два счёта остаются двумя отдельными платежами.
- **Пишите это в описании.** Поставьте в `description` слово «предоплата» — именно его клиент увидит в Kaspi.

## Клиент не пришёл

Решение за вами:

| Решение | Что делаете |
|---|---|
| Предоплата остаётся | Ничего, деньги на вашем счёте Kaspi |
| Возвращаете полностью | `POST /api/v1/invoices/{id}/refund` или из кабинета |
| Возвращаете половину | Тот же метод с полем `amount` |
| Переносите на следующую запись | Новый счёт не выставляете, засчитываете старый |

## Возврат

Возврат делается и из кабинета, и через API:

```
POST https://api.qut.kz/api/v1/invoices/{id}/refund
{ "amount": 2500, "reason": "предупредил за 24 часа" }
```

Без `amount` вернётся вся сумма. После частичного возврата счёт переходит в статус `partially_refunded`.

Важно: бывает, что ответ по возврату приходит **неопределённым** (`refund_unknown`). Не повторяйте запрос сразу — сначала прочитайте состояние счёта, иначе можно вернуть деньги дважды. Подробнее: [API возвратов](/kb/ru/refunds-api).

## Раздельный учёт по мастерам

Есть два способа:

**1. Через `metadata`.** При создании счёта пишете `metadata: { "master": "aizhan" }`. Поле возвращается в вебхуке и видно в выгрузке. Самый простой вариант, всё остаётся в одной организации.

**2. Отдельный API-ключ на мастера.** Ключ можно ещё и привязать к конкретному кассиру: боевые счета такого ключа идут только через этого кассира. Удобно сети салонов с несколькими точками: [Раздельная отчётность по точкам](/kb/ru/multi-point-reporting).

Месячный и суточный лимиты общие на организацию, между ключами они не делятся.

## На что обратить внимание

- **Номер кассира виден клиенту.** Он указан в уведомлении о счёте. Поэтому это должен быть рабочий номер салона, а не личный номер администратора.
- **Не входите в приложение Kaspi Pay с номера кассира.** Kaspi разрешает одному кассиру только одно активное устройство, вход оборвёт привязку.
- **Окно сканирования QR короткое** — около трёх минут, его задаёт Kaspi. Если клиент раздумывает, создайте новый счёт.
- **Бывают поздние оплаты.** Если деньги пришли после закрытия счёта, событие `invoice.paid` придёт с признаком `late: true`. Окажите услугу или верните деньги.
- **Деньги идут напрямую на ваш счёт Kaspi**, у нас они не задерживаются.

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

**Есть готовый модуль для Altegio?** Нет. Для Altegio, Bitrix24, amoCRM и других систем готового плагина нет, но всё подключается через API — нужен один метод. Общая схема: [Подключить свою CRM](/kb/ru/for-crm).

**А если я продаю абонемент — раз в месяц?** Это подписка. Но подписка означает выставление счёта по расписанию: деньги со счёта покупателя сами не уходят, каждый платёж он подтверждает вручную: [Бизнес по подписке](/kb/ru/for-subscription-business).

**Может ли каждый мастер выставлять счёт со своего телефона?** Да, если пригласить его в кабинет как сотрудника или подключить Telegram-бота. Номер кассира при этом общий, заводить его на каждого мастера не нужно.

**Если клиент не оплатил предоплату, счёт зависнет?** Счёт перейдёт в `expired`. От вас ничего не требуется, но он попадёт в месячный лимит.

**В салоне стоит касса, как это совместить?** Фискальную сторону смотрите отдельно: [Фискальный чек](/kb/ru/fiscal-receipt).