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