# QR Integration API — версия 1.0.0

Документ для разработчиков партнёрского сайта или Telegram-бота. API создаёт QR-заявки, выдаёт изображение и ссылку для оплаты, сообщает фактический статус платежа и показывает расчёты USDT только вашей площадки. Язык вашего приложения может быть любым; ниже есть готовый HTTP-клиент и Telegram-адаптер на Dart, а также backend сайта на JavaScript.

Начните с полного сценария ниже, затем подключайте HTTP-клиент к своему диалогу или форме. Для первого запуска без ключа используйте офлайн-пример Dart: `dart run bin/lifecycle_demo.dart`. Он подменяет HTTP, воспроизводит сбои и не создаёт счета. Учебный симулятор на странице документации также работает с вымышленными ответами; он не принимает API-ключ и не обращается к платёжным маршрутам.

В руководстве ФИО, ID, суммы курса и платёжный адрес — учебные данные. Команды cURL и рабочий Telegram-адаптер с настоящим ключом обращаются к рабочему API: перед их запуском подставьте согласованные реальные данные плательщика.

## Подключение

1. Администратор платформы создаёт API-партнёра в разделе «Партнёры» кнопкой «Создать API-партнёра» и передаёт вам адрес сервиса и API-ключ по защищённому каналу. Полный ключ показывается при создании один раз.
2. Сохраните `QR_API_BASE` и `QR_API_KEY` в переменных окружения своего backend. Адрес API: `https://api.cashwellpay.com/api/v1`; `QR_API_BASE` включает `/api/v1`.
3. При необходимости передайте администратору свой публичный HTTPS webhook URL и сохраните отдельно выданный `QR_WEBHOOK_SECRET`.
4. Создайте заявку, дождитесь QR, получите подтверждение оплаты. Для восстановления после перезапуска используйте сохранённый ID и `GET /orders/{id}`.

Используйте `Authorization: Bearer <API_KEY>` во всех запросах к данным и QR. Ключ относится ко всей вашей площадке. Ваш backend самостоятельно проверяет своих пользователей и связывает каждого пользователя со своими заявками. Не разрешайте клиенту читать произвольный ID заявки через ваш backend без проверки владельца.

Не передавайте API-ключ в браузерный JavaScript, Flutter-приложение пользователя, Telegram-сообщение, query-параметр или публичный URL изображения. Из браузера обращайтесь к своему авторизованному backend; из бота скачивайте PNG на сервере и отправляйте пользователю байты изображения. API-ключ и webhook secret — разные секреты.

При ротации администратор создаёт новый ключ, вы обновляете его на своих серверах, затем старый ключ отзывается. Отозванный ключ сразу перестаёт работать. Пауза партнёра запрещает новые заявки; чтение существующих и повтор уже принятого идентичного запроса сохраняются.

## Полный сценарий: 1 000 ₽ от заявки до подтверждения

Условие: авторизованный трейдер вашей площадки подтвердил оплату на `1000.00` ₽. В примере API возвращает курс `91.5628` ₽/USDT и расчёт `10.92146592` USDT. Курс уже учитывает общий коэффициент `1.06`; повторно прибавлять к нему 6% не нужно.

| Шаг | Обмен с API | Что делает ваше приложение |
| --- | --- | --- |
| 1. Подтверждение данных | Запросов пока нет | Показывает предупреждение, полные ФИО, банк и сумму. Получает подтверждение трейдера. |
| 2. Сохранение намерения | Запросов пока нет | Записывает владельца, исходное тело, `external_id` и `Idempotency-Key` в свою БД. |
| 3. Создание | `POST /orders` → `202`, `status: "creating"` | Сохраняет вернувшийся `id`. Показывает «Готовим QR», запускает проверку по этому ID. |
| 4. Готовность | `GET /orders/{id}` → `200`, `status: "ready"` | Скачивает PNG с Bearer на своём backend. Показывает QR и кнопку с `payment_url`, если она есть. |
| 5. Оплата | Подписанный `order.updated` с `data.status: "paid"` или GET со `status: "paid"` | Обновляет сохранённую заявку, убирает кнопку оплаты и QR, уведомляет её владельца. |
| 6. Учёт | `GET /balance` | Сверяет рассчитанные обязательства площадке и уже отмеченные платформой выплаты USDT. |

### Привязка к трейдеру до первого POST

Это пример записи **в вашей БД**, а не дополнительный запрос или ответ API:

```json
{
  "local_order_id": "checkout-123",
  "trader_id": "trader-17",
  "telegram_chat_id": 123456789,
  "external_id": "merchant-order-123",
  "idempotency_key": "create-merchant-order-123",
  "request": {
    "external_id": "merchant-order-123",
    "full_name": "Иванов Иван Иванович",
    "bank": "Сбербанк",
    "amount_rub": "1000.00"
  },
  "api_order_id": null
}
```

`trader_id` и `telegram_chat_id` берите из своей проверенной сессии или Telegram-обновления после проверки доступа. Эти поля не передаются в QR API. При просмотре и повторной выдаче QR ваш backend проверяет владельца локальной заявки. Для сайта это проверка авторизованного пользователя, для бота — числового ID пользователя и сохранённого чата.

