API чеков НПД для ЮKassa и Telegram-ботов

Передавайте название услуги и данные оплаченного заказа, получайте статус и ссылку на чек через HTTP API v1. О готовом чеке можно узнать опросом API или через подписанное уведомление. Действующий магазин ЮKassa остаётся вашим.

Это API сервиса НПД Чек. Для регистрации дохода агент использует сессию веб-кабинета «Мой налог». Мы не используем официальный партнёрский API ФНС. Как устроено подключение.

Подключение

• Подключите магазин ЮKassa и агента ФНС в кабинете НПД Чек.
• Подготовьте очередь отправки заказов в боте и обработчик статусов.
• Кабинет → «04. API для бота» → «Включить API и получить ключ».
• Сохраните ключ в Cloudflare Worker Secret `NPDCHECK_INTEGRATION_KEY`.

Авторизация

Authorization: Bearer <NPDCHECK_INTEGRATION_KEY>
Content-Type: application/json

Проверка подключения

{"api_version":"1","provider":"yookassa","shop_connected":true,"subscription_active":true}

Передача оплаченного заказа

{
  "provider": "yookassa",
  "external_id": "order:42",
  "payment_id": "идентификатор-платежа-ЮKassa",
  "description": "Персональная тренировка",
  "amount": "1500.00",
  "currency": "RUB"
}

• external_id: стабильный уникальный ID вашего заказа,1–80 ASCII-символов,

• payment_id: provider_payment_charge_id из Telegram SuccessfulPayment.

• description:1–128 символов, осмысленное название услуги без переносов

• amount: строка в рублях строго с2знаками после точки. Сумма должна совпасть

{
  "created": true,
  "order": {
    "external_id": "order:42",
    "provider": "yookassa",
    "payment_id": "идентификатор-платежа-ЮKassa",
    "description": "Персональная тренировка",
    "amount": "1500.00",
    "currency": "RUB",
    "status": "queued",
    "ready": false,
    "receipt_url": null,
    "error": null
  }
}

Статус и ссылка на чек

Ошибки и повторы

Подключение к присланному коду

import {orderPayload, submitOrder, getOrder, receiptLink}
  from './npdcheck-client.mjs';

// successful_payment: получить и сохранить снимок в локальную очередь.
const payload = orderPayload(order, msg.successful_payment);
// payload=null для demo/balance. Не вызывает сеть.

// В фоновом обработчике очереди:
const accepted = await submitOrder(C.env, savedPayload);
// Отметить отправку подтверждённой; это ещё не означает, что чек готов.

// Позже в отдельной задаче опроса:
const state = await getOrder(C.env, savedPayload.external_id);
const link = receiptLink(state);
// Только если link непустой: отправить покупателю и записать результат.

Границы первой версии

Ежемесячные списания

Каждый фактически завершённый платёж ЮKassa, включая рекуррентный, передаётся отдельным заказом. Используйте external_id: "charge:" + payment.id, а не постоянный ID подписки. Повтор одного списания отправляется с теми же данными и тем же ID. Круглосуточная выдача требует постоянно работающего агента и активного доступа. Действующий webhook ЮKassa можно оставить: ваш backend сохраняет событие в очередь и передаёт платёж через POST /orders. Возвраты также должны доходить до НПД Чек либо проверяться продавцом в кабинете.

Подписанные уведомления о чеках

Кабинет → «04. API для бота» → «Уведомления на ваш сервер». Сначала включите API. Укажите публичный HTTPS URL на порту 443. Секрет npdc_wh_… показывается один раз: сохраните его как NPDCHECK_WEBHOOK_SECRET на своём backend, отдельно от ключа API. Доступны сохранение/перевыпуск адреса и секрета, отключение и последние 20 доставок. Смена адреса/секрета и отключение отменяют старые ожидающие доставки. Отзыв ключа интеграции также отключает уведомления. Новое подключение не рассылает старые чеки.

POST содержит JSON в UTF-8:

