n8n автоматтандыру: Qut Pay-ді дайын workflow-тармен қосу

Қысқаша

n8n үшін екі дайын workflow бар: біреуі счёт жасайды, екіншісі Qut Pay жіберген оқиғаларды қабылдап, қолтаңбасын тексереді. Екеуі де тек стандартты түйіндерден (Webhook, Set, HTTP Request, Code, IF, Respond to Webhook) құралған — n8n-ге ешқандай қосымша пакет орнатудың қажеті жоқ.

Жүктеу: api.qut.kz/downloads/qutpay-n8n.zip. Кабинетте де бар: Интеграциялар → жүктеулер тізімі.

Керегі: n8n 1.x (self-hosted немесе Cloud), Qut Pay API кілті және webhook құпиясы.

Екі workflow

Импорттау: n8n → Workflows → Add workflow → ⋯ → Import from File → JSON файлды таңдау. Екі файл үшін екі рет қайталаңыз. Импорттан кейін workflow-лар белсенді емес — алдымен credential мен құпияны баптап, содан кейін Active қосқышын қосыңыз.

1. API кілтке credential

Кілтті кабинеттен аласыз: Интеграциялар → API кілттер → жасау. Сынау үшін sandbox кілтін (qp_test_…), продакшен үшін qp_live_… алыңыз.

n8n → Credentials → Add credential → Header Auth:

Сосын «Qut Pay — создать счёт» workflow-ын ашып, «Qut Pay: создать счёт» түйінінде Credential for Header Auth өрісінен жаңа credential-ды таңдаңыз. Таңдалмаса түйін қызылмен көрінеді.

Кілт n8n ішінде қалуы керек. Оны браузерде орындалатын кодқа немесе форманың өзіне салмаңыз.

2. Webhook құпиясы

Құпия кабинетте webhook адресін қосқанда бір рет көрсетіледі. «Проверка подписи» түйіні оны мына ретпен іздейді:

1. QUTPAY_WEBHOOK_SECRET орта айнымалысы ($env) — self-hosted үшін;
2. n8n Variables ішіндегі QUTPAY_WEBHOOK_SECRET ($vars) — Cloud үшін немесе $env жабық болса.

Self-hosted n8n-нің .env файлында:

QUTPAY_WEBHOOK_SECRET=whsec_…
N8N_BLOCK_ENV_ACCESS_IN_NODE=false
NODE_FUNCTION_ALLOW_BUILTIN=crypto

Өзгерткен соң n8n-ді қайта іске қосыңыз. n8n Cloud-та crypto әуел бастан рұқсат етілген, құпияны Settings → Variables арқылы қоясыз.

3. Адресті кабинетке тіркеу

1. «Qut Pay — приём webhook» workflow-ын Active етіңіз.
2. «Webhook: события Qut Pay» түйінін ашып, Production URL-ды көшіріңіз: мысалы https://n8n.example.kz/webhook/qutpay-events.
3. Кабинет → Интеграциялар → webhook адресін қосу → адресті қойыңыз → құпияны сақтап алыңыз.
4. Кабинеттегі «тест оқиғасын жіберу» батырмасы webhook.test жібереді. n8n-де ол қолтаңба тексерісінен өтіп, «Другие события» тармағына түседі, жауабы 200 болады.

Test URL (/webhook-test/…) тек «Listen for test event» батырмасы басылып тұрғанда жұмыс істейді — кабинетке ол жарамайды, тек Production URL.

Продакшенде адрес https және нақты доменмен болуы керек: IP мен уақытша туннель адрестері қабылданбайды.

Қолтаңбаны тексеру

«Проверка подписи» түйіні сіз үшін мынаны істейді:

• X-Webhook-Signature = sha256= + HMAC-SHA256(құпия, timestamp + "." + rawBody), hex;
• X-Webhook-Timestamp — unix секунд, ±300 секунд шегі (қайталау шабуылынан қорғаныс);
• салыстыру тұрақты уақытта жүреді;
• сәйкес келмесе — 401, Qut Pay жеткізуді қайталайды.

Ең маңызды бір нәрсе: Webhook түйінінде Options → Raw Body қосулы болуы керек. Қолтаңба дененің өзгертілмеген байттары бойынша есептеледі, JSON-ға айналдырылған нұсқа бойынша емес. Толығы: Webhook қолтаңбасы сәйкес келмейді.

