qr_vitanova/BACKEND_CHANGES.md

Fastcheck Backend — изменения сверх api.txt

Документ с дельтой — что нужно добавить/изменить в спеке public/api.txt, чтобы фронт полноценно заработал. Базовая спека остаётся в силе, здесь только правки.

Полный референс с примерами — см. BACKEND.md в этом же репозитории.

---

1. POST /fastcheck (создание) — расширить тело

Добавить поля orderId, note, returnUrl (все опциональные):

POST /fastcheck
HEADER: Authorization: {"sessionID": "..."}
Body:
{
  "amount": 158000,
  "currency": "RUB",
+ "orderId": "merchant-order-uuid",   // id заказа на стороне мерчанта
+ "note": "Оплата заказа №123",       // комментарий, видит получатель
+ "returnUrl": "https://shop.example.com/thanks"  // куда вернуть юзера после оплаты
}

Response:
{
  "fastcheck": "1234-5678-0001",
  "expiration": "2026-07-07T09:08:18Z",
  "code": "5864",
  "Status": true,
+ "orderId": "merchant-order-uuid"    // эхо обратно
}

note также возвращать в GET /fastcheck, чтобы получатель видел причину платежа перед приёмом.

---

2. Зафиксировать единицу amount

В api.txt пример "amount": 158000 неоднозначен. Зафиксировать:

amount — целое число в основной единице валюты (для RUB — рубли, не копейки). Минимум 1.

Если бэкенд считает в копейках — сообщить, фронт изменит формат.

---

3. Merchant webhook (новое)

После успешного POST /fastcheck (accept), сервер шлёт POST на webhookUrl, привязанный к orderId/мерчанту:

POST <merchant_webhook_url>
Headers:
  Content-Type: application/json
  X-Fastcheck-Signature: <hmac-sha256 от тела с секретом мерчанта>

Body:
{
  "event": "fastcheck.paid",
  "fastcheck": "1234-5678-0001",
  "orderId": "merchant-order-uuid",
  "amount": 158000,
  "currency": "RUB",
  "paidAt": "2026-04-30T12:34:56Z"
}

Мерчант проверяет подпись и помечает заказ оплаченным. Ретраи (минимум 3 попытки с экспоненциальной задержкой) при не-2xx ответах.

---

4. Развести create и accept на разные пути (рекомендация)

Сейчас POST /fastcheck делает оба действия — отличается только формой тела (amount vs code). Это хрупко.

- POST /fastcheck            (создание)
- POST /fastcheck            (приём)
+ POST /fastcheck            (создание)
+ POST /fastcheck/accept     (приём)

Фронт правится в одну строку. Если оставляете один путь — оставляем как есть.

---

5. Гранулярные ошибки POST /fastcheck (accept)

В api.txt любая ошибка = 404 { "message": "not authorized" }. Юзер не понимает, что пошло не так. Различать:

401 { "message": "not authorized" }         — нет/невалидная сессия
404 { "message": "fastcheck not found" }    — нет такого номера
403 { "message": "wrong code" }             — код неверный
410 { "message": "already used" }           — чек уже погашен
410 { "message": "expired" }                — просрочен

---

6. CORS + HTTPS + DNS (блокер)

Сейчас https://api.fastcheck.store даёт ERR_NAME_NOT_RESOLVED — домен не резолвится. Без этого тестировать нечего.

Минимально:

• Поднять DNS A-запись на api.fastcheck.store.
• Валидный TLS-сертификат (Let's Encrypt подойдёт).
• На все эндпоинты + OPTIONS отвечать заголовками:

  Access-Control-Allow-Origin: https://<домен-фронта>
  Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
  Access-Control-Allow-Headers: Content-Type, Authorization
  Access-Control-Max-Age: 86400
  

  OPTIONS → 204 No Content без тела.

Подробности — BACKEND.md §1.2.

---

Что не меняется

• GET /ping
• GET /websession, GET /websession/:id, DELETE /websession/:id
• GET /fastcheck
• Формат заголовка Authorization: {"sessionID":"..."}
• Telegram-логин через бот @DexarSupport_bot с ?start=<sessionId>

---

Чеклист для бэкенда

• DNS + HTTPS + CORS (блокер)
• orderId, note, returnUrl в POST /fastcheck (create)
• note возвращается в GET /fastcheck
• Зафиксировать amount в основной единице (рубли)
• Webhook на fastcheck.paid с HMAC-подписью
• Гранулярные ошибки accept
• (опц.) Развести create / accept на разные пути