После POST запишите `api_order_id: "0123456789abcdef0123"` в ту же запись. Если ответ потерялся, исходная запись остаётся: воркер повторяет сохранённое тело и ключ, получает прежний ID и продолжает работу. Не создавайте новую локальную заявку из-за таймаута.

### Пример подтверждённой оплаты

Ниже полный ответ `GET /orders/0123456789abcdef0123` после оплаты. Формат `creating` и `ready` с полными полями приведён в следующем разделе.

```json
{
  "id": "0123456789abcdef0123",
  "external_id": "merchant-order-123",
  "status": "paid",
  "generation_status": "ready",
  "payment_status": "paid",
  "amount_rub": "1000.00",
  "trader_rate": "91.5628",
  "expected_usdt": "10.92146592",
  "created_at": 1795251600.0,
  "updated_at": 1795251660.0,
  "expires_at": 1795252500.0,
  "payment_url": null,
  "qr_url": null
}
```

`generation_status` всё ещё `ready`, но платёж уже `paid`: основной статус оплаты определяйте по `status`. В подтверждённой заявке API больше не возвращает ссылку и QR. Сумма `expected_usdt` — расчёт по зафиксированному курсу; сам ответ не выполняет перевод USDT. Повторный `paid` после сетевого повтора или сверки обновляет ту же заявку, а не создаёт ещё одно начисление.

### Что увидит трейдер

1. Перед отправкой: «ФИО: Иванов Иван Иванович; банк: Сбербанк; сумма: 1 000 ₽. Данные верны?»
2. Пока `creating`: «Заявка принята. Готовим QR». Сохраняйте номер и давайте обновить статус.
3. При `ready`: крупный PNG, сумма, `trader_rate`, `expected_usdt` и кнопка «Перейти к оплате», если `payment_url` не `null`.
4. При `paid`: «✅ Оплата подтверждена. Заявка №0123456789abcdef0123, сумма 1 000 ₽». Удалите или отключите прежние элементы оплаты.
5. При `expired` или `cancelled`: соответствующий статус без работающей кнопки оплаты. При `needs_review`: «Уточняем результат. Сохраните номер заявки», без автоматического создания замены.

Отправка подтверждения пользователю выполняется вашим ботом или сайтом по сохранённой привязке. QR API не знает Telegram-токен вашего приложения и не выбирает получателя за вас.

## Создание и получение QR

Перед подтверждением в своём интерфейсе показывайте предупреждение: «Обязательно проверьте корректность введённых данных. В случае предоставления фейковых данных ваш кабинет и баланс будут заморожены. ФИО указывайте полностью: фамилию, имя и отчество, без сокращений. Для каждой заявки указывайте ФИО фактического плательщика, от которого будет оплата».

```sh
export QR_API_BASE='https://api.cashwellpay.com/api/v1'
# QR_API_KEY задайте в секретах вашего сервера, не сохраняйте в репозиторий.
curl --fail-with-body -X POST "$QR_API_BASE/orders" \
  -H "Authorization: Bearer $QR_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: merchant-order-123' \
  --data '{"external_id":"merchant-order-123","full_name":"Иванов Иван Иванович","bank":"Сбербанк","amount_rub":"1000.00"}'
```

Успешный ответ — **202 Accepted**. Генерация идёт в общей устойчивой очереди; API не удерживает HTTP-соединение до ответа платёжной формы.

```json
{
  "id": "0123456789abcdef0123",
  "external_id": "merchant-order-123",
  "status": "creating",
  "generation_status": "queued",
  "payment_status": "pending",
  "amount_rub": "1000.00",
  "trader_rate": "91.5628",
  "expected_usdt": "10.92146592",
  "created_at": 1795251600.0,
  "updated_at": 1795251600.0,
  "expires_at": null,
  "payment_url": null,
  "qr_url": null
}
```

Числа курса в примере иллюстративные; используйте значения, вернувшиеся именно для заявки, для отображения клиенту. Денежные значения передаются **десятичными строками**. Не преобразовывайте их в `double` для учёта денег; применяйте Decimal или целые минимальные единицы.

| Поле запроса | Правило |
| --- | --- |
| `external_id` | Ваш стабильный ID, уникальный в рамках вашей площадки. 1–128 ASCII-символов: первая буква/цифра, далее буквы, цифры, `.`, `_`, `:`, `/`, `-`. |
| `full_name` | Настоящие полные ФИО плательщика, фамилия, имя и отчество без сокращений. Валидируется формат; разные заявки могут содержать разные ФИО. Максимум 200 символов. |
| `bank` | Банк, с которого будет выполнена оплата; 2–100 символов, без управляющих символов. |
| `amount_rub` | Строка от `"50"` до `"35000"`, не более двух знаков после **точки**. Например `"400"`, `"1000.50"`. JSON-число, запятая, отрицательное значение и экспонента не принимаются. |
| Заголовок `Idempotency-Key` | Обязательный стабильный ID операции, те же ASCII-правила и длина 1–128. |

Лишние поля запрещены. Максимальный размер тела запроса — 16 КиБ.

**Повторы:** заранее сохраните исходные данные и оба идентификатора в своей базе. Если соединение оборвалось, повторите POST с тем же телом, `external_id` и `Idempotency-Key`: вернётся существующая заявка, повторный QR не создаётся. Тот же ключ или `external_id` с изменёнными данными даёт `409`. Не генерируйте новый ключ при каждом сетевом повторе. HTTP-таймаут не доказывает, что заявка не была создана.