Сценарий: форма → счёт → төлем → хабарлама

Ең жиі құрылатын тізбек:

1. Сайттағы форма (Tilda, өз формаңыз, CRM) POST /webhook/qutpay-order адресіне сома мен клиент деректерін жібереді.
2. «Поля счёта» түйіні өрістерді оқиды: amount, description, externalOrderId, customer.name/phone/email, successUrl, failUrl, metadata. Бұл өрістердің атаулары сіздің формаңызда басқаша болса, өрнектерді өзгертесіз.
3. «Qut Pay: создать счёт» түйіні POST https://api.qut.kz/api/v1/invoices шақырады және Idempotency-Key тақырыбын жібереді (әдепкі мәні n8n-<externalOrderId>). Сол тапсырыс нөмірімен қайта жіберілсе жаңа счёт жасалмай, бұрынғысы қайтады.
4. Жауап клиентке payUrl беріп қайтады — клиентті сол бетке жіберіңіз.
5. Клиент төлегенде Qut Pay invoice.paid оқиғасын екінші workflow-ға жібереді, ол «Оплачено: ваше действие» тармағын орындайды.

«Оплачено: ваше действие» — бос NoOp түйін, оны өз әрекетіңізбен ауыстырасыз: Google Sheets жолын қосу, хат жіберу, CRM-ге HTTP сұрау, 1С-ке жазу, Telegram хабарламасы (мысал-үлгі бар, өшірулі тұр). Тармақта $json.externalOrderId, $json.amount, $json.invoice.receiptUrl, $json.invoice.paidAt, $json.late қолжетімді.

Телефонға счёт жіберу үшін («Qut Pay: создать счёт» түйінінің JSON денесінде) kind: "phone" қосыңыз. Бұл жағдайда customer.phone міндетті, ал сома бүтін теңге болуы керек.

Қайталанатын оқиғалар

Бір оқиға екі рет келуі мүмкін: 2xx емес жауап берсеңіз, жеткізу 11 рет қайталанады. Сондықтан өңдеуіңіз идемпотентті болсын — дедупликация кілті (invoice.id, status) жұбы.

Төлем expired немесе cancelled болғаннан кейін де келуі мүмкін: ондай оқиғада late: true болады. Тауарды беріңіз немесе ақшаны қайтарыңыз.

Sandbox-та тексеру

Ұйымды sandbox режиміне ауыстырып, qp_test_… кілтін қолданыңыз. Счёт жасаңыз, сосын төлемді симуляциялаңыз:

curl -X POST https://api.qut.kz/api/v1/invoices/inv_…/simulate \
  -H 'X-API-Key: qp_test_…' -H 'Content-Type: application/json' \
  -d '{"status": "paid"}'

Бірнеше секундтан кейін invoice.paid сіздің n8n-ге келеді — «Qut Pay — приём webhook» workflow-ының Executions бөлімінен тексеріңіз. Curl-сыз да болады: payUrl бетін ашып, sandbox төлеу батырмасын басыңыз. Толығы: Sandbox-та төлемді симуляциялау.

Жиі кездесетін мәселелер

Webhook мүлде келмей жатса, себебі көбіне қолтаңбада емес: Webhook келмей жатыр.

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

n8n Cloud-та жұмыс істей ме? Иә. Екі workflow та тек стандартты түйіндерді қолданады. Құпияны Settings → Variables арқылы қоясыз.

Өз n8n түйінім (community node) керек пе? Жоқ. HTTP Request түйіні API-мен тікелей жұмыс істейді, бөлек түйін орнатудың қажеті жоқ.

Бір n8n-ге бірнеше ұйымды қосуға бола ма? Болады, бірақ әр ұйымның өз кілті мен өз webhook құпиясы бар. Әр ұйымға бөлек credential пен бөлек workflow (немесе бөлек адрес) жасаған дұрыс.

Жауаптағы payUrl-ды клиентке қалай жеткізем? Форманы жіберген беттен сол адреске бағыттаңыз. Форма-хук арқылы бірден бағыттайтын дайын жол да бар: Tilda және кез келген форма.

Қате кодын қайдан қараймын? Қателер каталогы бетінде барлық код топтап берілген.