Интеграции, API и мобильные приложения

Статус: проектирование объёма (задаёт верхнюю границу возможностей). Все интеграции — модули поверх абстрактных слоёв ядра. Ядро даёт API, шину событий и абстракции (платёж/доставка/CRM); конкретные коннекторы (ЮKassa, СДЭК, 1С) — включаемые модули.

Принцип: абстрактный слой в ядре, коннекторы — модули

Ключ к расширяемости интеграций — не хардкодить провайдеров. Ядро определяет абстрактный контракт, модуль-коннектор его реализует:

• Платежи: контракт PaymentGateway (pay/capture/refund/status/callback) + единая модель транзакции. Коннекторы (ЮKassa, Тинькофф, СБП, крипта) — модули.
• Доставка: контракт DeliveryProvider (calculate/createShipment/track/pickupPoints)
  • единая модель тарифа. Коннекторы (СДЭК, Почта, Boxberry) — модули.
• CRM/ERP: контракт обмена + очередь синхронизации. Коннекторы (Битрикс24, amoCRM, 1С) — модули.

Так добавление нового шлюза — это новый модуль, а не правка ядра. И сайт включает только те коннекторы, что использует.

API-слой (в ядре)

Ядро headless-ready: любая сущность доступна по API. Это фундамент для мобильных приложений, внешних интеграций и React-кабинетов.

Возможность	Описание
REST API	CRUD всех сущностей, единый формат, пагинация/сортировка/фильтрация, sparse fieldsets
GraphQL	Эндпоинт с интроспекцией, батчинг, лимиты глубины/сложности запроса
Версионирование	URL-версии (/v1, /v2), deprecation-политика, sunset-заголовки
OpenAPI/Swagger	Спецификация, автоген SDK, интерактивная песочница (Swagger UI / GraphiQL)
Content Delivery API	Только чтение, кешируемое — отдельно от Management API (запись, авторизация)
Preview API	Черновики/отложенные публикации для headless-превью
Безопасность API	Rate-limit и квоты per-token, API-ключи со scope, OAuth2 client credentials

Вебхуки

Тип	Описание
Исходящие	На события (сущность создана/изменена, статус заказа, оплата, регистрация)
Входящие	Колбэки от платёжек/доставки/маркетплейсов, валидация источника
Подпись	HMAC-SHA256, секрет на подписку, проверка timestamp против replay
Надёжность	Ретраи с экспон. задержкой, dead-letter, идемпотентность по event-id
Наблюдаемость	Журнал доставки, ручная переотправка, тестовая отправка из админки

Платёжные шлюзы

Единый абстрактный слой + коннекторы-модули:

Шлюз	Особенности
ЮKassa	REST, чеки 54-ФЗ, СБП, рекуррент, холдирование
Тинькофф (T-Bank)	Init/Confirm/Cancel, привязка карт, рекуррент, безопасная сделка
Робокасса	Подпись MD5/SHA, фискализация, подписки
СБП	QR (статический/динамический), C2B/B2C возвраты, платёжные ссылки
Сбербанк Эквайринг	REST/SOAP, двухстадийные платежи, привязка карт
PayPal / Stripe	Международные платежи, карты, кошельки, 3-D Secure
Крипта	См. ниже

Сквозное: 54-ФЗ фискализация (АТОЛ Онлайн, ЮKassa-чеки), сплитование платежей (маркетплейс — раздельные чеки), токенизация карт, сверка/реестры.

Крипто-платежи

• Приём напрямую (свой кошелёк) или через шлюз (CryptoCloud, NOWPayments, Cryptomus, BTCPay Server);
• сети/токены: BTC, ETH, USDT (TRC-20/ERC-20), TON; уникальный адрес на инвойс;
• курсы (оракул/биржа), фиксация на срок инвойса, пересчёт фиат↔крипта;
• подтверждения блокчейна (N confirmations), отслеживание по хешу, вебхук о поступлении;
• кошельки (hot/cold), автоконвертация в стейблкоин, учёт недоплат/переплат.

Системы доставки

Единый слой DeliveryProvider + коннекторы:

Служба	Возможности
СДЭК	Расчёт тарифа, регистрация заказа, трек, список ПВЗ, вебхуки статусов
Почта России	Расчёт по индексам, трекинг, ОПС, наложенный платёж
Boxberry	Тарификация, создание посылки, ПВЗ, трекинг
DPD / СберЛогистика / 5Post / PickPoint	Коннекторы того же контракта
Яндекс.Доставка	Экспресс, ПВЗ, курьер

Сквозное: карта ПВЗ на фронте (виджеты или своя на Яндекс/2ГИС), зоны доставки, весогабаритные ограничения, расчёт по адресу/гео, объединённая витрина способов с ценой и сроком.

CRM / ERP (двусторонний обмен)

Система	Обмен
Битрикс24	Лиды/сделки/контакты через REST, статусы
amoCRM	Сделки/контакты, вебхуки, воронки, автолид из заявки
RetailCRM	Заказы, клиенты, каталог, ICML-выгрузка
1С (УТ/Комплекс)	CommerceML: выгрузка каталога (товары/цены/остатки/свойства), загрузка заказов; web-сервис или файловый обмен