Различайте оба идентификатора: `external_id` идентифицирует вашу заявку, `Idempotency-Key` — операцию её создания. Новый ключ с прежним `external_id` и теми же нормализованными данными также возвращает существующую заявку. Для действительно новой заявки нужен новый `external_id`; сетевой повтор новой заявкой не является. POST всегда отвечает `202`, в том числе при повторе уже готовой или оплаченной заявки: её фактический статус находится в JSON.

После ответа сохраните `id`:

```sh
curl --fail-with-body "$QR_API_BASE/orders/0123456789abcdef0123" \
  -H "Authorization: Bearer $QR_API_KEY"
```

Для одной активной заявки обычно достаточно опроса раз в 2–5 секунд; при сбоях увеличивайте интервал. Для нескольких заявок используйте один планировщик с общим лимитом запросов и webhook как основной сигнал. Отдельный частый таймер на каждую заявку быстро исчерпает лимит ключа. При `ready` появятся `qr_url` и, если платёжный QR содержит безопасный веб-адрес, `payment_url`:

```json
{
  "id": "0123456789abcdef0123",
  "external_id": "merchant-order-123",
  "status": "ready",
  "generation_status": "ready",
  "payment_status": "pending",
  "amount_rub": "1000.00",
  "trader_rate": "91.5628",
  "expected_usdt": "10.92146592",
  "created_at": 1795251600.0,
  "updated_at": 1795251603.0,
  "expires_at": 1795252500.0,
  "payment_url": "https://payments.example/pay/opaque-invoice",
  "qr_url": "/api/v1/orders/0123456789abcdef0123/qr"
}
```

`qr_url` относится к тому же хосту API. Скачайте изображение с Bearer на своём сервере:

```sh
curl --fail-with-body "$QR_API_BASE/orders/0123456789abcdef0123/qr" \
  -H "Authorization: Bearer $QR_API_KEY" --output qr.png
```

Ответ — `image/png`, до 10 МиБ, с `Cache-Control: private, no-store`. Проверяйте статус ответа, тип и размер до передачи изображения клиенту. Не следуйте перенаправлению с авторизацией и не отправляйте ключ на другой хост. Кнопке «Перейти к оплате» передавайте `payment_url`, а не защищённый `qr_url`; если `payment_url` равен `null`, показывайте только QR. Ссылка платежа может вести на платёжную страницу; не добавляйте в неё API-ключ.

**Выданный QR не означает оплату.** Источником подтверждения служит `status: "paid"` из GET или проверенного webhook. После истечения срока QR больше не выдаётся; позднее подтверждение оплаты учитывается отдельным обновлением статуса.

## Состояния заявки

| `status` | Значение и действие |
| --- | --- |
| `creating` | Заявка в очереди/обработке. Продолжайте опрос с сохранённым ID. |
| `ready` | PNG доступен, оплата ещё не подтверждена. |
| `paid` | Оплата подтверждена. Используйте `expected_usdt` этой заявки для расчёта. |
| `cancelled` | Заявка отменена. |
| `expired` | Срок платежа истёк. Проверяйте обновления, если клиент сообщает о поздней оплате. |
| `failed` | Генерация завершилась ошибкой. Не выдавайте фиктивный QR. |
| `needs_review` | Результат создания или оплаты требует уточнения. Сохраните ID, дождитесь обновления; не создавайте автоматическую замену. |

`status` — основной публичный статус. `generation_status` описывает техническую очередь: `draft`, `queued`, `processing`, `submitting`, `ready`, `delivered`, `needs_review`, `failed`, `cancelled`. Он может оставаться `ready` при уже подтверждённой оплате, поэтому не определяйте оплату по нему. `payment_status` — `pending`, `paid`, `cancelled`, `expired` или `needs_review`. Даты — Unix seconds UTC, допускают дробную часть; `expires_at` может отсутствовать (`null`).

Список: `GET /orders?limit=50&offset=0`, `limit` от 1 до 100. Ответ `{items: [...], total, limit, offset}` содержит только вашу площадку. Для восстановления после простоя можно сверить сохранённые ID и текущие статусы; список не является журналом событий с неизменяемой пагинацией.

## Курс и расчёты

`GET /rate` возвращает актуальный **курс трейдера** в ₽ за USDT, коэффициент `factor: "1.06"`, `observed_at`, `valid_until`, `stale: false`, `min_amount_rub` и `max_amount_rub`. Базовый внутренний курс не раскрывается. Устаревший курс не используется для новых заявок: ответ `503 rate_unavailable`, повторите позже. При создании фиксируется курс конкретной заявки; изменение текущего курса не меняет старую заявку. Оценка количества USDT: рубли / курс трейдера. Для окончательного отображения берите возвращённое `expected_usdt`, не пересчитывайте его своим округлением.

`GET /balance` возвращает только расчёты вашей площадки:

