Интеграция по API: что это и как связать сервисы

Как спроектировать интеграцию по API?

1. Описать бизнес-событие и владельца результата.
2. Определить систему-источник для каждой сущности.
3. Согласовать поля, форматы, статусы и версии контракта.
4. Выбрать синхронный запрос, событие или пакетный обмен.
5. Добавить внешние ID и защиту от повторной обработки.
6. Настроить ограниченные повторы и очередь ошибок.
7. Разделить технические и бизнесовые ошибки.
8. Проверить доступы, журнал и восстановление на пилоте.

Что такое API и чего оно не решает?

API описывает, как обратиться к системе: какой адрес и метод использовать, какие данные передать и какой ответ получить. Это упрощает связь сервисов, но не определяет бизнес-смысл полей и не устраняет расхождения автоматически.

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

Можно ли интегрировать именно ваши системы?

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

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

Что должно быть в контракте данных?

Контракт фиксирует не только названия полей. Он объясняет их смысл, обязательность, формат, допустимые значения и реакцию на несовместимую версию.

• сущность и событие: клиент создан, заказ изменён, платёж подтверждён;
• уникальный ID события и внешний ID записи;
• время события, часовой пояс и версия данных;
• обязательные и необязательные поля;
• закрытые справочники и допустимые статусы;
• формат ошибки с кодом и понятным описанием;
• правила обратной совместимости и вывода старой версии;
• пример корректного запроса, ответа и отказа.

Как выбрать REST API, вебхуки, OData или пакетный обмен?

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

Как выглядит интеграция сервисов по API на практике?

Для обмена CRM и учётной системы есть отдельный разбор интеграции CRM с 1С. Если штатного API недостаточно, сравните RPA и API до выбора технологии.

Как защититься от дублей?

Сеть может оборваться после выполнения операции, но до получения ответа. Отправитель повторит запрос, поэтому принимающая сторона должна узнать уже обработанную операцию.

1. Создать уникальный ключ бизнес-операции.
2. Передавать его при каждом повторе того же действия.
3. Хранить результат обработки ключа ограниченное время.
4. Возвращать прежний результат без второго изменения.
5. Связывать внешние ID записей обеих систем.
6. Отдельно решать настоящий повтор бизнеса и технический повтор доставки.

Номер телефона, имя клиента или сумма не подходят как единственный ключ. Они могут совпадать у разных операций.

Как настроить ошибки и повторы?

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

Бесконечный повтор маскирует проблему и создаёт нагрузку. После лимита сообщение попадает в отдельную очередь с причиной и безопасным способом перезапуска.

Как ограничить доступ интеграции?

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

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

Как сопоставить данные разных систем?

Сначала определяют источник истины для каждого атрибута. Например, реквизиты ведёт учётная система, а этап продажи хранит CRM. Двустороннее изменение одного поля без приоритета создаёт цикл конфликтов.

Практический пример такого разделения есть в материале про интеграцию CRM с 1С.

Что контролировать после запуска?

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

Уведомление должно вести к конкретной операции и понятному действию. Сообщение «интеграция сломалась» без ID и причины увеличивает простой.

Как проверить интеграцию на пилоте?

1. 01

   Одна сущность

   Выбрать ограниченный поток с измеримым результатом.

2. 02

   Контракт

   Согласовать поля, статусы, ID и ошибки.

3. 03

   Негативные сценарии

   Проверить дубли, таймауты, неверные данные и права.

4. 04

   Остановка

   Убедиться, что очередь сохраняется и восстанавливается.

5. 05

   Сверка

   Сопоставить записи и контрольные суммы двух систем.

6. 06

   Приёмка

   Передать журнал, инструкции и ответственность владельцам.

Что нужно для оценки разработки интеграции по API?

Универсальная цена по названиям систем будет неточной. Для диагностики достаточно передать исходную схему процесса и восемь параметров:

• названия, версии и документацию систем;
• сущности и поля, которые должны участвовать в обмене;
• направление для каждой сущности: в одну сторону или в обе;
• частоту, объём и допустимую задержку;
• требуемый уровень доступности и время восстановления;
• ошибки, которые должен исправлять человек, и правила повторов;
• требования к доступу, персональным данным и аудиту;
• ответственность за обновления API и поддержку версий после запуска.

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

Частые вопросы