Контракт: маппинг полей, разрешение конфликтов, очередь синхронизации, лог обмена, ручной запуск/расписание. Обмен с 1С по CommerceML — де-факто стандарт РФ e-commerce.

Маркетплейсы (каналы продаж)

Площадка	API
Ozon	Seller API: карточки/цены/остатки, заказы FBO/FBS, ярлыки
Wildberries	Suppliers API: номенклатура, цены/скидки, остатки, заказы, поставки
Яндекс.Маркет	API партнёра, YML/фид, DBS/FBS, заказы, цены
СберМегаМаркет / Авито	Коннекторы по аналогии

Сквозное: единый PIM-источник карточек, матчинг категорий/атрибутов площадки, синхронизация остатков между каналами, цены per-канал, приём заказов в единую админку.

Прочие интеграции

• DaData/ФИАС/КЛАДР — автодополнение адресов, ФИО, реквизитов по ИНН, банков по БИК;
• Карты — Яндекс.Карты (приоритет РФ), 2ГИС, Google: геокодинг, точки, маршруты, ПВЗ;
• Мессенджеры — Telegram (Bot API, бот-магазин), WhatsApp Business, VK; чат-виджеты;
• Соцсети — VK ID, Одноклассники, Telegram Login; выгрузка в VK Магазин;
• ЕСИА/Госуслуги — авторизация через OAuth2/OIDC ЕСИА, верифицированные данные;
• ЭДО — Диадок/СБИС/Контур: счета, УПД, акты через оператора ЭДО;
• Аналитика — Яндекс.Метрика (e-commerce), GA4, сквозная (Roistat, Calltouch), коллтрекинг;
• Рассылки — Unisender, SendPulse, Mindbox, SMS-агрегаторы (SMS.ru, SMSC);
• Поиск — Elasticsearch/OpenSearch/Sphinx, синонимы, русская морфология, фасеты.

Мобильные приложения

CMS как backend для iOS/Android — тот же API-слой, что и веб.

Отдача данных (API-first)

• Мобильные приложения потребляют тот же Content Delivery / REST / GraphQL — единый источник правды;
• BFF-эндпоинты под мобайл: агрегированные ответы, урезанные поля, адаптивные размеры изображений (по DPI/сети);
• CDN и кеш ответов, ETag/If-None-Match для экономии трафика, сжатие (gzip/brotli).

Push-уведомления

• FCM (Android), APNs (iOS), RuStore-push как импортонезависимая альтернатива;
• регистрация/хранение device-токенов, привязка к пользователю, обработка отписок;
• сегментация (город, роль, история заказов, поведение), таргет и массовые кампании;
• триггерные push (статус заказа, брошенная корзина, акция), тихие push для синхронизации;
• rich push (картинка, кнопки, deep link), локализация, расписание/тайм-зоны.

Аутентификация мобильных клиентов

• OAuth2 (Password / Authorization Code + PKCE), JWT access-токены с коротким TTL;
• refresh-токены с ротацией, отзыв, привязка к устройству, чёрный список;
• соц-вход и ЕСИА на мобиле, вход по SMS-коду (OTP), биометрия разблокирует локальный токен;
• управление сессиями устройств (список активных, удалённый выход).

Синхронизация и офлайн

• Офлайн-кеш каталога/контента, очередь отложенных действий с досинхронизацией при сети;
• дельта-синхронизация (только изменения по timestamp/cursor), разрешение конфликтов;
• версионирование API для приложений: минимальная версия, graceful-деградация старых;
• force/soft-update (сервер сообщает об устаревании), feature-flags и remote config.

Deep links

• Universal Links (iOS) / App Links (Android) — открытие товара/раздела из ссылки, фолбэк в браузер;
• deferred deep linking — переход к экрану после установки из стора (AppsFlyer, Branch, myTracker);
• диплинки в push, письмах, QR; единая схема маршрутизации URL↔экран (web и app).

РФ-специфика (не упустить в ядре)

Требование	Что закладываем
152-ФЗ (ПДн)	Согласия, локализация хранения ПДн в РФ, журнал согласий, экспорт/удаление
54-ФЗ (кассы)	Фискализация каждого платежа, чеки, ОФД, раздельные чеки для сплита
38-ФЗ (маркировка рекламы)	Токены ОРД/ЕРИР на рекламные креативы, отчётность в РКН
ЭДО	Операторы Диадок/СБИС/Контур, форматы УПД/счёт-фактура
ЕСИА/Госуслуги	Авторизация и верифицированные данные для регулируемых ниш
1С CommerceML	Де-факто стандарт российского e-commerce
Импортонезависимость	RuStore как альтернатива Google для мобильных push/дистрибуции

Приоритет отечественных сервисов: ЮKassa/Тинькофф/СБП (платежи), СДЭК/Почта/Boxberry (доставка), Яндекс/2ГИС (карты), DaData/ФИАС (адреса), Яндекс.Метрика (аналитика), VK ID/Telegram (соц-вход).

Связь с другими разделами

Интеграции опираются на каталог подсистем (раздел 8) и на шину интеграций как единый слой коннекторов. Абстрактные слои платежей/доставки — часть e-commerce. Клиентские кабинеты, потребляющие API — см. кабинеты и клиентский маркетплейс.