| Поле | Значение |
| --- | --- |
| `expected_usdt` | Общая рассчитанная сумма по подтверждённым оплатам. `null`, если есть неразрешённое расхождение или отсутствующий курс. |
| `paid_usdt` | Фактически отмеченные платформой выплаты USDT вашей площадке. |
| `payable_usdt` | Осталось выплатить, не меньше нуля; `null` при неполных данных. |
| `balance_usdt` | Расчётный остаток с учётом выплат; может быть отрицательным после отмены/пересмотра ранее оплаченной заявки. |
| `overpaid_usdt` | Сумма переплаты при отрицательном остатке. |
| `expected_usdt_known_amount`, `payable_usdt_known_amount` | Известная часть суммы, а не полный итог при `complete: false`. |
| `expected_usdt_missing_orders` | Количество оплат без корректно зафиксированного курса. |
| `conflict_orders` | Количество неразрешённых расхождений. |
| `complete` | Можно ли считать финансовый итог полным. |
| `total_orders`, `successful_orders`, `successful_amount_kopeks` | Число заявок, подтверждённых оплат и их сумма в целых копейках. |

Расчёты платформы с вашей площадкой и ваши выплаты собственным трейдерам — разные уровни учёта. GET `/balance` показывает первый уровень. Публичный API не позволяет вручную присвоить заявке `paid` и сам не переводит USDT. Фактические выплаты платформы отмечает её администратор; ваша площадка ведёт собственный учёт выплат своей команде.

Например, после единственной подтверждённой заявки на 1 000 ₽ без отмеченных выплат ответ выглядит так:

```json
{
  "expected_usdt": "10.92146592",
  "expected_usdt_known_amount": "10.92146592",
  "expected_usdt_missing_orders": 0,
  "paid_usdt": "0",
  "payable_usdt": "10.92146592",
  "payable_usdt_known_amount": "10.92146592",
  "balance_usdt": "10.92146592",
  "overpaid_usdt": "0",
  "total_orders": 1,
  "successful_orders": 1,
  "successful_amount_kopeks": 100000,
  "conflict_orders": 0,
  "complete": true
}
```

Если у площадки есть ещё одна заявка с неразрешённым расхождением, полный итог будет неизвестен. Это пример **полного ответа**, а не нулевого баланса:

```json
{
  "expected_usdt": null,
  "expected_usdt_known_amount": "10.92146592",
  "expected_usdt_missing_orders": 0,
  "paid_usdt": "0",
  "payable_usdt": null,
  "payable_usdt_known_amount": "10.92146592",
  "balance_usdt": null,
  "overpaid_usdt": null,
  "total_orders": 2,
  "successful_orders": 1,
  "successful_amount_kopeks": 100000,
  "conflict_orders": 1,
  "complete": false
}
```

В этом случае показывайте «Известная часть: 10.92146592 USDT; итог уточняется», а не «К выплате 10.92146592». `complete: true` относится к полноте финансового расчёта подтверждённых оплат и не означает, что все активные заявки закрыты.

## Баланс API-партнёра в Telegram-группе

Кроме `GET /api/v1/balance`, баланс можно смотреть в общей группе вашей площадки. Добавьте **@cashwell_QR_payout_bot** в группу и отправьте `/groupid`. Передайте полученный числовой ID оператору: владелец платформы привяжет группу к вашей API-площадке в разделе **Партнёры → ваша площадка → Группа API-партнёра**.

После подключения доступны команды:

- `/balance` — созданные и оплаченные заявки, начисленные USDT, отмеченные выплаты площадке и остаток к выплате.
- `/apiorders` — история заявок с вашими внешними ID, статусами и сохранёнными расчётами.
- `/apipayments` — история отмеченных оператором выплат USDT вашей площадке.

В группе доступны только сведения привязанной площадки. Все участники этой группы смогут запрашивать её баланс. Для команд не нужен API-ключ: не отправляйте его в группу. Одна группа связывается с одной API-площадкой; привязкой управляет владелец платформы. Бот должен оставаться участником группы с правом отправлять сообщения. Если в группе несколько ботов, используйте команду с обращением, например `/balance@cashwell_QR_payout_bot`.

Новые подтверждённые оплаты после подключения сопровождаются уведомлением в эту группу. Прежние сделки остаются в балансе и истории, без массовой повторной отправки старых подтверждений. Получение QR не считается оплатой. Баланс группы и `GET /balance` используют одни и те же сохранённые начисления и выплаты; текущий курс не пересчитывает старые сделки. Групповые команды только показывают сведения и не создают заявку или перевод USDT.

## Подписанные webhook

Webhook необязателен: GET остаётся каноническим способом проверить состояние. Администратор настраивает один URL для вашей площадки: **HTTPS, порт 443, публичный адрес, без логина/пароля, query и fragment**. Локальные и частные адреса не допускаются. При первой настройке/ротации отдельно выдаётся `signing_secret`; обычное чтение конфигурации его не раскрывает.

Сервис отправляет POST с `Content-Type: application/json`:

```json
{"id":"opaque-event-id","type":"order.updated","created_at":1795251605.0,"sequence":2,"data":{"id":"0123456789abcdef0123","external_id":"merchant-order-123","status":"paid","generation_status":"ready","payment_status":"paid","amount_rub":"1000.00","trader_rate":"91.5628","expected_usdt":"10.92146592","created_at":1795251600.0,"updated_at":1795251605.0,"expires_at":1795252500.0,"payment_url":null,"qr_url":null}}
```

Заголовки:

