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

Қысқаша

Форма-хук — ұйымыңызға берілетін жеке адрес. Формаңыз деректерді сол адреске жібергенде, 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 КБ-тан аспауы керек.

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

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

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

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

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

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

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

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

Redirect режимі

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

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

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

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

Бағыттау. Хук параметрлерінде Redirect қосулы болса (немесе адреске ?redirect=1 қоссаңыз), жауаптың орнына 302 келеді және браузер клиентті бірден төлем бетіне апарады. Кәдімгі 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" белгісі сақталады — есепте қай форманың счёты екенін содан ажыратасыз.

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

Соңғы қате хук карточкасында да көрінеді — форманы баптағанда сонда қарау ең жылдам жол. Толық тізім: Қателер каталогы.

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

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

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

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

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

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

Бұл жол программист керек етпей ме? Керек етпейді. Кодсыз бастаудың басқа да жолдары бар: Әзірлеуші жоқ — қалай бастау керек.