Интеграция принимает заказ, создаёт сделку и ставит задачу менеджеру. Разработчик видит новую версию REST и предлагает заменить адреса запросов во всём обработчике. Но рабочий процесс затрагивает разные методы, форматы данных и обработку ошибок. Замена одного фрагмента URL не подтверждает, что заказ пройдёт весь маршрут.
REST 3.0 стоит рассматривать как изменение контракта обмена. Ниже — предлагаемая схема перехода для действующей интеграции, а не отчёт о выполненном клиентском проекте. Она помогает решить, что переносить сейчас, что оставить работающим и какими проверками подтвердить результат.
Что проверить до оценки переделки #
По официальному обзору REST 3.0 , прежняя и новая версии сосуществуют. Доступность конкретных методов нужно проверять по документации и OpenAPI своего портала. У новой версии отличаются путь вызова, требования к телу запроса и структура ответа. Поэтому сначала нужен перечень операций вашей интеграции.
Для каждого шага запишите объект, метод, входные поля, ожидаемый результат и следующий шаг. Отдельно отметьте создание, изменение и чтение. Чтение сделки можно повторить без появления второй сделки; повтор создания требует другого решения. Если сценарий вызывает таймлайн или генератор документов, его нельзя считать перенесённым только потому, что удалось получить карточку CRM.
Снимите обезличенные примеры реально используемых ответов: пустой список, несколько страниц, пользовательские поля, удалённый объект, отказ доступа. Именно такие ответы часто обнаруживают зависимости, которых нет в коротком описании обмена. Не копируйте в рабочие примеры токены, клиентские сообщения и действующие ссылки вебхуков.
Выберите законченный участок процесса #
Первая порция миграции должна иметь понятную границу. Например, получение карточки и связанных сведений для внутреннего отчёта. Если отчёт ошибётся, его можно остановить, не создавая внешних обязательств. Начинать с массового создания сделок только ради проверки новой версии опасно для качества данных.
Разделите транспортный адаптер и бизнес-правила. Адаптер знает адрес, параметры, формат ответа и ошибки выбранной версии. Остальная программа получает вашу стабильную внутреннюю модель: идентификатор сделки, ответственный, стадия, нужные поля. Тогда следующий метод можно переносить отдельно, а не переписывать все условия продаж.
Не возвращайте в приложение необработанный ответ API как будто его структура неизменна. Если старый код извлекает значение по одному вложенному пути, новый ответ должен пройти явное преобразование и проверку. Неизвестное поле не равно пустому: пустое значение может очистить уже заполненную информацию при обратной записи.
Сначала сравните чтение, затем переключайте запись #
На контрольной выборке прочитайте одни и те же объекты через оба адаптера. Сравните нормализованные значения, а не порядок полей в JSON. Проверьте даты и часовые пояса, денежные значения, множественные поля и отсутствие доступа к части записей. Разницу оформляйте как конкретное расхождение с ID объекта и названием поля.
Для операций записи два варианта не должны одновременно изменять рабочую CRM. Подход «старый обработчик продолжает работать, а новый для проверки тоже создаёт сделки» сам порождает дубли. Новый путь сначала проверяют на отдельном наборе тестовых карточек, затем назначают единственным исполнителем выбранной операции.
Границу переключения фиксируют в журнале: какое событие обрабатывается какой версией. Уже начатый заказ следует довести согласованным способом. Иначе старая версия создаст карточку, а новая, не увидев сохранённую связь, создаст ещё одну.
Повтор запроса и новая операция — разные вещи #
В REST 3.0 предусмотрен заголовок Idempotency-Key: при совпадении ключа и тела запроса сохранённый ответ можно получить повторно в пределах 24 часов. Это защита конкретного вызова. Она не заменяет постоянную связь заказа внешней системы с объектом CRM и не делает весь многошаговый процесс одной транзакцией.
В предлагаемой архитектуре запись о внешнем заказе хранит ID созданной сделки и состояние каждого шага. Если после создания сделки не удалось поставить задачу, восстановление начинает с задачи. Оно не создаёт заказ заново. При неизвестном результате после сетевого обрыва сначала выясняют состояние операции, а не объявляют её неуспешной.
Ключ повторного запроса нужно сохранить до первой отправки. Генерация нового ключа при каждой попытке не позволяет отличить повтор от новой операции. При этом изменение состава заказа — новая бизнес-редакция, которую нельзя незаметно отправить как прежнее тело. Подробнее различие между повтором и новым действием разобрано в статье об однократном выполнении действий .
Как понять, что участок готов к переключению #
Проведите один заказ от входного события до проверяемого результата. Остановите обработку после каждого внешнего шага и восстановите её. Отправьте повтор, изменённую редакцию и событие для недоступной карточки. В результате должна остаться одна согласованная сделка, а незавершённый шаг — получить понятное состояние и владельца разбора.
Сравнивайте число исходных операций и подтверждённых результатов. Успешный HTTP-ответ сам по себе не доказывает сохранение всех товарных строк или создание связанной задачи. Для чтения полезна сверка контрольной выборки; для записи — журнал связей и отдельный список расхождений.
Подготовьте обратное переключение до выпуска: какие события остановить, как сохранить очередь и откуда продолжить обработку. Возврат старого адаптера не должен автоматически повторять уже выполненные действия. Если формат внутренних данных изменился, отдельно проверяют, что прежний код сможет прочитать накопленную очередь.
Обязательно ли переносить работающий обмен целиком? #
Нет. Сначала определите пользу конкретного изменения: нужный метод, удобство получения связанных данных, понятная обработка ошибок. Если действующий участок стабилен и новая версия не решает его проблему, его можно оставить до следующего обоснованного изменения. Решение принимают по перечню зависимостей, а не по номеру версии.
Что передать подрядчику для оценки? #
Карту операций, используемые методы, обезличенные примеры ответов и ошибок, правила повторов, объём потока и критерии приёмки. Формулировка «перевести на REST 3.0» без этих сведений не определяет ни состав работ, ни границы проверки.
Начните с карты действующего обмена #
NetLabCS поможет разобрать зависимости, выделить участок миграции и организовать сверку в рамках интеграции Битрикс24 с внешними сервисами по API . Для обсуждения задачи подготовьте один рабочий маршрут: от входного события до последнего изменения в CRM. По нему определим безопасную границу перехода и проверяемый результат.