```text
X-QR-Event-ID: opaque-event-id
X-QR-Timestamp: 1795251605
X-QR-Signature: sha256=<64 lowercase hex characters>
```

Формула подписи: **HMAC-SHA256(secret, ASCII(timestamp) + byte(".") + raw_body_bytes)**. Проверяйте исходные байты до `jsonDecode`/JSON middleware; повторная сериализация JSON меняет подпись. Сравнивайте MAC за постоянное время, проверяйте допустимое отклонение времени (в примерах ±300 секунд), соответствие заголовка Event-ID полю `id`, тип события и положительный целый `sequence`.

Доставка происходит как минимум один раз. Сохраните уникальный `event.id` в durable inbox, обработайте только ещё не применённый номер `sequence` **для этой заявки**, и подтвердите HTTP `2xx` после устойчивой записи. У события стабильны ID и тело при повторах, а timestamp и подпись обновляются на каждой попытке. Повторы могут приходить не по порядку. Более старый `sequence` не должен откатывать уже известный статус. Если финансовое действие применяется непосредственно из webhook, уникальная запись события, обновление sequence и это действие должны быть одной транзакцией. В варианте с отдельным воркером ниже транзакция сохраняет inbox и запрос сверки; финансовая проекция обновляется по каноническому GET.

События формируются для наблюдаемых `ready`, `paid`, `cancelled`, `expired`, `failed`, `needs_review`. Отдельное событие `creating` не отправляется. Быстрые промежуточные изменения могут объединяться: первое событие может сразу содержать `paid`, даже если ваше приложение не увидело `ready`.

После ошибок DNS/сети, таймаутов, HTTP `408`, `429` и `5xx` сервис повторяет доставку. Для текущей конфигурации предусмотрено до 20 попыток в течение 24 часов активной доставки; задержки растут от 5 секунд до 1 часа. Числовой `Retry-After` получателя учитывается в пределах 1 часа. Перенаправления, другие `4xx` и небезопасный адрес не повторяются автоматически. Ответ получателя должен прийти за 10 секунд, его тело — не больше 8 КиБ; успешным считается `2xx` после этих проверок. Удобный ответ при принятом событии — пустой `204 No Content`.

После исчерпания попыток администратор видит недоставленные события и может повторить их. Пауза самой площадки не прекращает статусы её принятых заявок; отдельное отключение webhook приостанавливает доставку и её временной бюджет. Смена URL/секрета прекращает повторы старой конфигурации и повторно снимает актуальные состояния незавершённых доставок. Это не выгрузка всей уже доставленной истории. После переключения URL/секрета или простоя обязательно сверяйте сохранённые заявки через GET.

`sequence` существует в конверте webhook и увеличивается отдельно для каждой заявки. В GET такого поля нет; `updated_at` не объявлен универсальной заменой sequence. Не сравнивайте номера событий разных заявок и не используйте один глобальный счётчик. Для взаимодействия webhook и опроса используйте общую процедуру сверки, описанную ниже.

## Ошибки

Ошибки имеют стабильную форму; не привязывайтесь к английскому тексту `message`:

```json
{"error":{"code":"idempotency_conflict","message":"This idempotency key was already used with different order data."}}
```

| HTTP / код | Что произошло | Что делать |
| --- | --- | --- |
| `400` / `422 invalid_request` | Неверные поля, формат, лишние параметры или нет Idempotency-Key | Исправить данные до новой подтверждённой операции. Не повторять ошибочное тело по таймеру. |
| `401 invalid_api_key` | Нет ключа, ключ неверен или отозван | Остановить обращения, проверить секрет на backend и согласованную ротацию. |
| `403 partner_paused` | Приостановлено создание новых заявок площадки | Сохранить намерение, связаться с администратором. Чтение принятых заявок продолжается. |
| `403 daily_limit_reached` | Достигнут суточный лимит | Показать ограничение; не создавать замены с другими ID. |
| `404 order_not_found` | ID неизвестен этой площадке | Проверить ключ, окружение и собственную привязку. Чужие ID не раскрываются. |
| `408 request_timeout` | Тело запроса не пришло за 10 секунд | Повторить исходную операцию с теми же идентификаторами. |
| `409 idempotency_conflict` / `external_id_conflict` | ID уже связан с другими данными | Сверить сохранённый исходный запрос. Не менять ключ ради обхода конфликта. |
| `409 qr_unavailable` | PNG ещё не готов либо уже недоступен | Прочитать статус заявки. Скачать PNG можно только при `ready`. |
| `413 request_too_large` | Тело больше 16 КиБ | Исправить формирование JSON. |
| `429 rate_limit_exceeded` | Лимит запросов ключа | Приостановить общий планировщик до `Retry-After`; затем возобновить с ограниченной скоростью. |
| `429 queue_full` | Очередь генерации заполнена | Повторить тот же POST после `Retry-After`; не выделять новый external_id. |
| `503 rate_unavailable` | Нет свежего курса | Подождать, повторить тот же POST. Не заменять расчёт собственным устаревшим курсом. |
| `503 api_unavailable` | API временно выключен | Сохранить операцию и повторить позже. |
| `5xx` / разрыв соединения | Итог запроса неизвестен | При известном `id` читать GET; при потерянном ответе создания повторить **прежние** тело и оба ID. |

