ERP Platform Docs

Требования к PayKeeper

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

Требования к PayKeeper

Что должно быть на стороне PK, чтобы наша интеграция (Касса 3-в-1 + наш ERP надстройкой) работала. Только их зона ответственности — наши доработки сюда не входят.

TL;DR

2 блокера до MVP — reverse webhook каталога и webhook’и о статусах invoice. 2 пункта для среднего запуска (10+ ТТ). 6 пунктов на вырост (P2/P3).

Связанные документы:

Чек-лист

Колонки: запрошено (написали в PK) → подтверждено (приняли в работу с ETA) → готово (поставлено в прод).

🔴 До MVP

#ПунктЗапрошеноПодтвержденоГотово
1.1Reverse webhook каталога (PK → ERP)[ ][ ][ ]
1.2Webhook’и о статусах invoice[ ][ ][ ]

🟡 До 10+ ТТ

#ПунктЗапрошеноПодтвержденоГотово
2.2Идемпотентность webhook’ов (event_id)[ ][ ][ ]
2.4Webhook о доступности кассы в ТТ[ ][ ][ ]

🟢 На вырост (P2/P3)

#ПунктЗапрошеноПодтвержденоГотово
3.1Webhook закрытия смены с агрегатами[ ][ ][ ]
3.2API программного онбординга ЛК[ ][ ][ ]
3.3Расширенный IMS API (картинки, ШК, ТРУ-коды)[ ][ ][ ]
3.42-stage платежи (pre-auth + capture)[ ][ ][ ]
3.5Webhook смены настроек ЛК (security)[ ][ ][ ]
3.7API выплат (payouts) для лояльности[ ][ ][ ]

Раскрытие пунктов

1.1. Reverse webhook каталога

Что нужно: webhook от PK когда товар, цена или налог поменялись в ЛК PayKeeper руками владельца / кассира.

Зачем: сейчас sync только в одну сторону (ERP → PK). Если кто-то правит в ЛК PK — наш ночной push затрёт правки.

Payload (предложение): {event_id, account_id, pk_product_id, fields_changed[], old_values, new_values, ts}

Канал: партнёрский менеджер / roadmap.

Текущий статус у PK: в обсуждении, ETA не подтверждён.

Наша готовность: в paykeeper_product_mapping уже храним pk_product_id UNIQUE для reverse lookup.

1.2. Webhook’и о статусах invoice

Что нужно: уведомления о промежуточных и финальных статусах счёта:

  • invoice.expired — истёк TTL
  • invoice.cancelled — отменён клиентом или кассиром
  • invoice.failed — отказ эквайринга

Зачем: сейчас приходит только informer на успешную оплату. Если invoice не оплатили — заказ зависает в awaiting_payment навсегда, кассир не понимает можно ли его пробить заново.

Альтернатива: pull-API GET /info/invoices/byid/?status=expired,cancelled,failed — приемлемо, но webhook надёжнее и быстрее.

Канал: партнёрский менеджер.

2.2. Идемпотентность webhook’ов

Что нужно: уникальный event_id (UUID) в каждом webhook payload — для дедупа на нашей стороне.

Зачем: PK ретраит доставку при сетевых ошибках. Без event_id рискуем считать повторную доставку отдельным событием → дубль в учёте. Сейчас дедупим по (account_id, pk_payment_id) — рискованно для refund’ов и при множественных webhook’ах по одному платежу.

Канал: техподдержка PK.

Совместимость: должно быть обратно-совместимо — добавить новое поле, не ломая существующих consumer’ов.

2.4. Webhook о доступности кассы в ТТ

Что нужно: уведомление от облака PK о статусе физической кассы 3-в-1 в торговой точке (online, offline, paper_out, connection_lost).

Зачем: мы напрямую с кассой в ТТ не общаемся — только через облако PK. Heartbeat кассы знает только облако. Без этого webhook’а кассир в ТТ узнаёт о проблеме только когда клиент уже стоит у бара.

Архитектура связи:

наш POS → invoice → облако PK → касса 3-в-1 в ТТ
                       ↑
                    heartbeat (только PK видит)

Канал: партнёрский менеджер / архитектор PK.

Альтернатива: pull GET /info/terminals/{id}/status раз в минуту — нагрузка на их API при 50+ ТТ.

3.1. Webhook закрытия смены с агрегатами

Что нужно: webhook shift.closed с агрегатами:

