Вернуться к статьям Покупатель оформляет заказ, а менеджер видит его в учётной системе с задержкой, без части позиций или с неверным статусом. Остаток на сайте уже изменился, но внешний склад ещё не получил данные. Клиент отменил заказ, а возврат в связанной системе не зафиксирован. Такие ситуации возникают не потому, что обмен не подключён, а потому, что типовой сценарий не описывает реальный путь данных.
Разработка API для интернет-магазина нужна, когда сайт обменивается данными с несколькими системами, использует нестандартные правила или работает с форматом, который нельзя передать готовым модулем. Для такого обмена согласуют контракт API: состав данных, ответственность за их актуальность и действия при сбое.
Когда типового обмена для интернет-магазина недостаточно
Готовый обмен подходит для простого сценария: передать товары, цены, остатки или заказы в предсказуемом формате. Сложности появляются, когда в проекте есть исключения.
Например, часть ассортимента продаётся со свойствами, от которых зависит доступность или состав заказа. Для разных групп покупателей действуют отдельные правила. Заказ может быть разбит на несколько отправлений, отменён частично или дополнен после оформления. Внешняя система может возвращать статусы, которые не совпадают со статусами сайта.
Типовой модуль не всегда можно безопасно расширить без понимания его ограничений. Иногда достаточно обработчиков и настройки правил, иногда обмен лучше вынести в отдельный API. Решение зависит не от названия платформы, а от перечня сценариев, которые должны проходить без ручного исправления.
Какие задачи решает разработка API для интернет-магазина
API принимает и передаёт данные между сайтом, учётной системой, складом, службой доставки, платёжным контуром, личным кабинетом поставщика или внутренней CRM. Для каждой связки определяют состав данных и порядок обновления.
Для каталога обычно определяют, откуда поступают названия, характеристики, изображения, цены и остатки. Для заказа — состав корзины, контакты, способ получения, комментарии, скидки, статус оплаты и отгрузки. Отдельно описывают возвраты, отмены, промокоды, резервирование и замену товара.
Недостаточно перечислить сущности «товар» и «заказ». Нужно зафиксировать поля, обязательность, допустимые значения и правила обновления. Если внешний источник передал пустое значение цены, сайт должен очистить цену, оставить прежнюю или отклонить обновление? Если товар исчез из выгрузки, его скрывают, помечают недоступным или не меняют? Эти решения определяют логику API сильнее, чем выбор протокола.
Проектирование API: данные, направления и идентификаторы
Надёжный обмен начинается с карты данных. Для каждой сущности указывают источник, получателя, направление передачи и идентификатор, по которому записи сопоставляются. Артикул, внутренний код и внешний ID могут выглядеть похожими, но иметь разное назначение. Сопоставление по названию товара или адресу покупателя создаёт дубли и ошибки.
Полезно заранее описать состояния каждой записи. Товар может быть новым, активным, скрытым, снятым с продажи или временно отсутствующим. Заказ — созданным, подтверждённым, переданным в сборку, отменённым или возвращённым. API должен передавать согласованные значения либо правила преобразования статусов.
Для сайта на «1С-Битрикс: Управление сайтом» API затрагивает структуру каталога, карточки, корзину и обработку заказов. Это задачи CMS сайта. Внутренние процессы работы с клиентами относятся к CRM и требуют отдельного описания интеграции, даже если в обмене участвуют те же контакты и заказы.
Синхронный и асинхронный обмен данными
Синхронный запрос нужен, когда ответ требуется сразу: проверить доступность, рассчитать вариант получения или подтвердить действие пользователя. Внешний сервис может временно не отвечать или обрабатывать запрос слишком долго. В таком случае оформление заказа не должно останавливаться без понятного сообщения и дальнейшего сценария обработки.
Асинхронный обмен используют для операций, которые можно выполнить в очереди: загрузки каталога, обновления остатков, передачи заказа и получения статусов. Сайт сохраняет задачу, а отдельный процесс отправляет её и фиксирует результат. При кратковременном сбое операцию можно повторить без потери данных.
Для каждого направления определяют систему, данные которой считаются актуальными. Если и сайт, и внешняя система могут одновременно менять остаток или статус, нужны правила приоритета. Иначе данные будут перезаписываться тем участником, чей ответ обработан последним.
Обработка ошибок и защита от дублей
Ошибка API — рабочая ситуация, которую нужно предусмотреть в логике обмена. Внешняя система может вернуть неполный ответ, ограничить доступ, изменить формат поля или обработать запрос, но не успеть передать подтверждение. Поэтому заранее описывают повторные отправки, журнал событий и порядок проверки спорных операций.
Особое внимание требуется заказам. Повторная отправка одного запроса не должна создавать второй заказ во внешней системе. Для этого используют идентификатор операции или правило идемпотентности: одинаковый запрос распознаётся как повтор уже обработанного действия. Так же проверяют обновления каталога, чтобы старая выгрузка не перезаписала более свежие данные.
Журнал обмена должен показывать, что было отправлено, какой ответ получен, какие поля не прошли проверку, можно ли повторить операцию и где исправляют исходные данные. Пароли, токены доступа и другие секреты в журнал без необходимости не включают.
Как выбрать вариант интеграции и проверить результат
Выбор между готовым модулем, доработкой существующего обмена и отдельной разработкой зависит от границы задачи. Готовое решение подходит, если оно покрывает нужные сущности и правила без обходных схем. Доработка возможна, когда базовый механизм уже соответствует процессу, а изменения ограничены несколькими понятными сценариями. Отдельный API требуется, если обмен затрагивает несколько систем, включает преобразование данных и нуждается в самостоятельном контроле ошибок.
До начала работ фиксируют контракты API, схему направлений обмена и перечень исключений. Важно определить, кто предоставляет доступы и документацию форматов, какие поля обязательны, как обрабатываются пустые значения, что считается успешной передачей, как исключаются дубли и как восстанавливается обмен после сбоя.
Готовность проверяют через конкретные действия, а не формулировкой «интеграция настроена». Например, товар с вариантами обновляется по согласованным правилам, заказ передаётся без дублей, отмена меняет состояние в нужных системах, а ошибочная операция видна в журнале и может быть обработана повторно.
Часто задаваемые вопросы
- Когда интернет-магазину нужен отдельный API, а не готовый модуль?
Нужно выписать реальные сценарии обмена и проверить их на возможностях готового решения. Отдельный API рассматривают, если необходимо преобразовывать данные, объединять несколько источников, обрабатывать нестандартные статусы или контролировать повторную передачу операций.
- Какие данные нужно подготовить до разработки?
Понадобятся примеры товаров, заказов и статусов, описание источников данных, доступная документация внешних систем и список исключений. Полезно сразу отметить обязательные поля, ответственных за их заполнение и систему, которая может менять каждое значение.
- Что делать, если одна система временно недоступна?
Сценарий определяют заранее. Операция может попасть в очередь, получить статус ошибки и быть повторена после восстановления доступа. Для заказов отдельно описывают, что увидит покупатель и как сотрудник проверит, дошли ли данные до принимающей системы.
- Можно ли менять API после запуска интернет-магазина?
Можно, но изменение формата без совместимости способно остановить обмен. Новые поля, статусы и правила вводят через версию API или период одновременной поддержки старого и нового форматов. Перед изменением проверяют все системы-получатели.
- Как принять работу по интеграции?
Проверку проводят на согласованных примерах: товаре с характеристиками, изменении цены или остатка, заказе с нужным способом получения, отмене, повторной отправке запроса и недоступности внешней системы. Результат сверяют на сайте, в журнале обмена и в принимающей системе.