ERP Platform Docs

Overview

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

Paykeeper Adapter

Зона ответственности

Anti-corruption layer между ERP и внешним провайдером PayKeeper (приём платежей + фискализация 54-ФЗ + эквайринг). Мост «наш Order Service ↔ PK JSON API».

Сервис выполняет:

  1. Создание инвойсов — по событию order.payment_requested вызывает POST /change/invoice/preview/ в PK, возвращает URL для оплаты.
  2. Приём informer’ов — публичный webhook-endpoint на успешные оплаты и возвраты. MD5-валидация подписи (legacy PK-схема).
  3. Догрузка фискалки — после оплаты подтягивает ФН/ФД/ФП/смену через GET /info/receipts/bypaymentid/ или callback §8.13 (HMAC-SHA256).
  4. Возвраты — по order.refund_requested вызывает POST /change/payment/reverse/, дожидается webhook возврата.
  5. Reconciliation — per-invoice поллинг (25 мин + 5 мин интервал) + ночной cron stuck-платежей через POST /change/payment/repeatcnt/.
  6. Multi-tenant credentials — per-ЮЛ аккаунт (host, login, password, informer_seed). Шифрование AES-GCM.
  7. Outbox — гарантия at-least-once доставки исходящих команд в PK.
  8. Журнал событий — все входящие webhook’и и исходящие вызовы логируются для аудита.
  9. Синхронизация каталога в ЛК PK (BR 3.4) — consume Kafka-событий catalog.product.* / catalog.modifier_group.*, развёртывание товаров с модификаторами в виртуальные PK-продукты (категории в prefix имени, структурные опции как отдельные варианты, свободные опции как addon-товары), upsert/delete через PK ims-api (https://ims-api.paykeeper.ru/api/v1), ведение paykeeper_products mapping’а с поддержкой reverse lookup для будущего webhook’а PK. Ночной cron full re-sync + manual re-sync через админку. См. Catalog Sync и BR 3.4.
  10. Импорт сотрудников из ЛК PK (BR 3.5) — по требованию владельца запрос GET /info/organization/users/ в PK, формирование диффа с employees через GET /internal/users/by-email, wizard дозаполнения недостающих полей и пакетный импорт через POST /api/v1/employees. Ведение mapping’а paykeeper_users (employee ↔ pk_user) — используется для построения отчётов «выручка по кассиру» при получении чеков от PK. См. Импорт сотрудников из PayKeeper и BR 3.5.

P0 scope

Текущая фаза — только базовая платёжная петля. Push сотрудников ERP → ЛК PK (BR 3.6), autoinstaller, post-sale receipt, SBP QR, 2-stage hold — отложены (см. PayKeeper · Что НЕ входит). Catalog sync (BR 3.4) и pull сотрудников из ЛК PK (BR 3.5) — в скоупе.

Функции

  • CRUD PK-аккаунтов (per-ЮЛ) с шифрованием секретов.
  • CRUD привязок «наша ТТ ↔ терминал PK».
  • HTTP-клиент PK JSON API: Basic auth + security token 24ч (кэш).
  • Webhook-receiver для informer success / refund / receipt callback.
  • Outbox-worker для исходящих команд.
  • Kafka producer/consumer для cross-сервисной интеграции.
  • Per-invoice scheduler для reconciliation.
  • Ночной cron stuck-платежей.
  • Pull-импорт пользователей из ЛК PK (manual, по нажатию кнопки в админке) — wizard дозаполнения и пакетное создание employees.

Ролевой доступ

ОперацияPermission
Создать / редактировать PK-аккаунтintegrations.manage
Просмотр PK-аккаунтов и журналаintegrations.read
Привязать ТТ к терминалу PKintegrations.manage
Проверить соединение (тестовый запрос токена)integrations.manage
Инициировать возврат (из админки)orders.refund
Импорт сотрудников из ЛК PK (BR 3.5)integrations.manage AND employees.edit

Зависимости

  • User Service (HTTP /internal/legal-entities/{id}) — валидация ЮЛ при создании PK-аккаунта; резолв legal_entity_id → franchise_id для catalog sync routing (BR 3.4); GET /internal/users/by-email (lookup при матче кандидатов из ЛК PK) + POST /api/v1/employees / PATCH /api/v1/employees/{id} (создание/обновление при импорте) (BR 3.5).
  • Store Service (HTTP /internal/stores/{id}) — валидация ТТ при создании привязки терминала.
  • Order Service — consumer событий order.payment_requested / order.refund_requested; publisher paykeeper.payment.received / paykeeper.payment.refunded / paykeeper.receipt.fiscalized.
  • Catalog Service (BR 3.4) — consumer 4 событий catalog.product.* + catalog.modifier_group.*; HTTP GET /internal/catalog/products/{id}/expand (per-product развёртка при delta-sync) и GET /internal/catalog/full-snapshot?franchise_id=X (для cron и manual re-sync).
  • Auth Service — валидация внутренних токенов.
  • Kafka — transport событий.
  • Redis — кэш security token’ов PK (TTL 24ч), rate-limit’ов per-account, кэш legal_entity_id → franchise_id (TTL 5 мин) (BR 3.4).
  • PayKeeper JSON API — исходящие вызовы в PK ({tsp}.server.paykeeper.ru/* — платежи / инвойсы / возвраты / чеки).
  • PayKeeper ims-api (BR 3.4) — исходящие вызовы для синхронизации каталога на отдельный глобальный хост https://ims-api.paykeeper.ru/api/v1. Auth — отдельный JWT через GET /info/settings/service-token?service=ims-api.paykeeper.ru&user={login} на {tsp}.server.paykeeper.ru. Endpoints: POST /products, GET /product/{id}, GET /products, PATCH /product/{id}, DELETE /product/{id}.

Конфигурация

ПеременнаяЗначение
PORT3015
POSTGRES_URLpaykeeper_adapter_db схема в общем кластере
KAFKA_BROKERSобщий брокер
USER_SERVICE_URL, STORE_SERVICE_URL, ORDER_SERVICE_URLдля межсервисных вызовов
SERVICE_TOKENдля X-Service-Token
PAYKEEPER_SECRETS_KEYAES-GCM ключ (32 байта, base64) для шифрования pk_password/informer_seed
REDIS_URLдля кэша токенов
WEBHOOK_BASE_URLпубличный URL для формирования webhook endpoint’ов (например https://erp-test.nirbi.ru)
PK_CLIENT_TIMEOUT_MSтаймаут исходящих HTTP (default 30000)
PK_CLIENT_RETRY_ATTEMPTSколичество retry (default 3)
RECONCILE_CRON0 0 3 * * ? — ночной cron платежей
CATALOG_SERVICE_URLhttp://catalog-service:3004 — для snapshot и expand (BR 3.4)
CATALOG_SYNC_CRON0 0 3 * * ? — ночной catalog full re-sync (BR 3.4)
PK_IMS_API_BASEhttps://ims-api.paykeeper.ru/api/v1 — база ims-api (одна на всех мерчантов) (BR 3.4)
PK_IMS_SERVICE_IDims-api.paykeeper.ru — параметр service при получении JWT через /info/settings/service-token (BR 3.4)
CATALOG_SYNC_BATCH_SIZE50 — товаров в одном batch при full re-sync (BR 3.4)
CATALOG_SYNC_THROTTLE_US500 — sleep μs между write-запросами в ims-api (BR 3.4, эмпирика Koala)

Ссылки

Вид графа

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