{
  "event_id": "uuid",
  "account_id": "...",
  "terminal_id": "...",
  "shift_number": 42,
  "user_login": "barista_anna",
  "opened_at": "...",
  "closed_at": "...",
  "receipts_count": 87,
  "total_revenue": { "card": 45000, "cash": 12000, "sbp": 8000 },
  "z_report_url": "..."
}

Зачем: для read-only вкладки «Смены» в админке. Сейчас агрегируем сами по shift_number из чеков — медленно и неточно (если потеряли часть webhook’ов).

Альтернатива: агрегация на нашей стороне из paykeeper_receipts — приемлемо в P1, не критично.

3.2. API программного онбординга ЛК

Что нужно: API endpoints для автоматизации создания нового ЛК PK:

  • POST /partner/accounts → возвращает credentials нового ЛК
  • POST /partner/accounts/{id}/terminals → регистрация терминалов
  • POST /partner/accounts/{id}/webhooks → настройка webhook URL и secret
  • GET /partner/accounts/{id}/status → проверка готовности

Зачем: сейчас при подключении новой франшизы → ручная регистрация в PK через их сайт + ручное копирование credentials в наш wizard. Хочется: владелец вводит данные ЮЛ в нашей админке → автоматически создаётся ЛК PK без переключений.

Канал: партнёрский договор + API партнёра.

Текущий статус: partner-api.yaml есть в _reference/paykeeper/, но endpoints онбординга не покрывают.

3.3. Расширенный IMS API для каталога

Что нужно: добавить в POST /products поля:

  • image_url — картинка товара (URL или multipart upload)
  • barcode — штрих-код EAN-13 / EAN-8
  • mark_code — код Честного Знака (ТРУ-код, обязателен с 2027 для общепита по ряду категорий)
  • vendor_code — артикул

Зачем:

  • Картинки — кассир в ЛК PK видит товар визуально, меньше ошибок выбора
  • Штрих-код — для быстрого добавления товара в чек сканером
  • ТРУ-код — обязательное законодательное требование с 2027

Канал: roadmap PK.

Срочность: до 2027-01 если франшизы подпадают под обязательную маркировку.

3.4. 2-stage платежи (pre-auth + capture)

Что нужно: разделение платежа на два этапа:

  • POST /change/payment/hold — резервирование суммы на карте клиента
  • POST /change/payment/capture — фактическое списание (возможно меньше hold’а)
  • POST /change/payment/release — отмена резерва

Зачем:

  • Бронирование: резервируем 5000 ₽ при бронировании столика → списываем по факту прихода (или возвращаем при отмене)
  • Delivery: резерв при оформлении заказа → списание при выдаче курьеру
  • Открытый счёт: резерв при открытии счёта в баре → финальное списание при закрытии

Канал: roadmap PK.

Текущее: только 1-stage (мгновенное списание).

3.5. Webhook смены настроек ЛК (security)

Что нужно: webhook / email-alert когда в ЛК PK кто-то меняет critical-настройки:

  • Webhook URL (informer / refund / receipt)
  • Webhook secret / informer_seed
  • Доступ к API (создание новых API-ключей)
  • Удаление / изменение терминала

Зачем: если кто-то получил доступ к ЛК и поменял webhook URL — мы узнаём только когда платежи перестают доходить. К этому моменту атакующий уже принимает оплаты на свой URL. Превентивный alert критичен для безопасности.

Канал: security-команда PK.

3.7. API выплат (payouts)

Что нужно: POST /partner/payouts — выплата средств клиенту напрямую на карту:

  • По привязанной карте (bank_id)
  • По номеру карты (для возвратов клиентам без аккаунта)

Зачем:

  • Лояльность: кэшбек 5% на карту клиента после покупки
  • Реферальные бонусы: 500 ₽ на карту за приглашённого друга
  • Компенсации: возврат «доброй воли» если клиент пожаловался на качество

Канал: есть _reference/paykeeper/api-vyplat.yaml, но в текущей интеграции не используется. Нужно подтвердить готовность их сервиса выплат к нашему сценарию (комиссия, лимиты, KYC требования).

Журнал изменений

ДатаЧто изменилось
2026-04-27Создан документ. Список после фильтрации (изначально было 20 пунктов, оставлено 11).
2026-04-27Удалён пункт 2.5 (retry-policy webhook’ов). Осталось 10 пунктов.
2026-04-27Перенесены 2.1 → 1.1 (reverse webhook каталога) и 2.3 → 1.2 (статусы invoice) в блокеры MVP.

Вид графа

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