Автоматизация бизнеса / Блог ontech.pro
Что делать, если внешний сервис изменил формат API
Внешний сервис изменил ответ, и интеграция перестала создавать сделки или начала пропускать важные поля. Иногда явной ошибки нет: обмен выглядит успешным, но результат неполный. Реакция должна начинаться с оценки затронутых операций и сохранения данных для восстановления.
Подготовила команда ontech.pro · · 3 мин чтенияУстановите характер изменения
Сравните последний корректный обмен с новым ответом и актуальной документацией поставщика. Проверьте адрес, версию, авторизацию, обязательные поля и смысл значений. Переименование статуса отличается от смены единицы суммы, а ограничение частоты запросов — от изменения структуры. Не публикуйте токены и клиентские данные в общем чате при разборе. Сохраните обезличенный пример, время события и идентификатор операции, чтобы разработчик мог воспроизвести проблему.
Ограничьте неправильные последствия
Если данные разбираются неверно, простое продолжение обмена может создавать ошибочные заказы. Определите, какие действия временно остановить, а какие можно продолжать безопасно. Входящие обращения по возможности сохраняйте в контролируемой очереди с понятным статусом. Сотрудникам объясните временный процесс и запрет на неподтверждённые массовые повторы. Не отключайте все системы автоматически, если проблема затрагивает только одну операцию; границу остановки выбирайте по реальным последствиям.
Не путайте разные причины отказа
Код HTTP 429 обозначает превышение допустимой частоты запросов; сервер может сообщить время ожидания через Retry-After. Это отдельный сценарий, для которого бесконечное немедленное повторение не является решением. Другие ответы разбирайте по документации конкретного API и содержимому сообщения. Даже успешный транспортный ответ нужно сопоставить с ожидаемым бизнес-результатом. Журнал должен помогать отличить временную недоступность, неверные права и непонятный формат.
Документация: RFC 6585: HTTP 429 и Retry-After
Исправьте договор обмена
Обновите сопоставление полей и правила проверки, сохранив совместимость там, где поставщик ещё принимает прежние варианты. Не подставляйте произвольное значение вместо исчезнувшего обязательного поля. Если изменился смысл данных, согласуйте его с владельцем бизнес-процесса. Проверьте обычный ответ, пустой результат, ошибку и неизвестное значение. Полезно сохранить эти примеры как контрольный набор, чтобы следующая правка интеграции не вернула прежнюю проблему.
Восстановите пропущенные операции
Определите период сбоя и судьбу каждой записи: не отправлена, принята, отклонена или результат неизвестен. Повторяйте только с учётом идентификаторов и возможности дублей. Сначала проведите небольшую проверяемую партию, затем сравните источник и получателя. Не считайте восстановлением только исчезновение ошибки в журнале: нужны созданные сделки, правильные суммы и связи. Ручные исправления сотрудников за время сбоя следует учитывать, иначе восстановленный обмен перезапишет их работу.
Подготовьтесь к следующему изменению
Назначьте получателя объявлений поставщика, учёт используемых версий и регулярную проверку ключевого сценария. Обновите инструкцию поддержки и перечень признаков неисправности. Важный итог инцидента — не только новый обработчик, но и способ заметить несовместимость до того, как её впервые обнаружит клиент.