{
  "id": "evt_0123456789abcdef0123456789abcdef",
  "type": "receipt.registered",
  "created_at": 1793690000,
  "data": {
    "external_id": "charge:payment-12345678",
    "provider": "yookassa",
    "payment_id": "payment-12345678",
    "provider_receipt_id": "fns-document-id",
    "description": "Подписка MUVAI за ноябрь",
    "amount": "1000.00",
    "original_amount": "1500.00",
    "refunded_amount": "500.00",
    "currency": "RUB",
    "status": "registered",
    "ready": true,
    "receipt_url": "https://lknpd.nalog.ru/api/v1/receipt/ИНН/ID/print",
    "error": null
  }
}

Типы: receipt.registered, receipt.canceled, receipt.partial_refund, receipt.refund_review, receipt.unknown, receipt.review, receipt.failed. external_id может быть null, если заказ ещё не передавался через API.

Заголовки:

• X-NPDCheck-Event-Id: тот же id.
• X-NPDCheck-Timestamp: время попытки в Unix-секундах.
• X-NPDCheck-Signature: v1= + hex HMAC-SHA256 от

timestamp + "." + исходные байты тела, ключом служит секрет npdc_wh_….

Проверяйте подпись до разбора/использования данных, через constant-time compare или криптографическую verify. Допускайте разницу часов не более 5 минут и синхронизируйте часы сервера. Повторная попытка получает новую подпись и timestamp, сохраняя ID и тело. В модуле есть готовая verifyWebhook(rawBody, request.headers, env.NPDCHECK_WEBHOOK_SECRET).

import {verifyWebhook} from './npdcheck-client.mjs';

// В маршруте POST /webhooks/npdcheck вашего backend:
const rawBody = await request.text();
const event = await verifyWebhook(rawBody, request.headers, env.NPDCHECK_WEBHOOK_SECRET);
// Здесь: транзакционный INSERT OR IGNORE в свою очередь с UNIQUE(event.id).
// Ответ 2xx только ПОСЛЕ успешной записи; при ошибке БД верните 5xx.
// Затем отдельный worker обрабатывает свою очередь.
return new Response(null, {status: 204});

Успех доставки: любой HTTP 2xx в пределах 5 секунд ожидания сети на соединение/чтение. Редиректы не выполняются. При ошибках до 10 попыток, интервалы после неудач: 30 с, 2 мин, 10 мин, 30 мин, 1 ч, 2 ч, 4 ч, 6 ч, 10 ч (около суток). После исчерпания попыток в кабинете доступен ручной повтор с тем же ID. Событие хранится в БД вместе с изменением чека; перезапуск не теряет очередь.

Доставка допускает повторы и изменение порядка. Храните UNIQUE(event.id), а отправку покупателю учитывайте по ID документа ФНС, поскольку после корректировки у того же платежа появится новый чек. Перед отправкой ссылки получите актуальный заказ через GET /orders/{external_id}: снимок старого события мог уже устареть. Не отправляйте ссылку из события registered, если действующий документ уже другой или аннулирован. Опрос API остаётся доступен как резерв и для сверки пропущенных/устаревших событий.

Частичный возврат и замена чека

Деньги возвращаются через ЮKassa. В кабинете нажмите «Заменить на остаток» возле выданного чека. Сервис проверяет завершённый возврат и показывает текущую сумму, общую возвращённую сумму и остаток. После явного подтверждения продавца:

1. Сохраняется история исходного документа, суммы и ссылки.
2. Аннулируется исходный чек. До подтверждённого успеха новый не выпускается.
3. В очередь ставится новый чек на оставшуюся сумму с исходным названием и датой расчёта.
4. Новый документ доступен через тот же GET заказа и событие receipt.registered.

Повторный частичный возврат допускает следующую замену. Проверяется общая сумма возвратов относительно первоначального платежа, а не сумма последнего чека. Если возврат изменился перед выдачей или результат ФНС неизвестен, операция останавливается для сверки. Автоматически повторять неопределённый POST ФНС нельзя. При полном возврате используется «Аннулировать» без нового чека.

API интеграции по-прежнему не даёт прав возвращать деньги или подтверждать замену: это действие владельца в кабинете. GET заказа дополнительно возвращает original_amount, refunded_amount, provider_receipt_id и replacements.

Основание сохранения даты расчёта: разъяснение ФНС.

Нужна помощь с подключением? Напишите в поддержку НПД Чек.