Поставщик меняет API: как перевести интеграции на новую версию?

Как начать переход на новую версию API?

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

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

Зафиксируйте исходные условия в одном рабочем документе:

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

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

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

Какие изменения API могут нарушить работу интеграции?

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

В рекомендациях Google AIP-180 удаление компонента API и изменение значения по умолчанию рассматриваются как несовместимые изменения. Используйте эти примеры как ориентир при анализе; фактические правила версионирования и поддержки уточняйте у своего поставщика.

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

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

Как найти все системы, зависящие от API?

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

Для каждого потребителя заполните отдельную строку:

Рассмотрим учебную ситуацию: ERP передаёт заказы внешней службе доставки, а затем получает статусы отправлений. В новой версии поставщик меняет поля статусов. Это условный пример, не описание клиентского проекта DYNAMICSUN.

В таком реестре стоит отдельно отразить создание отправления и получение его состояния. Для первой операции нужно подтвердить связь заказа с созданным отправлением; для второй — правильное отображение состояния в ERP. Одного общего пункта «интеграция с доставкой» для приёмки недостаточно.

Исходными данными примера будут обезличенные заказы, идентификаторы отправлений и согласованная таблица статусов. Обработчик сопоставляет новые значения с состояниями ERP. Владелец логистического процесса утверждает соответствия и разбирает исключения. Показатель проверки — доля сверенных заказов с объяснимым результатом; допустимые расхождения согласуют до запуска, а не после него.

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

Как проверить новую версию до переключения?

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

Такой подход согласуется с практикой конкретных поставщиков: например, документация GitHub по версиям API рекомендует после обновления проверить, что интеграция работает с новой версией. Условия и сроки поддержки GitHub при этом нельзя переносить на другой сервис.

Включите в программу испытаний:

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

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

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

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

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

Как выбрать способ переключения?

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

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

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

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

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

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

В плане восстановления разделите три задачи:

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

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

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

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

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

Что подготовить для обсуждения проекта с DYNAMICSUN?

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

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

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

Пришлите описание систем, документацию старой и новой версии API и известную дату отключения: обсудим обследование интеграции и состав работ по переходу.

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