Лучшие практики интеграции с API Яндекс Маркета для продавцов
Эта страница предназначена для разработчиков и технических специалистов, которые создают, обслуживают или поддерживают интеграции с API Яндекс Маркета.
Цель статьи — помочь выстроить интеграцию с API Маркета, которая устойчиво работает под нагрузкой и обеспечивает безопасную обработку данных магазина.
Общие принципы интеграции
- Запрашивайте только те данные, которые нужны текущему сценарию
- Соблюдайте ограничения на запросы и равномерно распределяйте нагрузку во времени
- Используйте API‑уведомления вместо частого опроса методов
- Отслеживайте долю ошибок по методам и сценариям интеграции
- Проектируйте интеграцию с учетом требований безопасности
Работа с методами API
Проектируйте интеграцию устойчивой к изменениям
- Обрабатывайте только те поля, которые нужны сценарию, и пропускайте незнакомые элементы и поля
- Не полагайтесь на порядок полей, ориентируйтесь по их названиям
- Для перечислений (статусы, типы и так далее) предусмотрите значение по умолчанию для неизвестных значений и не допускайте падения из‑за ошибки парсинга
- Регулярно обновляйте клиентские модели по актуальной спецификации OpenAPI: используйте свежую версию спецификации с GitHub для пересборки клиента
- Следите за новостями API в истории обновлений и пометками об устаревании методов в документации и спецификации
- Планируйте переход на новые методы до момента полного отключения устаревших, чтобы избежать сбоев в интеграции
Запрашивайте только нужные данные
- Используйте фильтры методов по времени изменения, статусам и типам сущностей
- Настраивайте выборки под конкретные сценарии, а не запрашивайте полный набор данных из метода
- Старайтесь оптимизировать интеграцию так, чтобы не выполнять лишние запросы к API
Примеры:
Надежность, ошибки и лимиты
Разделяйте 4xx и 5xx и настраивайте повторы
- Настройте повторы при ответах 5xx и сетевых сбоях
- Делайте паузы между повторами, увеличивайте их длительность по экспоненте и добавляйте небольшую случайную задержку при каждом повторе
- Не выполняйте повторы при ответах 4xx: исправляйте причину клиентской ошибки вместо повторной отправки запроса
- При росте доли 4xx проверяйте корректность запросов: параметры, схему данных, актуальность используемых методов
Описание ошибок, возвращаемых API Маркета
Настройте сетевые параметры под интеграцию
- Задайте достаточные таймауты подключения и чтения — недостаточные таймауты могут приводить к ошибкам 499 (Client Closed Request)
- Используйте rate limiter или очередь задач, чтобы равномерно распределять запросы по времени, избегать всплесков трафика и не превышать лимиты
Включите логирование и мониторинг ошибок
- Логируйте информацию о вызовах методов: статус, заголовки и тела запросов и ответов
- Сохраняйте уникальный идентификатор запроса
traceparentдля поиска в разделе Логи запросов — это поможет вам и службе поддержки Маркета быстро найти конкретный запрос для анализа - Группируйте ошибки по типам (400 — неверные параметры, 401/403 — авторизация и доступы, 404 — отсутствующие ресурсы, 420 — превышение лимитов и так далее), отслеживайте их долю во времени и постройте дашборд с ошибками по методам и типам, чтобы быстро замечать всплески
- Настройте алерты по порогам ошибок (например, рост 404 для конкретного метода), чтобы получить уведомления и принять меры до того, как сбой начнет влиять на работу магазина
Авторизация и безопасность
Используйте актуальную схему авторизации и минимальные доступы
- Используйте схему авторизации Api‑Key для интеграций продавцов
- Ограничивайте доступы ключей минимально необходимыми для работы
- Создавайте отдельные Api‑Key для разных интеграций и настраивайте для каждого минимально необходимые доступы, чтобы ограничить возможный ущерб при утечке
- Для приема уведомлений проверяйте, что запросы приходят только с доверенных IP-адресов Яндекса. Список доверенных IP-адресов
Обеспечьте безопасное хранение и использование ключей
- Храните ключи авторизации и токены в хранилищах секретов, не добавляйте их в исходный код, логи и переписки
- Регулярно пересматривайте список активных ключей, удаляйте неиспользуемые и меняйте ключи при смене подрядчика или интегратора
Лучшие практики по сценариям
Заказы
- Для получения изменившихся заказов используйте параметр времени обновления и ограниченный интервал
- Используйте фильтры по времени создания, статусов и другим параметрам, чтобы получать только нужные заказы под конкретный сценарий
- Используйте API‑уведомления для событий по заказам вместо частых запросов
Остатки и цены
- Регулярно передавайте информацию по изменившимся позициям
- Передавайте только изменившиеся позиции, а не полный ассортимент
- Группируйте изменения в пакетные запросы допустимого размера и избегайте большого количества небольших запросов
- Синхронизируйте остатки и цены из единого источника данных, чтобы избежать расхождений между каналами продаж
Ассортимент и карточки товаров
- Используйте достаточно крупную пагинацию, чтобы не выполнять тысячи коротких запросов
- Планируйте расписание обновлений под бизнес‑потребность, а не чаще, чем это действительно требуется
- При добавлении и изменении ассортимента обязательно проверяйте перечень ошибок results.errors и замечаний results.warnings в ответе: при наличии ошибок изменения по всем переданным товарам не будут применены
Отчеты и аналитика
- Для аналитики за большие периоды используйте асинхронные отчеты
- Планируйте генерацию и скачивание отчетов по расписанию, равномерно распределяйте запросы во времени и сохраняйте результат локально до следующей регенерации
- Запрашивайте только те типы отчетов и только по тем магазинам, которые действительно нужны сценариям продавца
- Учитывайте, что структура и содержание отчетов могут меняться без предварительного уведомления: может появиться новая колонка или измениться название листа
Уведомления
- Подтверждайте прием уведомления быстрым ответом
- Отправляйте дальнейшую обработку события в очередь и выполняйте ее асинхронно
- Передавайте ошибку в ответе, если уведомление не принято
Была ли статья полезна?
Предыдущая
Следующая