API между системами — контракт данных, ошибки и повторные запросы

API — это договорённый интерфейс, через который программа запрашивает данные или действие у другой программы. Сайт может через API создать сделку в CRM, получить остаток из учётной системы, отправить платёж или показать статус доставки.

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

API не является отдельным волшебным сервисом между системами. На стороне поставщика запрос исполняет backend, на стороне сайта результат показывает frontend, а канал обычно защищает HTTPS. API задаёт понятный обеим сторонам способ разговора. Через него же headless CMS отдаёт контент отдельным интерфейсам, не связывая редактуру с одной витриной.

API — не труба для данных, а версионируемый договор о командах, значениях и ошибках.

В HTTP API клиент обращается к адресу — endpoint. Метод помогает выразить намерение: получить представление, создать ресурс, изменить или удалить. Конкретная семантика определяется контрактом и правилами HTTP.

Примеры:

Адрес /orders/123 сам по себе ничего не гарантирует. Документация должна объяснить, что означает 123, какие роли имеют доступ, какие поля возвращаются и что произойдёт, если заказ отсутствует.

Запрос включает параметры, заголовки и иногда тело. Ответ содержит статус, заголовки и данные. JSON распространён, но не обязателен: API может передавать XML, файл, изображение или другой формат. Важна не популярность формата, а однозначная схема.

Локальная касса или агент становятся отдельной границей API, когда запросы идут в локальную сеть; адреса, методы и разрешения нужно проверить в реальной среде.

До описания endpoint нужно договориться об объектах. «Клиент» в CRM может быть контактом, компанией или парой сущностей. «Заказ» на сайте — оформленная корзина, в 1С — документ реализации, в службе доставки — отправление. Одинаковые слова не означают одинаковую модель.

Полезная карта:

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

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

Главная сложность интеграции обычно находится не в отправке JSON, а в одинаковом понимании сущностей.

OpenAPI 3.2 позволяет описывать HTTP-операции, параметры, схемы запросов и ответов. Это полезный формальный слой, но хороший контракт шире. Файл спецификации описывает обещанный интерфейс; сам по себе он не доказывает, что рабочая среда отвечает по нему, выдерживает лимит или правильно обрабатывает повтор. Валидация схемы и контрактный тест подтверждают только проверенный документ, ответ и контур, а не доступность или сохранность данных в production.

Нужны:

Сгенерированная страница документации помогает разработчику вызвать endpoint. Она не объясняет, считается ли сделка созданной после ответа или после внутренней обработки, можно ли повторить запрос и где смотреть журнал.

Для внешней интеграции полезен sandbox или тестовый контур. Он должен быть достаточно похож на рабочий: те же схемы и классы ошибок, безопасные тестовые ключи, предсказуемые данные. «Проверить сразу в production» экономит настройку только до первого ошибочного заказа.

Аутентификация устанавливает, кто обращается к API. Это может быть ключ, OAuth-токен, сертификат или подписанный запрос. Ключ нельзя считать логином человека: обычно он идентифицирует приложение или интеграцию.

Авторизация определяет, что клиенту разрешено. Валидный токен CRM не должен автоматически давать чтение всех сделок. Интеграции, которая создаёт лиды, не нужен доступ к удалению пользователей.

Scope ограничивает заявленные полномочия токена, но не заменяет проверку доступа к конкретному объекту на каждом запросе. Полученный от клиента ID нельзя считать подтверждением права на объект.

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

Практический минимум:

Защищённый канал предотвращает чтение токена в пути, но не спасает от украденного секрета в репозитории или расширенных полномочий.

HTTP-статус сообщает класс результата. Успех, ошибка клиента и ошибка сервера требуют разного поведения. Однако одного кода недостаточно.

Представим запрос на создание заказа:

Тело ошибки должно содержать безопасный машинный код, понятное описание и сведения, по которым клиент решит, что делать. RFC 9457 предлагает формат problem details для HTTP API, но не заменяет семантику HTTP-статуса: поле status в теле лишь дублирует его и должно ему соответствовать. В ответ нельзя без необходимости включать стек и внутренние детали.

Если поставщик отвечает 200, хотя заявленная HTTP-операция не выполнена, статус вводит клиента в заблуждение и ломает стандартную обработку. Отдельный бизнес-результат в JSON уместен, только когда сам запрос действительно выполнен по описанной семантике и контракт однозначно отделяет его от последующей операции.

