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

> n8n үшін екі дайын workflow: счёт жасау және webhook қабылдау. Импорттау, credential, webhook құпиясы, қолтаңбаны тексеру және «форма → счёт → төлем → хабарлама» сценарийі.

## Қысқаша

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

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

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

## Екі workflow

| Файл | Не істейді |
|---|---|
| `qutpay-create-invoice.json` | `POST /webhook/qutpay-order` келеді → Qut Pay-де счёт жасайды → `{ id, payUrl, qrUrl, deepLink, expiresAt }` қайтарады |
| `qutpay-webhook-receiver.json` | `POST /webhook/qutpay-events` ← Qut Pay оқиғалары; HMAC қолтаңбаны тексереді, `invoice.paid` бойынша тармақталады, 200 қайтарады |

Импорттау: 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**:

| Өріс | Мәні |
|---|---|
| Credential name | `Qut Pay API key` — дәл осылай, түйін осы атауға сілтейді |
| Name | `X-API-Key` |
| Value | `qp_live_…` немесе `qp_test_…` |

Сосын «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 қолтаңбасы сәйкес келмейді](/kb/webhook-signature-mismatch).

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

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

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_…` кілтін қолданыңыз. Счёт жасаңыз, сосын төлемді симуляциялаңыз:

```bash
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-та төлемді симуляциялау](/kb/sandbox-simulate).

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

| Симптом | Себебі мен шешімі |
|---|---|
| `QUTPAY_WEBHOOK_SECRET не задан` | `$env`/`$vars` ішінде құпия жоқ, немесе `N8N_BLOCK_ENV_ACCESS_IN_NODE=true` |
| `Модуль crypto недоступен` | `NODE_FUNCTION_ALLOW_BUILTIN=crypto` қосып, n8n-ді қайта іске қосыңыз |
| `В узле Webhook включите опцию «Raw Body»` | Webhook → Options → Raw Body қосулы болуы керек |
| `X-Webhook-Timestamp вне допуска` | n8n серверінің сағаты 5 минуттан көп ауытқыған — NTP баптаңыз |
| `Подпись webhook неверна` | Құпия басқа адрестен/ұйымнан, немесе денені прокси өзгерткен |
| Кабинетте жеткізу `HTTP 404` | Workflow белсенді емес, немесе Production URL орнына Test URL берілген |
| Счёт жасауда `401 unauthorized` | Кілт қате немесе HTTP Request түйінінде credential таңдалмаған |
| `429 request_rate_limited` | Сұрау тым жиі — `Retry-After` тақырыбын құрметтеңіз |

Webhook мүлде келмей жатса, себебі көбіне қолтаңбада емес: [Webhook келмей жатыр](/kb/webhook-not-arriving).

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

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

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

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

**Жауаптағы `payUrl`-ды клиентке қалай жеткізем?** Форманы жіберген беттен сол адреске бағыттаңыз. Форма-хук арқылы бірден бағыттайтын дайын жол да бар: [Tilda және кез келген форма](/kb/tilda-forms).

**Қате кодын қайдан қараймын?** [Қателер каталогы](/kb/error-catalog) бетінде барлық код топтап берілген.