--- metadata: - name: generator content: Diplodoc Platform v5.55.0 alternate: - https://yandex.com/dev/market/partner-api/doc/en/concepts/best-practices.md - https://yandex.com/dev/market/partner-api/doc/ru/concepts/best-practices.md - https://yandex.com/dev/market/partner-api/doc/zh/concepts/best-practices.md - href: ru/concepts/best-practices.md type: text/markdown title: Markdown version - href: ../llms.txt type: text/markdown title: llms.txt --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/market/partner-api/doc/ru/llms.txt # Лучшие практики интеграции с API Яндекс Маркета для продавцов Эта страница предназначена для разработчиков и технических специалистов, которые создают, обслуживают или поддерживают интеграции с API Яндекс Маркета. Цель статьи — помочь выстроить интеграцию с API Маркета, которая устойчиво работает под нагрузкой и обеспечивает безопасную обработку данных магазина. ## Общие принципы интеграции - Запрашивайте только те данные, которые нужны текущему сценарию - Соблюдайте ограничения на запросы и равномерно распределяйте нагрузку во времени - Используйте API‑уведомления вместо частого опроса методов - Отслеживайте долю ошибок по методам и сценариям интеграции - Проектируйте интеграцию с учетом требований безопасности ## Работа с методами API ### Проектируйте интеграцию устойчивой к изменениям - Обрабатывайте только те поля, которые нужны сценарию, и пропускайте незнакомые элементы и поля - Не полагайтесь на порядок полей, ориентируйтесь по их названиям - Для перечислений (статусы, типы и так далее) предусмотрите значение по умолчанию для неизвестных значений и не допускайте падения из‑за ошибки парсинга - Регулярно обновляйте клиентские модели по актуальной [спецификации OpenAPI](https://yandex.com/dev/market/partner-api/doc/ru/concepts/openapi.md): используйте свежую версию спецификации [с GitHub](https://github.com/yandex-market/yandex-market-partner-api) для пересборки клиента - Следите за новостями API в [истории обновлений](https://yandex.com/dev/market/partner-api/doc/ru/changelog/all.md) и пометками об устаревании методов в документации и спецификации - Планируйте переход на новые методы до момента полного отключения устаревших, чтобы избежать сбоев в интеграции ### Запрашивайте только нужные данные - Используйте фильтры методов по времени изменения, статусам и типам сущностей - Настраивайте выборки под конкретные сценарии, а не запрашивайте полный набор данных из метода - Старайтесь оптимизировать интеграцию так, чтобы не выполнять лишние запросы к API Примеры: - [Просмотр товаров в кабинете](https://yandex.com/dev/market/partner-api/doc/ru/reference/business-offer-mappings/getOfferMappings.md) - [Список заказов](https://yandex.com/dev/market/partner-api/doc/ru/reference/orders/getBusinessOrders.md) ### Правильно обрабатывайте пагинацию по `pageToken` - Наличие следующей страницы определяйте **только** по полю `nextPageToken` в ответе, а не по количеству элементов на текущей странице - Число строк в ответе может быть меньше переданного или ожидаемого `limit` (например, если значение `limit` автоматически уменьшили до допустимого максимума) — это не значит, что данных больше нет - Продолжайте запросы, пока в ответе есть `nextPageToken`; если параметра нет — это последняя страница [Как работает пагинация](https://yandex.com/dev/market/partner-api/doc/ru/concepts/pagination.md) ## Надежность, ошибки и лимиты ### Разделяйте 4xx и 5xx и настраивайте повторы - Настройте повторы при ответах 5xx и сетевых сбоях - Делайте паузы между повторами, увеличивайте их длительность по экспоненте и добавляйте небольшую случайную задержку при каждом повторе - Не выполняйте повторы при ответах 4xx: исправляйте причину клиентской ошибки вместо повторной отправки запроса - При росте доли 4xx проверяйте корректность запросов: параметры, схему данных, актуальность используемых методов [Описание ошибок, возвращаемых API Маркета](https://yandex.com/dev/market/partner-api/doc/ru/concepts/error-codes.md) ### Настройте сетевые параметры под интеграцию - Задайте достаточные таймауты подключения и чтения — недостаточные таймауты могут приводить к ошибкам 499 (Client Closed Request) - Используйте rate limiter или очередь задач, чтобы равномерно распределять запросы по времени, избегать всплесков трафика и не превышать лимиты [Описание работы с лимитами](https://yandex.com/dev/market/partner-api/doc/ru/concepts/limits.md) ### Включите логирование и мониторинг ошибок - Логируйте информацию о вызовах методов: статус, заголовки и тела запросов и ответов - Сохраняйте уникальный идентификатор запроса `traceparent` для поиска в разделе [Логи запросов](https://yandex.com/dev/market/partner-api/doc/ru/concepts/debug.md) — это поможет вам и службе поддержки Маркета быстро найти конкретный запрос для анализа - Группируйте ошибки по типам (400 — неверные параметры, 401/403 — авторизация и доступы, 404 — отсутствующие ресурсы, 420 — превышение лимитов и так далее), отслеживайте их долю во времени и постройте дашборд с ошибками по методам и типам, чтобы быстро замечать всплески - Настройте алерты по порогам ошибок (например, рост 404 для конкретного метода), чтобы получить уведомления и принять меры до того, как сбой начнет влиять на работу магазина ## Авторизация и безопасность ### Используйте актуальную схему авторизации и минимальные доступы - Используйте схему авторизации **Api‑Key** для интеграций продавцов - Ограничивайте доступы ключей минимально необходимыми для работы - Создавайте отдельные **Api‑Key** для разных интеграций и настраивайте для каждого минимально необходимые доступы, чтобы ограничить возможный ущерб при утечке - Для приема уведомлений проверяйте, что запросы приходят только с доверенных IP-адресов Яндекса. [Список доверенных IP-адресов](https://yandex.ru/dev/market/partner-api/doc/ru/push-notifications/) [Как настроить Api‑Key](https://yandex.com/dev/market/partner-api/doc/ru/concepts/api-key.md) [Доступы к методам по Api‑Key](https://yandex.com/dev/market/partner-api/doc/ru/concepts/access.md) ### Обеспечьте безопасное хранение и использование ключей - Храните ключи авторизации и токены в хранилищах секретов, не добавляйте их в исходный код, логи и переписки - Регулярно пересматривайте список активных ключей, удаляйте неиспользуемые и меняйте ключи при смене подрядчика или интегратора ## Лучшие практики по сценариям ### Заказы - Для получения изменившихся заказов используйте параметр времени обновления и ограниченный интервал - Используйте фильтры по времени создания, статусов и другим параметрам, чтобы получать только нужные заказы под конкретный сценарий - Используйте API‑уведомления для событий по заказам вместо частых запросов [Получение заказов](https://yandex.com/dev/market/partner-api/doc/ru/step-by-step/orders-receive.md) ### Остатки и цены - Регулярно передавайте информацию по изменившимся позициям - Передавайте только изменившиеся позиции, а не полный ассортимент - Группируйте изменения в пакетные запросы допустимого размера и избегайте большого количества небольших запросов - Синхронизируйте остатки и цены из единого источника данных, чтобы избежать расхождений между каналами продаж [Передача остатков](https://yandex.com/dev/market/partner-api/doc/ru/reference/stocks/updateStocks.md) ### Ассортимент и карточки товаров - Используйте достаточно крупную пагинацию, чтобы не выполнять тысячи коротких запросов - Планируйте расписание обновлений под бизнес‑потребность, а не чаще, чем это действительно требуется - При добавлении и изменении ассортимента обязательно проверяйте перечень ошибок **results.errors** и замечаний **results.warnings** в ответе: при наличии ошибок изменения по всем переданным товарам не будут применены ### Отчеты и аналитика - Для аналитики за большие периоды используйте асинхронные отчеты - Планируйте генерацию и скачивание отчетов по расписанию, равномерно распределяйте запросы во времени и сохраняйте результат локально до следующей регенерации - Запрашивайте только те типы отчетов и только по тем магазинам, которые действительно нужны сценариям продавца - Учитывайте, что структура и содержание отчетов могут меняться без предварительного уведомления: может появиться новая колонка или измениться название листа ### Уведомления - Подтверждайте прием уведомления быстрым ответом - Отправляйте дальнейшую обработку события в очередь и выполняйте ее асинхронно - Передавайте ошибку в ответе, если уведомление не принято [Как работать с уведомлениями](https://yandex.com/dev/market/partner-api/doc/ru/push-notifications/index.md)