### Лимиты и стратегия повторов

Текущие стандартные пределы: **120 аутентифицированных HTTP-запросов на ключ за календарную минуту** и **20 новых успешно принятых созданий на ключ за минуту**. Запросы списка, статуса, курса, баланса и PNG, а также идемпотентные повторы расходуют общий HTTP-бюджет; повтор существующей заявки не создаёт ещё одну новую. Обычно одновременно допускается до 20 ожидающих генерации заявок площадки; готовые QR в этот счётчик не входят. Платформа может отдельно ограничить очередь.

Держите общий лимитер на backend. При временном сбое без `Retry-After` производственная политика может использовать паузы 1, 2, 4, 8… секунд до 30 секунд с небольшим случайным разбросом, затем редкие попытки в фоне. С `Retry-After` не повторяйте раньше указанного времени. Разрешайте только один незавершённый опрос одной заявки. Не запускайте новый фоновый опрос при каждом повторном открытии сообщения или страницы.

Это рекомендуемая политика приложения: приложенный `QrApi` делает до трёх HTTP-попыток, использует фиксированный `retryDelay` и ограничивает числовой `Retry-After` диапазоном 1–30 секунд. Для длительного восстановления и точного соблюдения общего бюджета нужен ваш устойчивый планировщик поверх клиента.

### Восстановление после перезапуска

1. Прочитайте собственные незавершённые операции создания и повторите сохранённые POST. Отсутствующий ответ не меняет сохранённые ID.
2. Для записей с `api_order_id` запланируйте GET с общим ограничением скорости. Сначала обработайте `creating`, `ready` и `needs_review`, затем периодически перепроверяйте недавно закрытые заявки с возможной поздней оплатой.
3. Продолжите чтение durable inbox и отправку собственных уведомлений из локального outbox. Принятый webhook нельзя терять из-за остановки процесса после HTTP-ответа.
4. Сверьте `GET /balance`: `complete: false` означает неполный финансовый итог. Известная часть не заменяет полный остаток к выплате.
5. Если нужно найти заявку, используйте свой сохранённый ID; список с offset пригоден для сверки и поиска, но новые вставки сдвигают страницы. Не используйте его как единственный журнал изменений или гарантированный курсор синхронизации.

## Производственная обработка: одна заявка, один результат

Для небольшого внедрения достаточно своего HTTP-клиента, таблицы намерений создания, очереди сверки и обработчика webhook. Для нескольких процессов используйте транзакционную БД. Приведённая схема описывает **вашу локальную проекцию**, не внутреннюю БД платформы и не автоматический кошелёк трейдера.

Чтобы webhook и опрос не спорили за состояние, удобен такой вариант: webhook после проверки подписи устойчиво сохраняется, отмечает заявку для сверки и будит воркер; фактическую проекцию воркер получает через GET. Один и тот же воркер вызывается после обычного опроса и после webhook. Перенесите бизнес-уведомление в локальный outbox той же транзакции. Ответ `2xx` означает «событие сохранено», а не «сообщение Telegram уже отправлено».

### Пример схемы PostgreSQL

Имена `integration_id`, `trader_id`, `observation_version` и поля аренды ниже принадлежат **вашему приложению**; не добавляйте их в JSON QR API. `integration_id` — постоянное имя подключения одной площадки; смена API-ключа не создаёт новое подключение или новый набор заявок. Данные заявки сохраняются до HTTP-вызова; пара `integration_id` + `external_id` никогда не используется для другого платежа.

```sql
CREATE TABLE qr_orders (
    integration_id text NOT NULL,
    local_order_id text NOT NULL,
    trader_id text NOT NULL,
    telegram_chat_id bigint,
    external_id varchar(128) NOT NULL,
    idempotency_key varchar(128) NOT NULL,
    request_json jsonb NOT NULL,
    request_sha256 char(64) NOT NULL,
    api_order_id char(20),
    status text NOT NULL DEFAULT 'creating',
    trader_rate numeric(38,18) CHECK (trader_rate > 0),
    expected_usdt numeric(38,8) CHECK (expected_usdt > 0),
    confirmed_usdt numeric(38,8) NOT NULL DEFAULT 0 CHECK (confirmed_usdt >= 0),
    local_hold boolean NOT NULL DEFAULT false,
    last_webhook_sequence bigint NOT NULL DEFAULT 0,
    observation_version bigint NOT NULL DEFAULT 0,
    reconcile_requested boolean NOT NULL DEFAULT true,
    lease_token uuid,
    lease_until timestamptz,
    updated_at timestamptz NOT NULL DEFAULT now(),
    PRIMARY KEY (integration_id, local_order_id),
    UNIQUE (integration_id, external_id),
    UNIQUE (integration_id, idempotency_key),
    UNIQUE (integration_id, api_order_id)
);

CREATE TABLE qr_webhook_inbox (
    integration_id text NOT NULL,
    event_id text NOT NULL,
    api_order_id char(20) NOT NULL,
    external_id varchar(128) NOT NULL,
    sequence bigint NOT NULL CHECK (sequence > 0),
    body_sha256 char(64) NOT NULL,
    payload jsonb NOT NULL,
    received_at timestamptz NOT NULL DEFAULT now(),
    PRIMARY KEY (integration_id, event_id)
);

CREATE TABLE qr_projection_audit (
    integration_id text NOT NULL,
    local_order_id text NOT NULL,
    observation_version bigint NOT NULL,
    old_status text NOT NULL,
    new_status text NOT NULL,
    confirmed_delta_usdt numeric(38,8) NOT NULL,
    created_at timestamptz NOT NULL DEFAULT now(),
    PRIMARY KEY (integration_id, local_order_id, observation_version)
);

CREATE TABLE qr_notice_outbox (
    integration_id text NOT NULL,
    local_order_id text NOT NULL,
    observation_version bigint NOT NULL,
    kind text NOT NULL,
    body jsonb NOT NULL,
    delivered_at timestamptz,
    PRIMARY KEY (integration_id, local_order_id, observation_version, kind)
);
```

