API - интеграция позволяет связать сайт, приложение, корпоративную систему или внешний сервис через формальный программный интерфейс. Разрабатываем собственные API и подключаем существующие внешние API с документированным контрактом, обработкой ошибок, контролем повторных операций и мониторингом.
API - это не просто набор endpoint'ов. Это контракт между системами: какие операции доступны, какие данные принимаются, что возвращается в ответ, как выглядит ошибка, кто имеет доступ и что происходит при повторном запросе, временной недоступности или изменении версии.
Работаем с REST API, webhooks, OpenAPI и SOAP там, где он требуется существующей системой.
Интеграция через API
Подключаем внешние программные интерфейсы к сайтам, веб-приложениям, мобильным приложениям и корпоративным системам.
API - интеграция может использоваться для подключения:
- CRM.
- ERP.
- Банковских сервисов.
- Платежных провайдеров.
- Служб доставки.
- Маркетплейсов.
- SaaS-платформ.
- Систем электронного документооборота.
- Внешних баз и информационных сервисов.
- Внутренних корпоративных систем.
Изучаем документацию внешнего API, тестовый контур, способы авторизации, ограничения и модель ошибок.
Затем проектируем клиентскую часть интеграции с учетом реального поведения внешнего сервиса, а не только его успешных примеров из документации.
Разработка API
Разрабатываем собственный API, если доступ к данным или функциям вашей системы должны получить другие приложения, сервисы или партнеры.
API может использоваться для:
- Мобильного приложения.
- Личного кабинета.
- frontend-приложения.
- Партнерской интеграции.
- Внутренних сервисов.
- Микросервисного взаимодействия.
- Корпоративной интеграционной платформы.
- Подключения внешних информационных систем.
До реализации определяем, какие возможности действительно должны быть открыты наружу, а какие детали внутренней архитектуры должны остаться скрытыми.
Что влияет на стоимость
Стоимость API - интеграции зависит от:
- Количества методов.
- Количества внешних систем.
- Сложности схем данных.
- Типа авторизации.
- Наличия webhooks.
- Необходимости разработки собственного API.
- Необходимости интеграции внешнего API.
- Требований к обратной совместимости.
- Требований к безопасности.
- Необходимости асинхронной обработки.
- Наличия тестового контура.
- Качества документации внешней системы.
Сроки и стоимость
Стоимость разработки или API - интеграции - от 80 000 ₽.
Срок - от 1 недели.
Точная оценка зависит от количества методов, сложности контракта, требований к безопасности, устойчивости и возможностей внешних систем.
Разработка REST API
Для новых HTTP-интеграций обычно проектируем REST API, если такой подход соответствует задаче и архитектуре системы.
Определяем:
- Ресурсы.
- URL и структуру endpoint'ов.
- HTTP-методы.
- Структуру запросов.
- Структуру ответов.
- HTTP-коды.
- Бизнес-коды ошибок.
- Фильтрацию.
- Сортировку.
- Пагинацию.
- Ограничения операций.
- Правила авторизации.
- Правила повторных запросов.
Контракт проектируется так, чтобы клиенту API не требовалось знать внутреннее устройство базы данных или внутренние классы приложения.
SOAP API
SOAP по-прежнему встречается в корпоративных, банковских и legacy-системах.
Если существующий контур требует SOAP, работаем с его контрактами, XML-схемами, авторизацией, ошибками и особенностями конкретного сервиса.
Не заменяем работающий корпоративный протокол только потому, что REST выглядит современнее. Архитектура выбирается под ограничения интеграционного контура.
Проектируем API-контракт
Контракт определяет, как клиент и сервер понимают друг друга.
Для каждой операции фиксируем:
- Назначение.
- Метод.
- Путь.
- Параметры.
- Заголовки.
- Формат тела запроса.
- Обязательные поля.
- Необязательные поля.
- Типы данных.
- Ограничения значений.
- Формат успешного ответа.
- Формат ошибки.
- Правила повторного вызова.
Чем точнее определен контракт, тем меньше логики клиент вынужден угадывать самостоятельно.
Стабильная модель ошибок
Клиенту недостаточно получить HTTP 400 или HTTP 500.
Для API определяем, какие ошибки являются:
- Ошибками входных данных.
- Ошибками авторизации.
- Ошибками прав доступа.
- Ошибками бизнес-правил.
- Конфликтами состояния.
- Временными техническими ошибками.
- Внутренними ошибками системы.
Ошибка должна позволять клиенту понять, можно ли исправить запрос, повторить его позже или требуется ручное вмешательство.
OpenAPI и документация
Для REST API формируем машинно-читаемое описание контракта через OpenAPI, если это соответствует стеку проекта.
Документация может включать:
- endpoint'ы.
- HTTP-методы.
- Параметры.
- Схемы запросов.
- Схемы ответов.
- Обязательные поля.
- Коды ошибок.
- Примеры запросов.
- Примеры ответов.
- Правила авторизации.
- Ограничения.
- Правила повторов.
Документация должна соответствовать фактически работающему API, а не описывать отдельно существующую идеальную версию.
Версионирование API
После запуска API начинает зависеть от его клиентов.
Поэтому изменение контракта нельзя рассматривать как обычный внутренний рефакторинг.
Определяем:
- Правила версионирования.
- Обратную совместимость.
- Какие изменения считаются breaking changes.
- Порядок вывода старой версии из эксплуатации.
- Период миграции клиентов.
- deprecated-методы и поля.
- Процесс уведомления потребителей API.
Новое поле обычно добавить проще, чем удалить существующее или изменить его смысл.
Совместимость контракта
При развитии API отдельно оцениваем влияние изменений на существующих клиентов.
Проверяем:
- Изменение обязательности полей.
- Удаление полей.
- Изменение типов.
- Изменение возможных значений.
- Изменение статусов.
- Изменение кодов ошибок.
- Изменение семантики существующей операции.
Технически корректный JSON еще не означает, что контракт остался совместимым.
Авторизация и доступ к API
Способ авторизации выбираем исходя из типа клиентов и требований проекта.
В зависимости от архитектуры могут использоваться:
- API keys.
- access tokens.
- OAuth 2.0.
- JWT.
- Подписанные запросы.
- mTLS.
- Дополнительные сетевые ограничения.
Не все механизмы нужны одновременно. Выбираем достаточную модель доступа для конкретной интеграции.
Работа с секретами
Ключи, токены и другие секреты не должны храниться непосредственно в исходном коде.
Определяем:
- Где хранятся секреты.
- Какие сервисы имеют к ним доступ.
- Какие права действительно нужны.
- Как выполняется ротация.
- Что происходит при компрометации.
- Какие данные запрещено записывать в логи.
Webhooks
Если внешний сервис должен сам сообщать о событии, используем webhook-модель, когда она поддерживается системой и подходит сценарию.
Для webhook определяем:
- Типы событий.
- Формат payload.
- Идентификатор события.
- Проверку подлинности.
- Подпись.
- Политику повторной доставки.
- Идемпотентную обработку.
- Логирование результата.
Получатель должен быть готов к тому, что одно событие может прийти повторно.
Идемпотентность
Повторный запрос не всегда означает новую бизнес-операцию.
Например, клиент мог отправить запрос, не получить ответ из-за сетевого timeout и повторить его.
Если первая операция уже выполнилась, бесконтрольный повтор может создать дубль.
Для критичных операций определяем механизм идемпотентности:
- idempotency key.
- Идентификатор внешней операции.
- Проверку ранее обработанного запроса.
- Правила возврата результата повторной операции.
Дедупликация событий
В асинхронных интеграциях одна операция также может быть доставлена повторно.
Поэтому определяем, как система отличает новое событие от уже обработанного.
Это особенно важно, если событие приводит к необратимому изменению состояния.
Timeout
У каждого внешнего вызова должна быть ограниченная продолжительность.
Бесконечное ожидание ответа постепенно блокирует ресурсы вызывающей системы.
Значения timeout выбираем в зависимости от характера операции и ожидаемого поведения внешнего сервиса.
Повторные запросы и retries
Не каждую ошибку нужно повторять.
Например, временная техническая недоступность и ошибка валидации требуют разного поведения.
Для повторов определяем:
- Какие ошибки можно повторять.
- Количество попыток.
- Интервалы.
- backoff.
- Максимальное время восстановления.
- Поведение после исчерпания попыток.
Rate limits
Внешние API часто ограничивают количество запросов.
Учитываем:
- Общий лимит.
- Лимиты отдельных методов.
- Окна ограничения.
- HTTP 429.
- Retry-After, если он поддерживается.
- Параллельность.
- Пакетную обработку.
- Очереди запросов.
Если лимиты игнорировать, API может нормально работать на тестах и начать регулярно падать после роста нагрузки.
Ограничиваем каскадные сбои
Проблема внешнего API не должна автоматически выводить из строя вашу систему.
В зависимости от архитектуры используем:
- timeout.
- Контролируемые retries.
- backoff.
- Ограничение параллельности.
- Очереди.
- Буферизацию.
- circuit breaker.
- dead-letter обработку.
Конкретный набор механизмов определяется критичностью операции.
Синхронная и асинхронная интеграция
Не каждую операцию нужно выполнять в рамках одного HTTP-запроса.
Синхронное взаимодействие удобно, когда клиенту требуется непосредственный результат.
Асинхронная модель полезна, когда операция:
- Выполняется долго.
- Допускает отложенную обработку.
- Должна переживать временную недоступность получателя.
- Имеет высокий поток событий.
- Требует независимого масштабирования участников.
REST API, webhooks и очереди могут использоваться совместно в одной архитектуре.
Валидация данных
API должен проверять входные данные на границе системы.
Проверяем:
- Обязательные поля.
- Типы.
- Форматы.
- Допустимые значения.
- Размеры.
- Связанные бизнес-ограничения.
Клиент должен получить понятную информацию о причине отказа, а не общую внутреннюю ошибку сервера.
Пагинация и большие объемы данных
Методы, которые возвращают коллекции, проектируем с учетом роста данных.
В зависимости от задачи определяем:
- Пагинацию.
- Размер страницы.
- Фильтры.
- Сортировку.
- Ограничения выборки.
- Поведение при изменении данных между запросами.
API не должен предполагать, что количество записей всегда останется небольшим.
Наблюдаемость API - интеграции
После запуска должно быть возможно понять, что произошло с конкретным запросом или событием.
В зависимости от инфраструктуры используем:
- Структурированные логи.
- correlation ID или trace ID.
- Метрики.
- Алерты.
- distributed tracing.
- Контроль задержки.
- Контроль процента ошибок.
- Контроль повторных попыток.
При этом секреты, токены и чувствительные данные должны маскироваться.
Что отслеживаем после запуска
Для критичных API полезно контролировать:
- Количество запросов.
- Количество успешных операций.
- Ошибки по типам.
- latency.
- timeout.
- Количество retries.
- rate limit.
- Зависшие события.
- Недоступность внешнего сервиса.
Тестирование API
Проверяем не только happy path.
Тестируем:
- Корректные запросы.
- Некорректные данные.
- Отсутствующие обязательные поля.
- Неверную авторизацию.
- Недостаточные права.
- Повторные запросы.
- timeout.
- Временные ошибки.
- rate limit.
- Неожиданные ответы внешней системы.
- Изменение состояния между операциями.
Интеграционные и контрактные тесты
Если API используется несколькими системами, проверяем не только отдельный endpoint, но и совместимость взаимодействия.
В зависимости от проекта используем:
- Интеграционные тесты.
- Контрактные проверки.
- Тестовые данные.
- sandbox внешнего сервиса.
- mocks или stubs.
- Проверку негативных сценариев.
Как строится разработка API
1. Определяем задачу
Выясняем:
- Какие системы взаимодействуют.
- Кто является клиентом API.
- Какие операции нужны.
- Какие данные передаются.
- Какие операции критичны.
- Какие ограничения уже существуют.
2. Проектируем контракт
Фиксируем:
- Методы.
- Схемы данных.
- Обязательные поля.
- Ответы.
- Ошибки.
- Авторизацию.
- Ограничения.
- Идемпотентность.
- Версионирование.
3. Проектируем устойчивость
Определяем:
- timeout.
- retries.
- backoff.
- rate limits.
- Поведение при недоступности.
- Повторную обработку.
- Наблюдаемость.
4. Реализуем API или интеграционный клиент
Реализуем серверную часть API, подключение внешнего сервиса или обе стороны, если проект требует полного интеграционного контура.
5. Тестируем
Проверяем позитивные, негативные и аварийные сценарии.
6. Запускаем и наблюдаем
После запуска контролируем технические ошибки, задержки, повторные операции и изменение поведения внешних зависимостей.
Что считаем готовым API
Разработка API заканчивается не тогда, когда endpoint отвечает HTTP 200.
Для приемки проверяем:
- Контракт описан.
- Схемы запросов и ответов определены.
- Ошибки имеют стабильную модель.
- Авторизация работает.
- Права ограничены.
- Критичные операции защищены от неконтролируемых повторов.
- timeout и ошибки внешних зависимостей обработаны.
- Документация соответствует реализации.
- API можно диагностировать после запуска.
- Понятен процесс изменения контракта.
Что получает команда
В зависимости от проекта результат может включать:
- Реализованный REST API.
- Клиент внешнего API.
- OpenAPI-описание.
- Схемы данных.
- Описание ошибок.
- Правила авторизации.
- Правила идемпотентности.
- webhook-контракты.
- Правила версионирования.
- Интеграционные тесты.
- Настроенное логирование.
- Метрики и мониторинг.
- Инструкцию по эксплуатации интеграции.
Типовые ошибки при разработке API
API повторяет структуру базы данных
Внутренняя модель системы фактически становится публичным контрактом, поэтому любое изменение базы начинает затрагивать клиентов.
Нет стабильной модели ошибок
Клиенты вынуждены анализировать текстовые сообщения или угадывать причину отказа.
Нет идемпотентности
Повторный запрос после timeout создает вторую бизнес-операцию.
Retry выполняется для любой ошибки
Система повторяет даже запросы, которые никогда не станут успешными, и создает дополнительную нагрузку.
Не учитываются rate limits
Интеграция работает на тестовых объемах, но начинает получать отказы после роста нагрузки.
Нет версионирования
Любое изменение контракта одновременно ломает всех существующих потребителей.
Нет мониторинга
О проблеме узнают от пользователя или партнера, а не от системы наблюдения.
В логах сохраняются секреты
Токены, ключи или чувствительные данные оказываются доступны через инфраструктуру логирования.
Границы услуги
Эта страница посвящена именно API - интеграции, интеграции через API и разработке собственного API.
Если задача заключается прежде всего в синхронизации 1С, CRM, ERP и сайта, включая товары, заказы, клиентов, остатки и бизнес-статусы, используется интеграция 1С с сайтом, CRM и ERP.
Если требуется подключить эквайринг, СБП или платежный шлюз, используется подключение онлайн-оплаты.
Если требуется интеграция фискального контура и формирование чеков, используется интеграция онлайн-кассы.
Что нужно для старта
Для первичной оценки полезно предоставить:
- Описание задачи.
- Список участвующих систем.
- Документацию API, если она существует.
- OpenAPI или Swagger, если доступны.
- Описание способов авторизации.
- Список необходимых операций.
- Примеры запросов и ответов.
- Информацию о тестовом контуре.
- Известные ограничения.
- Описание текущих проблем интеграции.
Если документации нет или фактическое поведение API отличается от нее, сначала исследуем существующий интерфейс и фиксируем реальный контракт.
Хорошая API - интеграция определяется не количеством endpoint'ов, а тем, насколько предсказуемо системы взаимодействуют при нормальной работе, ошибках, повторах и последующих изменениях контракта.
Да. Сначала можно исследовать существующую интеграцию, посмотреть её фактическое поведение и определить причины сбоев. Если текущую реализацию можно безопасно развивать, полной замены не требуется. Решение о переработке принимается после анализа, а не автоматически.
Можно. Интеграцию необязательно запускать сразу со всем возможным набором операций. Важно при первом этапе не спроектировать решение так, чтобы дальнейшее расширение потребовало ломать уже работающую часть.
Да, если есть необходимые технические возможности и доступ к сторонам интеграции. В таком проекте особенно важно заранее определить, кто отвечает за каждую систему, получить актуальную документацию и согласовать изменения, которые потребуются от разных участников.
Не обязательно. Разработку и значительную часть тестирования обычно можно выполнять отдельно от работающего пользовательского контура. Потребуется ли какое-либо ограничение работы при финальном запуске, зависит от архитектуры сайта и характера изменений.
Тогда сначала нужно выяснить, предоставляет ли сервис другой официальный способ интеграции. Если программного интерфейса или другого предусмотренного механизма обмена нет, обычную API - интеграцию выполнить нельзя. Возможные альтернативы оцениваются отдельно с учетом возможностей конкретной системы.
Да, если внешний API предоставляет необходимые операции чтения и позволяет соответствующим образом ограничить доступ. Интеграции не обязательно давать возможность изменять данные только потому, что такая возможность существует у внешнего сервиса.
Возможно, если можно организовать сетевую связность между участниками интеграции. В таком случае помимо самого API нужно учитывать существующие ограничения сети, firewall и способ безопасного доступа к внутренней системе.
Не всегда. Необходимые доступы зависят от того, как устроен проект и что именно требуется интегрировать. Там, где возможно, разработку и проверку лучше отделять от рабочих данных с помощью тестового контура, тестовых учетных записей и подготовленных наборов данных.
Да, если для реализации доступны необходимые системы, документация и технические доступы. Наличие собственного разработчика у заказчика не является обязательным, но со стороны компании обычно нужен человек, который сможет подтвердить бизнес-логику и ожидаемый результат обмена данными.
Интеграция не должна зависеть только от знаний разработчика, который её создавал. Для этого фиксируются контракт, способы авторизации, основные правила обработки ошибок и другие значимые параметры, а для работающей системы предусматривается возможность понять по логам и мониторингу, что произошло с конкретной операцией.