Для асинхронной обработки 202 Accepted прямо означает, что запрос принят, но ещё не завершён; контракт должен дать способ проверить итог. 200 OK допустим, если успешно выполнена именно заявленная операция, например постановка сообщения в очередь, и это ясно названо в контракте.

Например, API принял заявку в очередь и вернул технический успех. Позже CRM отклонила поле. Интерфейс не должен сообщать «менеджер получил заявку», если подтверждён только первый шаг.

Клиент не всегда знает, завершилась ли операция. Тайм-аут или разрыв соединения могут наступить после записи на стороне поставщика, но до ответа клиенту. Повтор — нормальная реакция на временную ошибку, поэтому проект обязан учитывать его заранее.

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

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

Автоматический retry применяют не ко всем ошибкам. RFC 9110 не рекомендует автоматически повторять неидемпотентный запрос, если клиент не знает, что его семантика идемпотентна, или не может установить, что исходный запрос не применён. Для 429 или временной недоступности учитывают Retry-After, если сервер его прислал, и увеличивают паузу между попытками (backoff) с пределом и разбросом. Retry-After и прочие заголовки лимитов могут отсутствовать, а их набор и смысл не универсальны. Контракт должен назвать, какие ответы можно повторять, сколько попыток допустимо и кто увидит операцию, которая не завершилась автоматически.

При опросе клиент регулярно спрашивает: «появились ли изменения?». Это просто, но создаёт задержку и лишние запросы.

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

Webhook не является гарантией завершения. Получатель может быть недоступен, ответить ошибкой, обработать сообщение дважды или принять его, но сломаться на следующем шаге. Поэтому нужны подпись, ID события, повторная доставка, защита от дубля и журнал. Подпись проверяют по исходному телу и алгоритму поставщика; для защиты от повторного воспроизведения контракт задаёт метку времени и допустимое окно, nonce или уникальный ID события. Схема заголовков, ротация секрета и порядок повторов у поставщиков различаются.

Webhook доказывает попытку сообщить о событии, а не выполнение всей цепочки у получателя.

Иногда лучший вариант сочетает webhook и сверочный опрос. Уведомления дают скорость, а периодическая проверка находит пропуски. Это дороже, но оправдано для критичных платежей и заказов.

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

Список из десяти тысяч товаров обычно возвращают страницами. Важно определить:

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

Выгрузка «всего каталога каждую минуту» может работать на тесте и сломаться после роста. Инкрементальный обмен уменьшает объём, но требует надёжного маркера изменений и периодической полной сверки.

Большие файлы и долгие отчёты часто обрабатывают асинхронно: запрос создаёт задачу, клиент получает ID, проверяет статус и скачивает результат после готовности. Тайм-аут одного HTTP-запроса не должен определять предел бизнес-процесса.

API меняется вместе с продуктом. Без политики версий поставщик может незаметно переименовать поле или изменить справочник, а клиент узнает об этом из ошибок.

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

Политика должна отвечать:

Клиент тоже обязан быть устойчивым: не падать из-за неизвестного необязательного поля, корректно обрабатывать неизвестный статус и не зависеть от порядка свойств JSON.

Интеграция может быть технически доступна и передавать неправильные данные. Поэтому нужен контроль нескольких уровней.

Технический уровень:

Бизнес-уровень:

Для CRM важно проследить путь до назначенной сделки. Для учётной системы — владельца товара, цены, остатка и заказа; такую прикладную роль 1С:Предприятия полезно отделять от самого механизма обмена. Единый график «API работает» эти разные процессы не описывает.

Заполните её для каждого критичного действия.

К карточке добавьте карту полей с примерами и три контрактных теста: нормальный, граничный и ошибочный. Для критичного действия проверьте также повтор одного сообщения, неизвестное необязательное поле, недоступность получателя и итоговую бизнес-сверку. Это не обещает «ровно один раз», доступность production, сохранность данных или доставку третьей стороной, но показывает, какие последствия повтора и сбоя стороны согласовали и проверили в выбранном контуре.

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

Наличие API у двух продуктов ещё не означает готовую интеграцию. Между ними остаётся работа по сопоставлению данных и ответственности.

Если проект пока описан фразой «связать сайт, CRM и 1С», Xleb может разобрать одну операцию и собрать карту полей, ошибок и владельцев. Такой контракт даёт основу для оценки и приёмки, не привязывая бизнес к неопределённому обещанию «API есть».