Appearance
Карта документации
mock-services — открытый тестовый стенд: моки банков-эквайрингов, облачных касс и ОФД по официальным протоколам провайдеров. Стенд нужен, чтобы проверить платёжную и фискальную интеграцию до договора с провайдером — с честными схемами, кодами ошибок, сценариями отказов и подсказками «что не так в запросе».
Этот раздел — точка входа: что читать по порядку, где лежит документация по каждому провайдеру и как устроен репозиторий.
пометки VERIFY и FORK
В документации встречаются пометки [VERIFY] и [FORK] — они помогают отличить проверенные факты от допущений:
[VERIFY]— деталь не проверена по официальной документации провайдера: публичный срез не раскрывает поле, схему, статус или поведение. Мок делает консервативное допущение, которое нужно пересверить при получении доступа к кабинету/тест-контуру. Такие места перечислены в гайде провайдера и вservices/<name>-mock/README.md.[FORK]— сознательное отличие мока от формулировки/поведения провайдера, зафиксированное как документированный форк. Причина: противоречие в срезе, отсутствие публичной спеки, локальная конвенция стенда (например, синтетические тестовые карты, cursor как индекс, повторный Login выдаёт новый marker). Форк не является утверждением о протоколе — перед переносом в production сверьте с официальной докой.
Легенда вынесена сюда, чтобы не повторять её в каждом гайде. В тексте пометки оставлены как есть, но теперь они ссылаются на этот раздел.
С чего начать
- Быстрый старт — поднять стенд:
docker compose up(все десять сервисов) илиnpm run start:<сервис>без Docker (нужен только Node ≥ 18). - Интеграция за 10 минут по вашему провайдеру — таблицы ниже. Гайд ведёт от
getToken/Initдо первого успешного платежа или чека и объясняет, что мок проверит за вас. - Справочник провайдера — когда нужны детали: поля, подписи, статусы, официальные разделы документации и что именно снято с первоисточника.
- OpenAPI 3.1 — машинкочитаемые спецификации каждого сервиса: ссылки в таблицах выше, на живом стенде —
GET /openapi.json.
Банки — эквайринг
| Провайдер | Что эмулирует | Порт | Документы |
|---|---|---|---|
| Т-Банк | EACQ: Init → платёжная форма → нотификации → Confirm/Cancel; Мультирасчёты (сделки, выплаты e2c), СБП QR, рекурренты, чарджбэки, верификация счетов (AV) | 3100 | гайд · справочник — конспект в приватном mock-services-docs · OpenAPI |
| ЮKassa | REST /v3: Basic Auth + Idempotence-Key, two-stage с частичным capture, возвраты, confirmation-страница, вебхуки | 3102 | гайд · справочник — конспект в приватном mock-services-docs |
| Альфа-Банк | интернет-эквайринг REST /payment/rest/*.do: register/registerPreAuth → formUrl, deposit ≤ холда, reverse, refund, callback HTTP GET с checksum HMAC-SHA256 | 3104 | гайд · справочник — конспект в приватном mock-services-docs · OpenAPI |
| Сбербанк | Ecom REST v1.1.11.1 /ecomm/gw/partner/api/v1/*.do: register, форма и ACS 111111, deposit/reverse/refund/decline, callback JSON с ACK 200 и retry | 3105 | гайд · справочник — конспект в приватном mock-services-docs · OpenAPI |
| ВТБ | SMB E-commerce API /openapi/smb/efcp/e-commerce/v1/: OAuth 2.0 client_credentials, orders/preauth/complete/cancel/refunds, ордер живёт 20 минут | 3106 | гайд · справочник — конспект в приватном mock-services-docs · OpenAPI |
Кассы и ОФД
| Провайдер | Что эмулирует | Порт | Документы |
|---|---|---|---|
| OFD Ferma | облачная касса по 54-ФЗ: sell/buy с возвратами и коррекциями, авансы и зачёты, маркировка «Честный ЗНАК», очередь ОФД, смены ККТ 24 ч и Z-отчёты, ресурс ФН | 3101 | гайд · справочник — конспект в приватном mock-services-docs · OpenAPI |
| АТОЛ Онлайн | direct API v4 (ФФД 1.05): getToken на 24 ч, шесть операций фискализации, идемпотентность external_id, отчёт wait → done|fail с ФД/ФП | 3103 | гайд · справочник — конспект в приватном mock-services-docs · OpenAPI |
| Первый ОФД (OKassa) | асинхронная очередь заявок /api/external/queue/v1/transaction/{type} → requestId, статусы IN_PROGRESS → COMPLETED|ERROR, сверка чеков за период | 3107 | гайд · справочник — конспект в приватном mock-services-docs · OpenAPI |
| Контур.ОФД | чтение и сверка: Sid + API key, организации, кассы, фискальные документы (суммы в копейках) — без создания чека | 3108 | гайд · справочник — конспект в приватном mock-services-docs · OpenAPI |
| Такском | read-only кабинет/ОФД, API v2: POST /API/v2/Login с Integrator-ID → Session-Token на 5 минут, AccountList, NewDocuments за 10 суток | 3109 | гайд · справочник — конспект в приватном mock-services-docs · OpenAPI |
Read-only адаптеры (Контур.ОФД, Такском) не умеют создавать чеки: они предназначены для сверки уже пробитых документов. Write API Такскома не моделируется.
Как устроена документация
| Слой | Где лежит | Для чего |
|---|---|---|
| Гайды «за 10 минут» | docs/integration/ | Поднять сервис, провести первый платёж/чек, увидеть сценарии отказов |
| Справочники провайдеров | приватный репозиторий mock-services-docs (каталог <provider>/) | Конспект официальной доки: эндпоинты, поля, подписи, статусы, даты сверки |
| OpenAPI 3.1 | docs/openapi/ | Машинкочитаемые спецификации; на живом стенде — GET /openapi.json |
| Манифесты протоколов | protocols/<provider>.json | Декларация операций для детектора дрейфа (npm run check:drift) |
| Сервисы | services/<provider>-mock/ | Env-переменные, эндпоинты управления (/mock/*), сценарии, журнал |
| Ядро | packages/core/ | Общая инфраструктура адаптеров: ошибки, часы, песочницы, вебхуки |
| Проект | CONTRIBUTING · SECURITY · RFC-001 | Правила вклада, модель угроз и требования к развёртыванию |
Что полезно знать перед интеграцией
- Это не продакшен и не drop-in. Мок повторяет клиентский контракт провайдера, но одной смены URL для перехода в бой недостаточно: проверьте конфигурацию, безопасность и условия интеграции.
- Ошибка — это подсказка. Любой отказ мока содержит код, человекочитаемое объяснение, проблемное поле и ссылку на официальный раздел документации.
- Сценарии отказов переключаются. Недостаток средств, таймаут, дубль вебхука, чарджбэк, отказ ККТ — сценарием или переменной окружения, а не «ждём боевой инцидент».
- Виртуальные часы.
POST /mock/timeдвигает время стенда: TTL токенов, смены 24 ч, устаревание резерва ФН и retry вебхуков проверяются без ожидания. - Развёртывание наружу. Порты по умолчанию слушают
127.0.0.1; для публичного стенда обязательныMOCK_HOSTED=1, токены/mock/*и админки, TLS и egress-фильтр — см. SECURITY.
Вне публичного периметра
Часть проектной документации в этом репозитории не публикуется и живёт в закрытом mock-services-docs[^private]. Не публикуются внутренние аудиты[^audit], брифы доработок[^brief] и карточки проектов[^canon]. Если в тексте (или на другой странице) встречается сноска на документ без ссылки — значит, документ существует, но доступен только команде; публичная часть документации при этом самодостаточна.
Ссылки на официальные источники провайдеров собраны в конспектах провайдеров — в приватном репозитории mock-services-docs.
Репозиторий: github.com/rucorp/mock-services · Лицензия Apache-2.0 · © 2026 ООО «Аксиома»
[^private]: Закрытый репозиторий команды rucorp/mock-services-docs — доступ у мейнтейнеров. [^audit]: docs/audit/AUDIT-2026-10-08.md — внутренний аудит репозитория перед публикацией. [^brief]: docs/briefs/CLAUDE-2026-10-12-agent-brief.md — очередь доработок и статусы задач. [^canon]: docs/canon/MOCK_SERVICES_SPEC.md, docs/canon/T-038-fiscalization-54fz.md — внутренние спеки и карточки проектов.