ERP Platform Docs

PK-summary-answers

время чтения ~4 мин.

PayKeeper — ответы на наши вопросы

Дата: 2026-04-23
Источник: переписка с техподдержкой PayKeeper

Ответы покрывают 7 вопросов по интеграции, выявленных при анализе бэклога и спек. В скобках указаны ссылки на соответствующие разделы протокола из этой папки.

1. Cross-device push (передача заказа с нашего планшета на терминал PayKeeper)

Вопрос: По публичным спекам механизма нет; в бэклоге PK помечено «подключение iiko/сайта/CRM» — уточнить что за механизм и доступен ли нам.

Ответ PK:

Работает через форму создания счёта в API ЛК. После этого в терминале появляется возможность оплатить этот заказ по кнопке «Оплата заказа».

Как делать у нас: вызов POST /change/invoice/preview/ (03-scheta.md §3.4) создаёт счёт; на терминале PK этот счёт виден и оплачивается по кнопке. Отдельный push не нужен — терминал сам подхватывает.

2. Webhook’и на возвраты/отмены/коррекции

Вопрос: Сейчас виден только webhook «успешная оплата». Без webhook на возврат учёт расходится.

Ответ PK:

Есть webhook (callback) о возврате платежа. Включается техподдержкой PK для конкретного ЛК. Сигнатура вызова похожа на POST-уведомление об успешном платеже.

Как делать у нас:

  • Запросить у техподдержки PK включение callback о возвратах для нашего ЛК.
  • Для чеков (в т. ч. коррекций) есть отдельный callback при переходе в финальный статус: 08-rabota-s-chekami-54-fz.md §8.13 — POST с HMAC-SHA256 подписью по секретному слову.

3. GET /payments API для reconciliation

Вопрос: Нужен список платежей за период на случай потери webhook’а.

Ответ PK:

Есть несколько вариантов:

  • /export/payments/ (7.1) — файловые реестры
  • /info/payments/bydatecount/ (2.2) — количество платежей
  • /info/payments/bydate/ (2.1) — список платежей
  • /info/systems/sums/ (1.2) — суммы за период

Наиболее надёжный алгоритм: получать POST-уведомления (они настырно стучатся пока не дойдут), а раз в сутки контролировать платежи в статусе stuck («Совершён без оповещения») и адресно их загружать.

Как делать у нас:

4. Фискальные поля в webhook (ФН, ФД, ФП, номер смены)

Вопрос: Без них чеки в ERP не сопоставляются с ОФД для налоговой.

Ответ PK:

Все поля загружаются по API вызовам чека (8.1, 8.3, 8.4) или опций платежа (2.4 /info/options/byid/).

Как делать у нас:

  • В webhook успешной оплаты или после получения payment_id → §8.3 /info/receipts/bypaymentid/ или §8.4 /info/receipts/byid/.
  • Доступные фискальные атрибуты: fpd (ФПД), fnd (ФД), fn (ФН), ts (время), rnkkt (регистрационный номер ККТ), shift_number, receipt_number, fop_url (QR-контент).

5. API смен ФН (блокировка через 24ч, программное закрытие, webhook «смена скоро истечёт»)

Вопрос: Нужен статус смены + программное закрытие + оповещение о скором истечении.

Ответ PK:

Явно делать не требуется — кассовое приложение само закроет/откроет смену, если она истечёт.

Как делать у нас: ничего не делаем. Управление сменой — на стороне терминала PayKeeper.

6. Webhook на изменения каталога в ЛК PK

Вопрос: Когда владелец меняет цену или добавляет товар в ЛК PayKeeper, мы не узнаём — наш push перезатирает чужие правки.

Ответ PK:

Это в планах. Обсудим пожелания на колле, реализуем.

Как делать у нас:

  • Вынести на созвон: желаемая сигнатура webhook, события (catalog.item.updated, catalog.item.created, catalog.item.deleted), полезная нагрузка, таймаут/ретраи.
  • До появления webhook’а — либо дисциплинарно зафиксировать, что редактирование только в ERP, либо писать периодический diff-pull (нагрузочно).

7. Автоматизация онбординга ЛК

Вопрос: Три ручных шага при регистрации ТТ: polling готовности ЛК, ввод webhook URL вручную, copy-paste HMAC secret в админку.

Ответ PK:

На ранних этапах это несущественно (даже лучше первые интеграции делать вручную, чтобы понять какие настройки реально необходимы). В дальнейшем автоматизируется через API работы с настройками ЛК: запросы 4., 5..

Общая логика: всё что можно в ЛК вручную — можно и через API.

Как делать у нас:

Итоги для нашей интеграции

Ничего кастомного от PK не нужно для MVP:

  • #1 cross-device — уже работает через invoice API
  • #4 фискальные поля — уже доступны через 2.4 / 8.3 / 8.4
  • #5 смены — PK рулит сам

Просим включить / уточнить:

  • #2 callback на возвраты — запрос в техподдержку PK
  • #6 webhook каталога — обсуждаемо, на созвон

Откладываем на после MVP:

  • #3 reconciliation-cron на stuck-платежи
  • #7 автоматизация онбординга через 4./5.

Ссылки

  • 00-index.md — оглавление документации PK JSON API
  • [Business Requirements: PayKeeper partnership](../../07-Tasks/Business Requirements) — наш скоуп интеграции

Вид графа

Обратные ссылки