`confirmed_usdt` — локальная расчётная проекция по подтверждённому статусу. Она не означает полученные вашей площадкой USDT. Для фактически отмеченных выплат сверяйте поле `paid_usdt` ответа `GET /balance`; собственные выплаты трейдерам ведите отдельно.

### Транзакция входящего webhook

До транзакции проверьте HMAC над исходными байтами, возраст timestamp, совпадение Event-ID, тип события, `sequence` и формат данных. Секрет выбирайте по заранее настроенной интеграции получателя, а не из параметров присланного тела.

```text
BEGIN
  INSERT inbox(integration_id, event_id, api_order_id, external_id,
               sequence, body_sha256, payload)
    ON CONFLICT DO NOTHING RETURNING event_id

  если событие уже было:
    проверить совпадение сохранённого body_sha256
    COMMIT; ответить 204 без повторного бизнес-действия

  SELECT локальную заявку по integration_id + external_id FOR UPDATE
  проверить её api_order_id (если уже известен) и сумму по сохранённому запросу
  если привязки нет или данные не совпали:
    устойчиво записать отдельную задачу разбирательства, без начисления
    COMMIT; ответить 204

  если sequence <= last_webhook_sequence:
    COMMIT; ответить 204: это старое наблюдение

  привязать api_order_id, если ответ исходного POST ещё не успел сохраниться
  UPDATE заявки: last_webhook_sequence = sequence,
      reconcile_requested = true,
      observation_version = observation_version + 1
COMMIT
ответить 204
```

Идентичный ID с другим телом не перезаписывайте: сохраните диагностический инцидент без API-ключей и запретите финансовое действие до сверки. При ошибке БД откатите транзакцию и верните `503`, чтобы платформа повторила доставку. Записи без локальной привязки не распределяйте автоматически между трейдерами; сохраните их в отдельной очереди сопоставления.

### Воркер канонической сверки

1. Короткой транзакцией заберите готовую задачу через `SELECT … FOR UPDATE SKIP LOCKED`, установите случайный `lease_token` и срок аренды, сохраните текущий `observation_version`. Завершите транзакцию до сетевого запроса.
2. Если ID ответа создания потерян, восстановите его прежним POST; затем выполните GET. HTTP выполняется вне транзакции и только с конфигурацией своей интеграции.
3. Начните новую транзакцию и заблокируйте **эту же** строку. Проверьте токен и срок аренды, совпадение ID/суммы и сохранённого `observation_version`. Если во время GET пришёл новый webhook или задачу перехватил другой воркер, не применяйте устаревший ответ: оставьте сверку запрошенной и повторите GET.
4. Сохраните статус и зафиксированные десятичные `trader_rate` / `expected_usdt`. Несогласованное изменение ранее сохранённого расчёта отправьте на разбор. Временный HTTP-сбой не превращайте в `failed` платежа.
5. Обновите одну проекцию заявки: для `paid` с корректным `expected_usdt` целевое `confirmed_usdt` равно этой сумме. Для неподтверждённого статуса — нулю. `needs_review` или отсутствие расчёта устанавливает `local_hold`; ранее проведённое фактическое перечисление при этом не отменяется программно.
6. Разницу между новой и прежней проекцией запишите в аудит. Меняйте **одну строку заявки**, а не добавляйте новый платёж при каждом `paid`. При видимом изменении увеличьте локальную версию, добавьте уведомление в outbox и снимите аренду в той же транзакции.
7. Отдельный отправитель доставляет сообщения из outbox сохранённому владельцу. После сбоя Telegram-процесса это повтор доставки уведомления, а не новое начисление или создание QR.

Так, последовательность `paid → needs_review → paid` меняет одну проекцию и признак удержания. Даже при двух разных ID событий `paid` она не создаёт два независимых основания для выплаты. Если собственные бизнес-правила допускают вывод средств, используйте отдельный журнал однократного исполнения по ID заявки и явный процесс разбора расхождений; этот пример платежей USDT не исполняет.

