redigomarket
Сервисы и автоматизация

Замена API-ключа маркетплейса без остановки интеграции

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

Замена API-ключа маркетплейса без остановки интеграции

Замена API-ключа маркетплейса без сбоев

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

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

Сначала выясните, допускает ли площадка перекрытие ключей

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

  • Можно ли выпустить второй ключ до отзыва первого?
  • Связаны ли ключ с конкретным продавцом, кабинетом или набором категорий?
  • Отзыв одного ключа оставляет второй активным?
  • Какие процессы ещё используют прежние учётные данные, включая фоновые задачи, BI-коннекторы, CRM и вебхуки?

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

КонтурЧто проверять перед ротацией
WildberriesТип выданного ключа, режим использования и доступ к нужным категориям. Тестовые учётные данные нельзя оставлять в рабочем контуре.
OzonВ типовой схеме Seller API авторизация опирается на связку Client-Id + Api-Key. Обновлять её следует согласованно, иначе новый ключ не компенсирует смену идентификатора клиента.
Yandex MarketВ части методов используется OAuth-подход с токеном и реквизитами клиента. Сначала нужно определить, какой именно секрет обновляется и требуется ли перевыпуск связанных параметров.

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

Нулевой простой обеспечивает заранее спроектированное перекрытие двух рабочих версий ключа, а не сам факт выпуска нового токена.

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

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

Подготовка и тестирование нового ключа

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

1. Проверьте права и привязку к аккаунту

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

Для multi-account setups отдельно сверяются:

  • идентификатор продавца;
  • юридическое лицо и кабинет;
  • доступные категории;
  • тип ключа: тестовый, боевой или общий;
  • доступ к нужным складам и каналам.

2. Проверьте чтение реальных данных

Для проверки используется минимальный read-метод, возвращающий сведения о продавце или текущем состоянии ресурса. Ответ должен показать ожидаемый account ID, актуальные данные и корректную временную метку.

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

3. Отдельно проверьте запись

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

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

4. Проверьте лимиты и задержку

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

  • время ответа на одинаковых методах;
  • частоту 429 Too Many Requests;
  • количество одновременных запросов;
  • задержку обновления данных;
  • стабильность соединения при длинных опросах.

5. Прогоните отрицательный тест авторизации

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

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

6. Сверьте выданный ключ с секретом в хранилище

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

Переключение трафика без остановки

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

ЭтапСтарый ключНовый ключРабочий трафикТочка отката
ПодготовкаАктивенХранится как stagedОбслуживается старымУдалить новую версию
Теневой тестАктивенПроверяет только чтениеОбслуживается старымПрекратить тестовые запросы
CanaryАктивенОбслуживает небольшую часть трафикаРаспределяется между версиямиВернуть всю нагрузку старому
Основной трафикРезервныйОсновнойОбслуживается новымПовторно назначить старый
ЗавершениеОтозванЕдинственный активныйОбслуживается новымОтката через старый ключ уже нет

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

Процессы, которые читают токен только при запуске, требуют отдельного внимания. Перезапуск одного контейнера не обновляет-token в уже работающих соседних процессах. Надёжнее получать актуальную credential version на каждый запрос либо поддерживать горячую перезагрузку через watcher конфигурации. При этом один запрос должен использовать одну версию от начала до конца.

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

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

Отзыв старого ключа и контроль ошибок

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

  • новый ключ используется во всех экземплярах приложения;
  • заказы и остатки обновляются с ожидаемой задержкой;
  • фоновые выгрузки завершаются успешно;
  • рекламные и складские процессы не возвращают ошибки авторизации;
  • вебхуки продолжают обрабатываться;
  • в логах нет запросов со старой credential version.

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

Для контроля авторизации нужны отдельные метрики:

  • количество 401, 403 и 429 в разрезе credential version;
  • доля ошибок по каждому методу API;
  • время ответа и распределение задержек;
  • глубина очереди и число повторных попыток;
  • возраст последних обновлений заказов, цен и остатков;
  • количество запросов со старым ключом;
  • подтверждение успешной записи по каждому типу операции.

Отпечаток ключа можно сформировать как короткий хеш или внутренний идентификатор версии. Сам токен в метрики, URL и журналы не попадает.

Ответ APIЧто обычно означаетРеакция
401 UnauthorizedТокен недействителен, отозван, истёк, передан не в том заголовке либо сервис его не распозналПроверить активную версию, формат credential и источник секрета
403 ForbiddenЗапрос распознан, но недостаточно прав или есть ограничение аккаунтаСверить scopes, продавца, категории и состояние кабинета
429 Too Many RequestsИсчерпана частота или квотаСнизить нагрузку, применить backoff; ротация обычно не помогает
5xxОшибка на стороне сервисаПроверить статус площадки и корреляцию с конкретной версией ключа
Таймаут после записиРезультат операции неизвестенСначала сверить состояние объекта, затем принять решение о повторе
Успешный ответ со старыми даннымиРаботает кэш, завис worker или очередьПроверить freshness данных и задержку конвейера

Ошибки авторизации нельзя объединять в один счётчик. Для 401 требуется восстановление доступа, для 403 — проверка разрешений, для 429 — управление темпом запросов.

Безопасное хранение токенов и защита от отката

Ротация становится рискованной, если секрет заранее размазан по репозиториям, .env, образам контейнеров, CI/CD и ручным таблицам. Рабочий контур лучше строить вокруг специализированного хранилища секретов: Vault, облачного Secret Manager или управляемого KMS-слоя.

Минимальная практика выглядит так:

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

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

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

Типовые баги, которые ломают ротацию

1. Старый токен остаётся в памяти процесса. Перезапуск обновляет часть workers, но pooled connections или фоновые задачи продолжают использовать прежнюю версию.

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

3. Ротация идёт без реестра потребителей. Ключ заменили в основном API-клиенте, забыв про BI-коннектор, CRM, ETL и cron-задачу.

4. Ошибка 401 вызывает бесконечный retry. Повтор с заведомо неверным токеном создаёт нагрузку на API и засоряет журналы.

5. Таймаут автоматически приводит к повторной записи. Особенно опасно для создания заказов и безналичного списания.

6. Старый ключ отзывают слишком рано. Откат возможен только до отзыва. После отзыва возвращение к прежней версии требует выпуска нового ключа.

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

8. В логи попадает заголовок Authorization. Даже краткое попадание токена в журнал создаёт риск восстановления доступа посторонним человеком.

9. Не учитывают квоты конкретной версии. Canary способен упереться в отдельный лимит и дать 429, который ошибочно примут за проблему авторизации.

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

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

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