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