Сайт получает цены из учётной системы, передаёт заказы на склад, считает доставку и принимает оплату. Объясняем без жаргона, как устроены API и что заложить в проект, чтобы интеграции не ломались.
API — это договор между системами
API, или программный интерфейс, проще всего представить как окно выдачи в столовой. Вы не заходите на кухню и не знаете, как там готовят, — вы делаете заказ по меню, в оговорённой форме, и получаете блюдо в оговорённом виде. Так же и сайт: он отправляет запрос другой системе по заранее описанным правилам и получает ответ в понятном формате.
Эти правила фиксируются в документации: какие адреса можно вызывать, какие параметры передавать, что вернётся в ответ и какие ошибки возможны. Хорошая документация — половина успеха интеграции. Если её нет или она устарела, разработчикам приходится выяснять поведение методом проб, а это время и риск ошибок.
Для бизнеса важно понимать одно: каждая интеграция — это зависимость. Сайт начинает полагаться на внешнюю систему, и её сбои, изменения и ограничения становятся вашими проблемами. Поэтому интеграции нужно не только сделать, но и спроектировать с запасом прочности.
Какие интеграции встречаются чаще всего
По нашему опыту, у типичного B2B-сайта или интернет-магазина от трёх до десяти внешних связей. Вот основные группы.
- Учётные системы: выгрузка номенклатуры, цен, остатков, передача заказов и контрагентов.
- CRM: передача заявок, обращений, статусов сделок.
- Платёжные сервисы: приём оплаты картой, по QR-коду, выставление счетов юрлицам.
- Службы доставки: расчёт стоимости и сроков, пункты выдачи, создание отправлений, трекинг.
- Сервисы проверки контрагентов и адресов: автозаполнение реквизитов по ИНН, подсказки адресов.
- Рассылки и уведомления: email, SMS, мессенджеры.
- Аналитика и реклама: передача событий и офлайн-конверсий.
- Системы складского учёта и производственные системы — для производителей, которые показывают дилерам сроки изготовления.
Форматы и протоколы: что стоит знать заказчику
Погружаться в технические детали руководителю не обязательно, но базовые понятия помогают вести диалог с подрядчиками и IT-отделом.
| Подход | Суть | Где встречается |
|---|---|---|
| REST с JSON | Запросы к адресам ресурсов, данные в лёгком текстовом формате | Большинство современных сервисов: оплата, доставка, CRM |
| SOAP с XML | Строгий формат сообщений с описанием схемы | Банки, государственные и крупные корпоративные системы |
| Обмен файлами | Выгрузка XML или CSV по расписанию на сервер | Учётные системы, прайс-листы поставщиков |
| Вебхуки | Внешняя система сама сообщает сайту о событии | Статусы оплат, изменения в CRM, трекинг доставки |
| GraphQL | Клиент сам описывает, какие поля ему нужны | Сложные интерфейсы, мобильные приложения, headless-архитектура |
Важное различие — синхронный и асинхронный обмен. Синхронный: сайт спрашивает и ждёт ответа, пока пользователь смотрит на экран, например при расчёте стоимости доставки. Асинхронный: данные передаются в фоне, например ночная выгрузка каталога. Всё, что пользователь ждёт в реальном времени, должно отвечать за доли секунды, иначе интерфейс начнёт «тормозить».
Надёжность: что происходит, когда другая сторона не отвечает
Любой внешний сервис рано или поздно бывает недоступен. Вопрос не в том, случится ли сбой, а в том, как сайт его переживёт. Мы закладываем несколько правил в каждый проект.
Таймауты
Запрос к внешней системе не должен висеть бесконечно. Если служба доставки не ответила за 2–3 секунды, пользователь увидит сообщение «Стоимость уточнит менеджер» или ориентировочную цену из последнего успешного расчёта, а не зависшую страницу оформления заказа.
Очереди и повторные попытки
Критичные данные — заказы, заявки, оплаты — сначала сохраняются на стороне сайта, а затем отправляются. Не получилось — система повторит попытку через минуту, через пять, через полчаса. Заказ не потеряется, даже если учётная система была недоступна всю ночь.
Кеширование
Справочные данные — список пунктов выдачи, курсы, категории — не нужно запрашивать при каждом открытии страницы. Их сохраняют локально и обновляют по расписанию. Это ускоряет сайт и снижает зависимость от внешнего сервиса.
Идемпотентность
Сложное слово с простым смыслом: повторная отправка одного и того же запроса не должна создавать дубль. Если сайт дважды отправил заказ из-за сетевой ошибки, в учётной системе должен остаться один заказ. Для этого каждому запросу присваивается уникальный идентификатор.
История из практики: когда интеграций стало слишком много
К нам обратился оптовый поставщик электротехники, чей сайт за несколько лет оброс связями с шестью системами. Каждую интеграцию делали разные подрядчики, в разное время и по-своему. Выгрузка остатков конфликтовала с выгрузкой цен, запускаясь в одно и то же время; обработчик заказов при ошибке учётной системы молча завершался, и менеджеры узнавали о потерянных заказах из звонков клиентов.
Мы не стали переписывать всё сразу. Сначала составили карту: какая система что отправляет, по какому расписанию и что будет, если она недоступна. Затем перевели все исходящие потоки на единую очередь с журналом и оповещением об ошибках, развели по времени тяжёлые выгрузки и добавили панель, где менеджер видит статус каждого заказа на пути в учётную систему. Код отдельных интеграций меняли точечно. Итог — за следующие полгода не было ни одного потерянного заказа, а время разбора инцидентов сократилось с дней до минут.
Совет студии: заведите «паспорт интеграций» — простую таблицу, где для каждой связи указано направление, формат, расписание, ответственный с обеих сторон и поведение при сбое. Обновлять её — дело десяти минут, а в момент аварии она экономит часы.
Безопасность и доступы
Интеграции открывают двери между системами, и эти двери нужно запирать. Ключи доступа к API хранятся в защищённых настройках сервера, а не в коде и тем более не в браузере пользователя. У каждого ключа — минимально необходимые права: если сайту нужно только читать остатки, ключ не должен позволять менять цены.
Входящие вебхуки проверяются по подписи, чтобы злоумышленник не мог отправить сайту поддельное уведомление об оплате. Обмен идёт только по защищённому соединению. Ключи периодически обновляются, а при увольнении сотрудника или смене подрядчика — обязательно. Журнал запросов хранится достаточно долго, чтобы при инциденте восстановить картину.
Как заложить интеграции в проект сайта
Самая дорогая ошибка — вспомнить об интеграциях после утверждения дизайна и вёрстки. Выясняется, что учётная система не отдаёт нужные характеристики, служба доставки не умеет считать негабарит, а у CRM ограничение на количество запросов в минуту. Приходится менять интерфейс и сдвигать сроки.
Поэтому на этапе аналитики мы проводим обследование всех систем, с которыми будет работать сайт: запрашиваем документацию и тестовые доступы, проверяем реальные ответы, оцениваем объёмы данных. Результат фиксируется в техническом задании. Для интернет-магазинов и B2B-проектов этот этап занимает от одной до трёх недель, но экономит в разы больше времени на разработке.
Чек-лист перед запуском интеграций
- Для каждой связи есть актуальная документация и тестовая среда.
- Определено, что видит пользователь, если внешний сервис недоступен.
- Заказы, заявки и платежи сохраняются на сайте до отправки и ставятся в очередь.
- Настроены таймауты, повторные попытки и защита от дублей.
- Ключи доступа хранятся безопасно и имеют минимальные права.
- Есть журнал обмена и оповещение ответственного при серии ошибок.
- Тяжёлые выгрузки разведены по времени и не пересекаются с пиками посещаемости.
- Составлен паспорт интеграций с контактами ответственных.
