← На главную

При интеграции учётных систем с маркетплейсом Яндекс Маркет разработчики нередко сталкиваются с ситуацией, когда типовые запросы к API успешно отрабатывают на большинстве магазинов, но на одном из подключенных кабинетов вызывают ошибку с кодом состояния 403 Forbidden. Чаще всего это происходит при обращении к методу получения статистики по заказам POST v2/campaigns/{campaignId}/stats/orders.

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

Причина 1. Ограничение прав доступа (Scopes) API-ключа

Ранее авторизация в партнерском API Яндекс Маркета строилась на базе протокола OAuth 2.0 и токенов авторизации. В настоящее время основным и рекомендуемым методом аутентификации стал API-key, который передается в заголовке Api-Key. Однако, в отличие от простых статических ключей, в кабинете продавца Яндекс Маркета реализована система гранулярных прав доступа (областей видимости или scopes).

Проанализируем механизм создания ключа: при генерации API-ключа администратор кабинета явно выбирает уровень разрешений. Если ключ был выпущен исключительно для работы с каталогом (например, изменение цен или остатков), попытка вызвать метод статистики заказов немедленно вернет ошибку 403.

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

1. Обработка заказов и учёт товаров — системные идентификаторы inventory-and-order-processing или inventory-and-order-processing:read-only (для режима только чтение).
2. Полное управление кабинетом / Просмотр всех данных — системные идентификаторы all-methods или all-methods:read-only.

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

Причина 2. Несоответствие campaignId и привязки ключа

Выясним частую техническую ошибку, связанную с подстановкой параметров в URL запроса. В пути метода v2/campaigns/{campaignId}/stats/orders используется числовой идентификатор кампании. Ошибка 403 при корректном ключе может возникать в следующих случаях:

1. Путаница между идентификаторами: вместо технического campaignId в запрос передается номер бизнеса (businessId), номер клиента (clientId) или номер магазина из адресной строки браузера. Идентификатор кампании формируется платформой отдельно. Точный список идентификаторов магазинов рекомендуется получать через служебный метод GET v2/campaigns.
2. Ключ выпущен для другого магазина: если API-ключ привязан к конкретному магазину внутри кабинета, а в URL передается идентификатор другого магазина (пусть даже принадлежащего тому же юрлицу), сервер воспримет это как попытку несанкционированного доступа к чужому ресурсу и вернет код 403.

Причина 3. Роль учетной записи пользователя, создавшего ключ

Рассмотрим зависимость ключа от прав создавшего его сотрудника. Права API-ключа не могут превышать полномочия той учетной записи на Яндексе, под которой он был сгенерирован в личном кабинете. Сервер возвращает 403 в следующих ситуациях:

1. Учетная запись сотрудника имеет в данном конкретном магазине ограниченную роль (например, бухгалтерский или логистический доступ, где закрыт просмотр детализации заказов).
2. Пользователь, сгенерировавший ключ, был удален из состава сотрудников магазина владельцем кабинета либо его учетная запись была деактивирована. В этом случае все связанные с ним API-ключи автоматически теряют доступ.

Причина 4. Превышение лимитов по периоду дат

Посмотрим на параметры тела самого запроса. Метод POST v2/campaigns/{campaignId}/stats/orders накладывает строгие ограничения на фильтрацию по времени:

1. Максимальный интервал между датами fromDate и toDate в рамках одного запроса не может превышать 30 дней.
2. По умолчанию (при отсутствии расширенной подписки продавца) запрещено запрашивать исторические данные по заказам старше 90 дней от текущей даты.

Способы точной диагностики ошибки

Разберем по шагам, как локализовать причину запрета, не имея прямого доступа к настройкам кабинета:

1. Анализ тела ответа: при возникновении HTTP-ошибки 403 Яндекс Маркет всегда возвращает подробное JSON-сообщение. В структуре errors поле message содержит текстовое пояснение, а поле code — конкретный код системной ошибки (например, прямое указание на отсутствие требуемого скоупа или доступ к чужому ресурсу). Не отбрасывайте тело ответа при получении ошибки.
2. Журнал запросов в личном кабинете: администратор кабинета может перейти в раздел интеграции API и просмотреть журнал входящих вызовов. В нем фиксируются все заблокированные обращения с точным указанием причины отклонения системой безопасности.

Альтернативные методы для получения данных по заказам

Если для бизнес-процесса необходима выгрузка информации о заказах, рассмотрим другие штатные методы API Яндекс Маркета, которые могут быть удобнее:

1. Заказы на уровне бизнеса: метод POST v1/businesses/{businessId}/orders позволяет получать список заказов сразу по всем связанным магазинам компании. Важным преимуществом этого метода является отсутствие 40-минутной задержки обновления данных, характерной для метода аналитической статистики stats/orders.
2. Генерация единого отчета по заказам: метод POST v2/reports/united-orders/generate запускает фоновую генерацию полного отчета по заказам с расширенными финансовыми и логистическими полями.