Интеграция: Платёжные системы + Wildberries

Платёжный контур: приём оплаты картой, через СБП, кошельки, рассрочку и оплату частями, а также возвраты и частичные отмены. Для юридических лиц добавляется оплата по счёту с ручной или автоматической сверкой.

Типовые системы на этом конце: ЮKassa, Тинькофф Касса, Сбербанк, CloudPayments, Robokassa, СБП; Stripe — только для зарубежных юридических лиц.

Wildberries — крупнейший маркетплейс: продажи со склада площадки (FBO) и со склада продавца (FBS), а также реклама, акции и отчёты по комиссиям.

Как с ней работать технически: Marketplace API: контент и карточки, цены и скидки, остатки, поставки FBO, сборочные задания FBS, статистика продаж и отчёты о реализации.

В платёжную систему уходят сумма, состав заказа, данные для чека и адрес доставки; обратно приходят статус платежа, идентификатор транзакции, результат холдирования и уведомления о возврате.

Мы всегда описываем обмен в виде таблицы «сущность — направление — частота — владелец данных». Без этого документа интеграция работает до первой нештатной ситуации, после чего расхождения ищут вручную.

«Платёжные системы» и «Wildberries» отвечают за разные участки процесса, поэтому прямой коннектор между ними нужен не всегда — чаще они сходятся в одной из систем контура. Маркетплейс — отдельный канал со своими правилами, лимитами API и отчётностью. Синхронизацию ведём через очередь с ограничителем частоты запросов, остатки распределяем по каналам, а финансовые отчёты площадки регулярно сверяем с учётной системой.

Реализация зависит от того, есть ли у системы открытый API и какие у него лимиты. Если API нет или он ограничен, обмен строим через промежуточный слой: очередь, промежуточную базу или файловый обмен по расписанию с журналом обработки.

Самое частое — расхождение статусов и повторные вебхуки: уведомление может прийти дважды или с задержкой. Поэтому обработка должна быть идемпотентной, а сверка с выпиской — ежедневной. Карточные данные не должны проходить через ваш сервер: это требование PCI DSS, которое закрывается платёжной формой провайдера.

Мы закладываем в интеграцию ограничитель частоты запросов, повторные попытки с нарастающей паузой, журнал операций и оповещение при ошибках. Это дешевле, чем разбирать последствия сбоя в высокий сезон.

Жёсткие лимиты на частоту запросов и частые изменения методов: интеграцию нужно писать с ограничителем, очередью и обработкой ошибок 429. Обязательны корректные штрихкоды и соблюдение правил упаковки, иначе поставку не примут.

Часть ограничений обходится архитектурой (кэш, очередь, разделение каналов обмена), часть — нет: тогда мы предлагаем изменить процесс, а не имитировать его в коде.

На стоимость влияют: наличие и качество API, количество сущностей в обмене, требования к истории (загружать ли прошлые заказы), необходимость синхронизации в реальном времени, требования к маркировке и чекам, а также готовность данных на обеих сторонах.

Сроки обычно определяет не разработка, а согласования: доступы к системе, тестовый контур, договор с провайдером, правила расчёта и требования бухгалтерии. Мы выносим эти пункты в чек-лист подготовки, чтобы они не останавливали работы в середине проекта.

Первый шаг — обследование: смотрим, какие данные уже ведутся, кто владелец каждой сущности и какие ограничения есть у API. Затем делаем прототип обмена на тестовом контуре, проверяем нештатные сценарии (повтор, отмена, частичное выполнение) и только после этого выводим интеграцию в продуктив.

После запуска передаём документацию по обмену и журнал операций, чтобы поддержку можно было передать другой команде без обратного проектирования кода.