Перейти к основному содержанию
Обсудить проект

Разработка и цифровые решения

API - интеграция и разработка API

APLIKE / DIGITAL STUDIODESIGN · ENGINEERING · GROWTHSYSTEMS · AUTOMATION · RELIABILITY
Ориентир по бюджету

Стоимость и сроки

ПРОЗРАЧНАЯ ОЦЕНКА · РАЗУМНЫЕ РЕШЕНИЯPLAN · BUILD · LAUNCH
Стоимость: от 80 000₽
Срок: от 1 недели
Хотите посмотреть весь прайс-лист?
О решении

Подробно о подходе.

Из чего состоит работа, какие задачи решаем и что важно учитывать.

В основе проекта — инженерные решения, которые работают на бизнес.

DISCOVER · ARCHITECT · DELIVER
API - интеграция и разработка API. Заказать API - интеграцию и разработку API в Москве

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'ов, а тем, насколько предсказуемо системы взаимодействуют при нормальной работе, ошибках, повторах и последующих изменениях контракта.

Часто задаваемые вопросы (FAQ)
У нас уже есть интеграция, но она периодически ломается. Можно её доработать, а не делать заново?

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

Можно сначала подключить только одну нужную функцию, а остальные добавить позже?

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

Наш сайт и внешнюю систему обслуживают разные подрядчики. Вы сможете сделать интеграцию между ними?

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

Нужно ли останавливать работающий сайт на время подключения API?

Не обязательно. Разработку и значительную часть тестирования обычно можно выполнять отдельно от работающего пользовательского контура. Потребуется ли какое-либо ограничение работы при финальном запуске, зависит от архитектуры сайта и характера изменений.

Что если у нужного нам сервиса вообще нет API?

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

Можно сделать так, чтобы наш сайт только получал данные из другой системы и ничего там не менял?

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

Можно подключить внутреннюю систему, которая доступна только из офиса или корпоративной сети?

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

Для разработки обязательно давать доступ к рабочей базе данных и реальным данным клиентов?

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

У нас нет своего программиста. Можно заказать интеграцию полностью под ключ?

Да, если для реализации доступны необходимые системы, документация и технические доступы. Наличие собственного разработчика у заказчика не является обязательным, но со стороны компании обычно нужен человек, который сможет подтвердить бизнес-логику и ожидаемый результат обмена данными.

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

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

Рейтинг услуги
0
12 голосов со средней оценкой 4.7.
Поставьте оценку уровню наших услуг
ДОПОЛНЯЮЩИЕ РЕШЕНИЯ

Работают лучше вместе.

Смежные услуги, которые помогают получить больше от проекта.

Интегрируем онлайн - кассу с сайтом и платёжным контуром: формирование чеков, возвраты, авансы и предоплаты, взаимодействие с ОФД, контроль статусов, очереди и повторные попытки. Защищаем процесс от потери операций и двойной фискализации.
Интеграция сайта с CRM, 1С и ERP: синхронизация клиентов, товаров, цен, остатков, заказов, оплат и документов. Настраиваем устойчивый обмен данными без дублей, потерь и ручного переноса.
Подключение онлайн-оплаты к сайту: эквайринг, СБП, платежные шлюзы, корректные статусы, возвраты и webhooks. Настраиваем интеграцию так, чтобы платеж доходил до заказа и не терялся при сбоях.
Проектируем программы лояльности и геймификацию для роста повторных покупок, retention и LTV. Разрабатываем бонусные модели, cashback, статусы, персональные предложения и игровые механики, интегрируем их с CRM, кассой, интернет-магазином или приложением.