Paykeeper × наш ERP — что делаем, что нужно от вас
Документ написан простым языком — без технических деталей. Для обсуждения границ интеграции.
Коротко о ролях
Paykeeper — приём оплаты и фискализация. Ваш терминал принимает карту / SBP / наличные, ваша касса (ФН) пробивает чек, ваш ОФД отправляет его в налоговую.
Наш ERP — всё что вокруг платежа. Каталог меню, модификаторы, цены по точкам, стоп-листы, склад с техкартами, сотрудники и их права, заказы, смены, зарплата, отчёты и аналитика.
Мы не делаем своё фискальное решение — делегируем это вам. Вы не делаете учёт и меню — делегируете это нам. Пересекаемся только в точке «платёж прошёл».
Что стыкуется уже сейчас
Большая часть платёжной петли работает без доработок с обеих сторон:
- Кассир проводит оплату на вашем терминале — вы присылаете нам уведомление, мы закрываем заказ у себя.
- Чек формируется у вас (54-ФЗ, ФН, ОФД) — вы отдаёте нам ссылку, клиент видит чек.
- Справочник товаров — передаём вам базовый набор (название, цена, ставка НДС, тип товара, единица, штрихкод, маркировка «Честный знак»).
- Справочник кассиров — когда мы заводим сотрудника с правом работы на кассе, зеркалим его в ваш ЛК.
- Способы оплаты — карта, SBP, наличные, ApplePay, MirPay — всё на вашей стороне.
- Возврат платежа — кассир нажимает на терминале, возврат проходит через вас.
- Выплаты физлицам (курьеры, сборщики, самозанятые) — можно делать через ваш OCT API, если понадобится.
Что мы сами доделаем на своей стороне
Это наш фронт работ, вам ничего делать не нужно:
- Добавим в карточку товара обязательные для вас поля: ставка НДС, тип товара по 54-ФЗ, уточнение единицы измерения когда наша не маппится на вашу.
- Добавим в админку раздел «Интеграции → Paykeeper» — туда владелец франшизы пропишет адрес ЛК, логин сервисного пользователя, секретное слово для подписи уведомлений, привяжет свои торговые точки к вашим терминалам.
- Построим отдельный сервис-«переводчик» между нашим ERP и вашим API, чтобы изменения в каталоге/сотрудниках автоматически улетали к вам, а ваши уведомления о платежах разлетались по нашим сервисам.
Что нам нужно от вас
Сгруппировали по критичности: без какого функционала запуск невозможен (P0), что сильно осложняет жизнь (P1), что было бы хорошо иметь (P2).
БЛОКИРУЮЩЕЕ (P0) — без этого интеграция не поедет
1. Модификаторы товара
У нас: товар редко продаётся «как есть». Капучино бывает маленький/большой, с сиропом или без, с добавкой эспрессо-шота. У одного товара — несколько групп модификаторов, у каждой группы — список опций со своими ценами.
У вас: модификаторов не существует. Товар в каталоге — плоская штука с одной ценой.
Что мы делаем сейчас: когда кассир инициирует оплату из нашего приложения — передаём вам «готовую корзину» с финальными позициями (например, Капучино M + сироп лесной орех — 380 ₽ одной строкой).
Что не работает: кассир не может взять ваш терминал «как есть» и пробить заказ с модификаторами — в вашем каталоге он видит только плоские позиции. Сценарий «терминал как самостоятельная касса» невозможен.
Что нужно от вас: поддержка модификаторов в каталоге и в экране выбора товара на mPOS.
2. Иерархия категорий
У нас: меню — это дерево. «Напитки → Кофе → Горячие → Эспрессо-напитки → Капучино». До 4-5 уровней. Бариста привык к такой навигации.
У вас: теги — плоский список, без родительских связей.
Что мы можем делать сейчас: схлопывать путь в одну строку — «Напитки / Кофе / Горячие / Капучино». Но в вашем интерфейсе это выглядит мусорно, и при любом переименовании категории в нашем ERP нужно перегенерировать все теги.
Что нужно от вас: родительская связь у тегов + отображение дерева в UI ЛК.
3. Разные цены для разных точек
У нас: капучино в Москве стоит 300 ₽, в Петербурге — 260 ₽, в Ростове — 220 ₽. У одной франшизы может быть несколько прейскурантов, каждая ТТ работает по одному из них.
У вас: одна цена на товар на весь ТСП.
Что мы делаем сейчас: передаём актуальную цену в каждом запросе на оплату. Но если открыть ваш каталог напрямую — видна только «глобальная» цена, которая никому не соответствует.
Что нужно от вас: возможность завести несколько прейскурантов и назначить их на терминалы.
4. Стоп-листы и «товар доступен только в этих точках»
У нас:
- Капучино временно закончился в точке на Арбате → его нельзя продавать только там, в других точках — можно.
- Эксклюзивный десерт продаётся только в двух флагманских ТТ из двадцати.
У вас: товар либо виден на всех терминалах, либо ни на одном.
Что не работает: мы не можем оперативно снять товар с продажи в одной точке. Любое точечное ограничение нужно делать «вручную» в каждой точке отдельно.
Что нужно от вас: список терминалов (или ТТ), в которых товар доступен, + быстрый способ включить/выключить товар на точке без переливки всего каталога.
5. Роли и разграничение доступа в ЛК
У нас: гибкая система прав. Создаём роль «Менеджер зала» с галочками «может смотреть отчёты своей ТТ, может снимать товар со стоп-листа, не может редактировать меню». И пачка таких ролей на разных сотрудников.
У вас: на пользователе есть несколько булевых флажков («админ», «может делать возвраты», «видит только свои платежи»). Нет ролей как отдельного объекта. Нет привязки пользователя к конкретным терминалам.
Что не работает:
- Кассир одной ТТ видит платежи другой ТТ того же ТСП — нарушение периметра.
- Нельзя выдать менеджеру права «видит только свою точку» — только либо всё, либо ничего своё.
Что нужно от вас:
- Роли как настраиваемые наборы прав.
- Привязка пользователя к конкретным терминалам (чтобы кассир на Арбате не видел платежи с Ленинского).
6. Уведомления о возвратах, отменах и корректировках
У нас: в отчёте должны быть видны не только продажи, но и возвраты, отмены, чеки коррекции — с привязкой к сотруднику и точке.
У вас: уведомление приходит только об успешной оплате. О том, что кассир оформил возврат — нам ничего не падает.
Что не работает: мы узнаём о возврате только из ручной выгрузки выписки из ЛК или при сверке раз в сутки. Между возвратом и его попаданием в наш учёт проходят часы.
Что нужно от вас: уведомления на наш сервер по типам событий:
- Возврат прошёл успешно / неуспешно
- Клиент не оплатил (закрыл экран mPOS)
- Пробит чек коррекции по предписанию ФНС
7. Выгрузка списка платежей за период
Зачем: если ваше уведомление до нас не дошло (сеть упала, сервер был на рестарте) — нам нужен способ «досверить» и подтянуть пропущенное.
У вас: такой ручки нет (по крайней мере, в открытой документации).
Что нужно от вас: метод вида «дай все платежи с такого-то по такое-то время с полной информацией» — чтобы наш сервис мог раз в несколько минут автоматически сверяться.
8. Тестовая среда
Что есть: продакшн.
Что нужно:
- Отдельный тестовый ЛК, где ничего не пробивается в реальный ОФД.
- Возможность из админки «симулировать» успешный платёж с тестового терминала (чтобы наши разработчики проверяли сценарий без реальных карт).
- Тестовые карты / тестовые SBP-операции.
Без этого мы не можем полноценно тестировать интеграцию ни в CI, ни при подключении нового партнёра-франчайзи.
СИЛЬНО ОСЛОЖНЯЕТ (P1) — можно жить, но больно
9. Внятные ошибки при импорте каталога
При массовой загрузке каталога вы возвращаете только счётчики: «добавлено 497, пропущено 0, ошибок 3». А какие именно три — непонятно. Приходится переотправлять товары по одному чтобы найти проблемные.
Нужно: список конкретных строк, которые не прошли, с причиной.
10. Фискальные данные в уведомлении о платеже
Сейчас в уведомлении есть идентификатор платежа и ключ для ссылки на чек. Нет: номера ФН, номера ФД (фискального документа), фискального признака, номера чека в смене, номера смены.
Эти данные нужны:
- Для внутреннего реестра (наша бухгалтерия / налоговый аудит).
- Для сопоставления с выпиской ОФД когда что-то не сошлось.
11. Управление сменой ФН
По 54-ФЗ смена на кассе не может идти больше 24 часов — иначе ФН блокируется и ТТ встаёт. Сейчас у нас нет способа:
- Узнать что смена открыта / сколько ей ещё работать.
- Принудительно закрыть смену программно (если менеджер забыл).
- Получить предупреждение за час до 24-часового лимита.
Что нужно: ручка «статус смены на терминале» + принудительное закрытие + уведомление о приближении лимита. Иначе мы узнаём о блокировке кассы только когда кассир звонит и говорит «не работает».
12. Границы ЛК: один ЛК = что?
Открытый вопрос, от ответа зависит архитектура.
Один личный кабинет Paykeeper покрывает:
- один терминал?
- одну торговую точку (с несколькими терминалами)?
- одно юридическое лицо (с несколькими ТТ)?
- всю франшизу (с несколькими юрлицами)?
Если, например, у франчайзи два ЮЛ и пять точек — ему заводить один ЛК или пять? Это влияет на то, как регистрировать нового партнёра-франчайзи и где хранить его учётные данные у нас.
Что нужно: документированный стандартный вариант + обоснование.
13. Весовой товар и ручная цена на кассе
У нас:
- Торт по весу — кассир ставит на весы, вводит граммы, цена считается автоматически.
- «Свободная цена» — цена вбивается на кассе (например, индивидуальные заказы).
У вас: есть price_can_be_changed — близко к «свободной цене», но непонятно как на mPOS вводится вес с весов.
Что нужно: флаг «весовой товар» + сценарий ввода веса на терминале (хотя бы ручной).
14. Регуляторика: алкоголь, табак
У нас: товар помечен как алкогольный / табачный / сахаросодержащий.
У вас: нет таких флагов.
Что нужно (минимум): флаги + предупреждение на mPOS «требуется проверка возраста» / «продажа разрешена с 08:00 до 23:00». Для алкоголя отдельно — позиция: кто ведёт ЕГАИС (УТМ). Если вы — расскажите как. Если мы — что передавать вам, чтобы ваш чек был совместим с ЕГАИС.
ХОРОШО БЫ ИМЕТЬ (P2) — не блокирует, но упростит жизнь
15. Альтернатива CSRF-токену для сервисных вызовов
Сейчас перед каждым POST в ЛК наш сервис делает отдельный GET за CSRF-токеном. Для автоматизации это лишний round-trip. Хотелось бы сервисный API-токен, который не требует CSRF.
16. Rate limits
Нет документированных лимитов на частоту запросов. Если наш сервис начнёт лить быстро — неизвестно, когда упрёмся в бан. Нужны заголовки X-RateLimit-* и HTTP 429 с Retry-After.
Что получится если оставить «как есть»
Даже со всеми разрывами базовая интеграция заработает, но с серьёзными ограничениями:
| Что не работает | Почему |
|---|---|
| Кассир не может оформить заказ на терминале «напрямую» | Нет модификаторов, нет иерархии, нет правильных цен |
| Быстро снять товар с продажи в одной ТТ | Нет стоп-листов per-store |
| Менеджер видит только свою точку | Нет разграничения в ЛК |
| Real-time учёт возвратов | Нет webhook о возврате |
| Полный фискальный реестр у нас | Нет ФН/ФД/ФП в уведомлении |
| Гарантия что ничего не потеряли | Нет API для сверки |
| Предупреждение о переполнении смены | Нет API смены |
| Автоматические тесты интеграции | Нет sandbox |
Минимальный сценарий который работает сегодня: все платежи инициируются только из нашего приложения, терминал PK — это только «плати-и-печатай чек», никакой самостоятельной работы.
Приоритеты для встречи
Хотелось бы обсудить в первую очередь:
- Модификаторы (P0 №1) — без этого вся концепция «терминал как часть POS» не работает.
- Webhooks возвратов и корректировок (P0 №6) — без них учёт перестаёт сходиться в реальном времени.
- Sandbox (P0 №8) — блокирует подключение разработки, нам некуда деплоить.
- Multi-tenancy (P1 №12) — от ответа зависит как мы будем регистрировать новых франчайзи.
- Смены ФН (P1 №11) — риск внезапной остановки ТТ.
Остальное можно обсудить вторым этапом — оно тоже важное, но не блокирующее запуск пилота.
Ссылки
- Технический gap-анализ:
_assets/paykeeper/gap-analysis.md - Презентация по архитектуре интеграции:
_assets/paykeeper/presentation.html - OpenAPI-спеки Paykeeper:
_assets/paykeeper/