Синтаксис `ON CONFLICT` и блокировки строк основаны на официальной документации PostgreSQL: [INSERT / ON CONFLICT](https://www.postgresql.org/docs/current/sql-insert.html), [блокировки строк](https://www.postgresql.org/docs/current/explicit-locking.html). SQL выше — заготовка для адаптации под ваши таблицы пользователей, очередь и политику хранения, а не миграция API платформы.

## Dart: ваш Telegram-бот

В каталоге `examples/partner_api/dart` находятся готовые примеры версии 1.0.0. Зависимости зафиксированы: `http 1.6.0`, `crypto 3.0.8`, Dart SDK `>=3.4.0 <4.0.0`.

### Сначала — полный офлайн-сценарий

```sh
cd examples/partner_api/dart
dart pub get
dart run bin/lifecycle_demo.dart
dart run test/lifecycle_demo_test.dart
```

Сценарий использует `MockClient` и учебный хост `.example`, игнорирует рабочие ключи окружения, не обращается к QR-сервису и не отправляет сообщения Telegram. Он показывает весь путь: сохранение намерения и владельца → принятый POST с потерянным ответом → повтор с теми же ID → `429` с `Retry-After` → `creating` → `ready` с PNG/ссылкой → подписанный `paid` → восстановление из учебного файла после перезапуска. Повтор события и старый `ready` отбрасываются. Последовательность `paid → needs_review → paid` не создаёт второго бизнес-подтверждения по той же заявке.

Сначала сравните вывод демо со сценарием выше, затем подключайте свой webhook и проверяйте интеграцию с согласованной реальной заявкой. Учебный JSON-inbox рассчитан на один процесс; схема производственной БД приведена выше.

### Подключение к рабочему API

```sh
cd examples/partner_api/dart
dart pub get
dart analyze
dart run test/contract_test.dart
```

`lib/qr_api.dart` — HTTP-клиент: создание, GET/список, курс, баланс, опрос и защищённое скачивание PNG. `bin/telegram_bot.dart` — адаптер, который можно вызвать из обработчика вашего уже существующего бота после вашей проверки трейдера:

```dart
final order = await sendQrForApprovedTrader(
  api: api, telegramBotToken: tokenFromServerEnvironment,
  approvedChatId: verifiedTraderChatId,
  externalId: savedLocalOrderId,
  fullName: payerFullName, bank: payerBank, amountRub: '1000.00',
);
// Сохраните order.id за verifiedTraderChatId; повторная выдача — по тому же ID.
```

Для запуска адаптера отдельно задайте `QR_API_BASE`, `QR_API_KEY`, `TELEGRAM_BOT_TOKEN` и `TELEGRAM_CHAT_ID` в окружении сервера:

```sh
dart run bin/telegram_bot.dart order-123 "Иванов Иван Иванович" "Сбербанк" 1000.00
```

Это выполняет **реальную заявку** и отправляет её в указанный чат; запускайте только с реальными данными и одобренным получателем. Встройте функцию в свой диалог ФИО → банк → сумма → подтверждение. Токен Telegram остаётся у вас; передавать его платформе для HTTP API не требуется. Изображение отправляется multipart-загрузкой `sendPhoto`, кнопка открывает `payment_url`. Загрузку байтов поддерживает официальный [Telegram Bot API sendPhoto](https://core.telegram.org/bots/api#sendphoto); HTTP-вызовы и HMAC реализованы пакетами [Dart http](https://pub.dev/packages/http) и [Dart crypto](https://pub.dev/packages/crypto).

`bin/webhook_server.dart` — проверяющий подпись приёмник: задайте `QR_WEBHOOK_SECRET`, при необходимости `QR_WEBHOOK_INBOX` и `PORT`, запустите `dart run bin/webhook_server.dart`, проксируйте публичный `https://your-host/qr-webhook` на loopback. Пример хранит inbox в приватном файле и работает в одном процессе; для нескольких воркеров и начисления баланса замените его транзакционной БД. Сервер читает исходный [поток байтов HttpRequest](https://api.dart.dev/dart-io/HttpRequest-class.html).

## JavaScript: ваш сайт

`examples/partner_api/javascript/server.mjs` — запускаемый backend для Node.js 22+. Он хранит API-ключ только на сервере, связывает локальный ID с заявкой, повторяет потерянное создание с прежним ключом и проксирует PNG. В браузере есть простая форма и опрос статуса. Webhook проверяет HMAC и сохраняет inbox.

Задайте серверные переменные `QR_API_BASE`, `QR_API_KEY`, `QR_WEBHOOK_SECRET`, `SITE_USERNAME`, `SITE_PASSWORD`, `SITE_ORIGIN` (например `https://your-host`), при необходимости `PRIVATE_STATE_FILE` и `PORT`. Запустите:

```sh
node examples/partner_api/javascript/server.mjs
```

Публикуйте loopback-сервер через HTTPS reverse proxy. Демонстрация рассчитана на **одного** трейдера с HTTP Basic auth. В вашем продукте замените её своей сессией/ролями, проверкой доступа и БД: локальная заявка должна принадлежать конкретному авторизованному пользователю. Закрывайте от публичного доступа файл состояния и секреты. Пример не является заменой вашей регистрации, выплат и управления командой.

Публичная схема: `GET /api/v1/openapi.json`; версия в файле `PARTNER_API_OPENAPI.json`. В неё входят только партнёрские HTTP-маршруты, без внутренней админ-панели и секретов. Страница документации: [api.cashwellpay.com/api/v1/docs](https://api.cashwellpay.com/api/v1/docs). Доступен также отдельный вариант подключения своего Telegram-бота через токен и одобрение платформы; он описан в `PARTNER_GUIDE.md` и не требуется для HTTP API.
