# Tilda және кез келген форма: кодсыз төлем қабылдау

> Форма-хук — формаңызды Qut Pay адресіне бағыттасаңыз, жіберілген сәтте счёт жасалады. Өрістерді сәйкестендіру, redirect режимі, кабинетте баптау және хукты тоқтату.

## Қысқаша

**Форма-хук** — ұйымыңызға берілетін жеке адрес. Формаңыз деректерді сол адреске жібергенде, Qut Pay сол сәтте счёт жасайды. Кодтың бір жолын да жазудың қажеті жоқ: Tilda-да «Webhook» қабылдағышының адресін көрсетесіз, кәдімгі HTML формада `action` атрибутына жазасыз.

Адрес мына түрде болады: `https://api.qut.kz/hooks/form/<токен>`. Оны кабинеттен аласыз: **Интеграциялар** → форма-хуктар → жаңасын жасау.

Жауапта төлем бетінің сілтемесі қайтады. **Redirect режимін** қоссаңыз, клиент форманы жібергеннен кейін бірден төлем бетіне түседі.

## Қалай баптау керек

1. Кабинет → **Интеграциялар** → форма-хук жасаңыз, атау беріңіз (2-60 таңба).
2. Хуктың адресін көшіріңіз.
3. Tilda-да: форманың параметрлерінде «Webhook» қабылдағышын қосып, сол адресті қойыңыз. Кәдімгі HTML формада: `<form method="post" action="https://api.qut.kz/hooks/form/…">`.
4. Форманы бір рет жіберіп көріңіз. Кабинеттегі хук карточкасында келген сұраулардың саны, жасалған счёттардың саны және соңғы қате көрінеді.

Бір ұйымға **20-ға дейін** хук жасауға болады. Әр беттің, әр тауардың, әр науқанның өз хугі болғаны ыңғайлы — сонда есеп те бөлек көрінеді.

Хук `application/json` де, кәдімгі форманың `application/x-www-form-urlencoded` пішімін де қабылдайды. Сұраудың денесі 32 КБ-тан аспауы керек.

## Өрістерді сәйкестендіру

Өріс атауларын қолмен теңестірудің қажеті жоқ — хук ең жиі кездесетін атауларды өзі таниды. Регистрдің маңызы жоқ.

| Не | Қабылданатын атаулар |
|---|---|
| Сома | `amount`, `sum`, `summa`, `price`, `total`, `paymentsum`, `payment.amount`, `сумма` |
| Телефон | `phone`, `tel`, `telephone`, `mobile`, `whatsapp`, `телефон` |
| Email | `email`, `e-mail`, `mail`, `почта` |
| Аты | `name`, `fio`, `fullname`, `имя`, `аты` |
| Сипаттама | `description`, `comment`, `product`, `service`, `tariff`, `plan`, `сипаттама`, `товар`, `услуга` |
| Тапсырыс нөмірі | `orderid`, `order_id`, `externalorderid`, `payment.orderid`, `tranid`, `formid` |

Tilda-ның кірістірілген құрылымдары да танылады: `payment[amount]` сияқты өрістер бір деңгей төмен жазылады, ал `products` тізімі берілсе, оның жалпы сомасы (`бағасы × саны`) есептеліп, сома ретінде алынады.

**Сома табылмаса**, хук `invalid_amount` қатесін қайтарады: «Сома өрісі табылмады». Ондай жағдайда формадағы өрістің атын жоғарыдағы тізімнен біреуіне ауыстырыңыз немесе хук параметрлерінде тұрақты сома қойыңыз.

Телефон `7XXXXXXXXXX` пішіміне өзі келтіріледі — клиент оны қалай жазса да (сызықшамен, жақшамен, 8-ден бастап) жарайды.

## Хуктың әдепкі параметрлері

Хук карточкасында бірнеше әдепкі мән қоюға болады:

| Параметр | Не істейді |
|---|---|
| Сома | Тұрақты сома. Қойылса, формадағы сома еленбейді — бір бағалы тауар мен жазылу үшін ыңғайлы |
| Сипаттама | Клиент көретін мәтін. Формада сипаттама болмаса қолданылады. 60 таңбаға дейін |
| Счёт түрі | `qr` — QR және төлем беті; `phone` — счёт клиенттің Kaspi қосымшасына кетеді |
| successUrl | Төлемнен кейін клиент түсетін бет. Тек http(s) |
| Redirect | Қосулы болса, жауап орнына клиент бірден төлем бетіне бағытталады |

`phone` түрін таңдасаңыз, формада телефон өрісі міндетті болуы керек және сома бүтін теңгеге дөңгелектенеді. Телефон келмесе, хук әдеттегі QR счётын жасайды.

## Redirect режимі

Екі жұмыс тәсілі бар.

