API-интеграция: 8 правил данных до разработки

В карточке заказа уже стоит «оплачен». В CRM он ещё ждёт подтверждения. Склад видит заказ как отменённый: более раннее событие пришло позже нового. Все системы ответили с 200 OK, а оператору всё равно приходится выяснять, кому верить.

Такая ситуация возникает, когда стороны согласовали URL, токен и JSON, но оставили без ответа вопросы о владельце записи, смысле статуса и правилах изменения данных. У сущности должен быть владелец, у изменения — причина, у повтора — ожидаемый результат. Эти решения определяют работу личного кабинета, поддержки, оплаты и склада ещё до первой строки интеграционного кода.

API передаёт значение. Интеграция должна сохранить его смысл

Спецификация OpenAPI описывает структуру запроса и ответа. Схема не определяет, что именно означает status: "paid": успешный callback провайдера, проверка суммы, бухгалтерское проведение или подтверждение оператора. Пока смысл статуса не зафиксирован, у каждой системы появляется собственная версия процесса.

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

Восемь решений до первой задачи в разработке

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

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

Сущность, идентификаторы и владелец данных

У сущности почти всегда больше одного идентификатора. UUID нужен сервису как технический уникальный ID записи. Номер заказа нужен оператору. Идентификатор контрагента приходит из ERP, а внешний платёжный ID помогает провести сверку. Риск появляется, когда один из них начинают использовать как универсальный ключ без правила, кто его создаёт и может ли он измениться.

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

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

Поля, которые нельзя трактовать по-разному

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

У каждой важной характеристики стоит записать:

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

Время требует отдельного правила. Запись без часового пояса для одной системы может быть московским временем, для другой — UTC, для третьей — временем пользователя. В контракте фиксируют формат, часовой пояс и то, описывает ли значение момент, дедлайн или локальный слот в расписании.

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

Статусы и момент фиксации

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

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

Здесь определяется момент истины: достаточно ли уведомления от платёжного провайдера для статуса «оплачен» или статус меняется после проверки подписи, суммы и валюты. Одно понятное правило устраняет разные трактовки между оплатой, складом и поддержкой.

События, порядок и повторы

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

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

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

Повтор запроса и конфликт изменений

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

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

Доступ, страницы, ошибки и версии

Роль описывает, кто пользователь. Интеграции нужен следующий уровень: к какой организации, заказу, складу или документу у него есть доступ и какие поля он может увидеть или изменить. Матрица «субъект — объект — операция — поле» нужна API, интерфейсу и журналу аудита.

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

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

Версия контракта даёт потребителям время увидеть изменение и перейти на новую схему. В опросе Postman функциональные и интеграционные тесты использовали по 67% участников, контрактные — 17%. Выборка не описывает весь рынок, но показывает, почему проверку совместимости лучше не переносить на финальную неделю.

Проверка контракта на сценариях

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

Исследование о consumer-driven contract testing связывает такой подход с ранним обнаружением ломающих изменений между поставщиком и потребителем API. Проверочные сценарии переводят продуктовые решения в наблюдаемое поведение системы.

С чего начать

Минимальный артефакт перед разработкой помещается на одной странице: восемь решений из таблицы, два или три JSON-примера и имя владельца каждого решения. С ним команда оценивает правила, миграции, тесты и риски вместе с количеством эндпоинтов.

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

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

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