**Жауап беру (әдепкі).** Хук HTTP 201 және JSON қайтарады:

```json
{ "ok": true, "invoiceId": "inv_…", "status": "pending",
  "payUrl": "https://api.qut.kz/pay/inv_…", "expiresAt": "…" }
```

Бұл Tilda-ның webhook қабылдағышына, n8n-ге, өз серверіңізге жарайды: `payUrl`-ды алып, клиентті сол жаққа жібересіз.

**Бағыттау.** Хук параметрлерінде Redirect қосулы болса (немесе адреске `?redirect=1` қоссаңыз), жауаптың орнына 302 келеді және браузер клиентті бірден төлем бетіне апарады. Кәдімгі HTML форма үшін ең қарапайым жол:

```html
<form method="post" action="https://api.qut.kz/hooks/form/ТОКЕН?redirect=1">
  <input name="amount" value="5000" type="hidden">
  <input name="name" placeholder="Атыңыз">
  <input name="phone" placeholder="Телефон">
  <button type="submit">Төлеу</button>
</form>
```

Tilda-ның өз «webhook» механизмі формадан кейін бетті ауыстырмайды, сондықтан онда redirect емес, жауаптағы `payUrl` қолданылады — немесе форманы тікелей хук адресіне жіберетін кәдімгі блок қолданылады.

## Tilda-ның тексеру сұрауы

Tilda webhook адресін сақтарда `test` белгісі бар бос сұрау жібереді. Хук оны танып, `{ "ok": true, "test": true }` деп жауап береді және счёт жасамайды. Яғни Tilda-дағы «Проверить» батырмасы қалыпты өтеді, ал кабинетте артық счёт пайда болмайды.

## Хукты тоқтату және токенді ауыстыру

Хук адресі құпия емес, бірақ ол ашық тұр: адресті білген кез келген адам счёт жасай алады. Сондықтан:

- **Тоқтату.** Хук карточкасында күйін «тоқтатылған» етіңіз. Содан кейін сұраулар `hook_paused` (HTTP 410) қатесін алады, счёт жасалмайды. Науқан біткенде немесе бетті жапқанда осылай істеңіз.
- **Токенді ауыстыру.** Адрес бөтен адамға тиіп кетсе, токенді жаңартыңыз. Ескі адрес сол сәтте істемей қалады — формадағы адресті жаңартуды ұмытпаңыз.
- **Жою.** Хук мүлде керек болмаса, жойыңыз.

Хук арқылы жасалған счёттарда `metadata` ішінде хуктың идентификаторы және `source: "form"` белгісі сақталады — есепте қай форманың счёты екенін содан ажыратасыз.

## Қателерді қалай оқу керек

| Қате | HTTP | Не болды |
|---|---|---|
| `hook_not_found` | 404 | Адрес қате немесе токен ауысқан |
| `hook_paused` | 410 | Хук тоқтатылған, кабинеттен қайта қосыңыз |
| `invalid_amount` | 422 | Сома өрісі табылмады немесе сан емес |
| `invalid_phone` | 422 | Телефон пішімі дұрыс емес |
| `tariff_limit_reached` | 429 | Айлық счёт лимиті бітті |

Соңғы қате хук карточкасында да көрінеді — форманы баптағанда сонда қарау ең жылдам жол. Толық тізім: [Қателер каталогы](/kb/error-catalog).

## Жиі қойылатын сұрақтар

**Сайт Tilda-да емес, басқа конструкторда. Жарай ма?** Иә. Форма POST сұрау жібере алса — Webflow, WordPress формасы, қолмен жазылған HTML, Google Forms-тан кейінгі автоматтандыру — бәрі жарайды.

**Форма жіберілді, бірақ счёт жоқ.** Хук карточкасындағы «соңғы қате» жолын қараңыз. Ең жиі себебі — сома өрісінің аты танылмауы немесе форманың бос сома жіберуі.

**Клиент төлегенін қалай білемін?** Хабарламаны кабинеттен, Telegram боттан немесе webhook арқылы аласыз. Автоматтандыру керек болса, оқиғаларды n8n-ге жіберіңіз: [n8n автоматтандыру](/kb/n8n).

**Бір форма бірнеше тауарға жарай ма?** Иә: сипаттама өрісін формадан алдырыңыз, сома да формадан келсін. Сонда бір хук барлық позицияны өңдейді.

**Сома клиенттің өз қолымен енгізілуі керек. Бола ма?** Болады — форманың сома өрісін ашық қалдырыңыз, хук параметрлерінде тұрақты сома қоймаңыз.

**Бұл жол программист керек етпей ме?** Керек етпейді. Кодсыз бастаудың басқа да жолдары бар: [Әзірлеуші жоқ — қалай бастау керек](/kb/no-developer).