Яндекс Маркет PHP API - Полное руководство для разработчиков

Чтобы начать работу с Яндекс Маркет PHP API, установите официальный SDK через Composer. Выполните команду composer require yandex/market в терминале. Это подключит все необходимые зависимости и упростит интеграцию. Убедитесь, что у вас настроена среда PHP версии 7.4 или выше, так как SDK поддерживает только современные версии языка.

После установки SDK настройте авторизацию через OAuth-токен. Получите токен в личном кабинете разработчика Яндекс Маркета. Используйте метод setToken() для передачи токена в клиент API. Например: $client->setToken(‘ваш_токен’);. Это обеспечит доступ к данным вашего магазина и позволит выполнять запросы к API.

Для получения информации о заказах вызовите метод getOrders(). Он возвращает список заказов с деталями, такими как статус, стоимость и данные покупателя. Если нужно обновить статус заказа, используйте updateOrderStatus(), передав ID заказа и новый статус. Это помогает синхронизировать данные между вашей системой и Яндекс Маркетом.

Работа с товарами требует вызова методов getOffers() и updateOffer(). Первый возвращает список товаров, а второй позволяет обновить их параметры, например цену или наличие. Для массового обновления используйте updateOffers(), передавая массив данных. Это ускоряет синхронизацию и снижает нагрузку на сервер.

Обрабатывайте ошибки с помощью исключений, которые выбрасывает SDK. Например, если токен недействителен, метод setToken() вызовет исключение InvalidTokenException. Ловите такие исключения и логируйте их для упрощения отладки. Это поможет быстро находить и устранять проблемы в работе с API.

Настройка окружения для работы с Яндекс Маркет API

Установите PHP версии 7.4 или выше, чтобы обеспечить совместимость с библиотеками и функциями, необходимыми для работы с API. Проверьте текущую версию PHP командой php -v в терминале. Если версия ниже, обновите её через пакетный менеджер вашей операционной системы.

Создайте новый проект в удобной для вас среде разработки, например, в PhpStorm или Visual Studio Code. Убедитесь, что у вас установлен Composer, так как он упрощает управление зависимостями. Выполните команду composer init в корне проекта, чтобы создать файл composer.json.

Добавьте библиотеку Guzzle HTTP Client для работы с HTTP-запросами. Введите команду composer require guzzlehttp/guzzle. Guzzle упрощает отправку запросов и обработку ответов, что особенно полезно при взаимодействии с API.

Получите OAuth-токен для доступа к Яндекс Маркет API. Перейдите в кабинет разработчика Яндекс, создайте новое приложение и скопируйте идентификатор клиента (Client ID) и секрет (Client Secret). Используйте эти данные для получения токена через OAuth-авторизацию.

Создайте файл .env в корне проекта для хранения чувствительных данных, таких как Client ID, Client Secret и токен. Используйте библиотеку vlucas/phpdotenv для загрузки переменных окружения. Установите её командой composer require vlucas/phpdotenv.

Настройте базовый URL для запросов к API. Например, для работы с API магазинов используйте https://api.partner.market.yandex.ru. Создайте отдельный класс или файл для хранения конфигураций, чтобы упростить управление параметрами запросов.

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

Выбор и установка необходимых инструментов

Для работы с API Яндекс Маркета на PHP установите PHP версии 7.4 или выше. Это обеспечит поддержку всех необходимых функций и библиотек. Убедитесь, что на вашем сервере или локальной машине установлен Composer – менеджер зависимостей для PHP.

Установите Composer, выполнив команду в терминале:

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"

Создайте новый проект или перейдите в существующий и выполните команду:
```
composer init
```
Это создаст файл composer.json, где вы сможете указать зависимости.

Добавьте библиотеку Guzzle для работы с HTTP-запросами. Она упростит взаимодействие с API. Установите её через Composer:

composer require guzzlehttp/guzzle

Для удобства работы с JSON-ответами установите библиотеку для их обработки, например, symfony/serializer:

composer require symfony/serializer

Если вы планируете использовать OAuth-авторизацию, добавьте библиотеку league/oauth2-client:

composer require league/oauth2-client

Проверьте настройки PHP на сервере. Убедитесь, что включены расширения curl и json. Для этого выполните команду:

php -m

Если расширения отсутствуют, установите их. Например, для Ubuntu используйте команду:

sudo apt-get install php-curl php-json

Теперь вы готовы к работе с API Яндекс Маркета. Настройте среду разработки, добавьте необходимые зависимости и приступайте к написанию кода.

Определение ключевых параметров для подключения к API

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

Убедитесь, что ваш токен имеет доступ к необходимым правам (scopes). Например, для работы с заказами потребуется право market:order, а для управления товарами – market:partner. Проверьте список доступных прав в документации API.

Для выполнения запросов укажите идентификатор магазина (campaignId). Его можно найти в личном кабинете партнера Яндекс Маркета. Этот параметр обязателен для большинства методов, связанных с управлением магазином.

Настройте базовый URL для API. Для работы с основными функциями используйте https://api.partner.market.yandex.ru. Для тестирования можно подключиться к песочнице по адресу https://api.partner.market.yandex.ru/v2.

Проверьте корректность заголовков запроса. Убедитесь, что передаете Authorization: OAuth ваш_токен и Content-Type: application/json. Это обеспечит успешную авторизацию и обработку данных.

Используйте лимиты запросов, указанные в документации. Например, для метода получения списка заказов допустимо до 100 запросов в минуту. Следите за лимитами, чтобы избежать блокировки.

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

Создание тестового проекта на PHP

Создайте новую директорию для проекта и инициализируйте её с помощью Composer. В терминале выполните команду composer init, чтобы создать файл composer.json. Укажите необходимые параметры, такие как имя проекта и версия PHP.

Установите библиотеку для работы с API Яндекс Маркета. Добавьте её в зависимости, выполнив команду composer require vendor/package-name. Это позволит вам легко подключать API в коде.

Создайте файл index.php в корне проекта. Подключите автозагрузку Composer, добавив строку require 'vendor/autoload.php';. Это обеспечит автоматическую загрузку всех необходимых классов.

Настройте подключение к API. Используйте ключ доступа, который можно получить в личном кабинете Яндекс Маркета. Создайте экземпляр клиента API, передав ключ в конструктор. Например: $client = new YandexMarketApiClient('your-api-key');.

Проверьте работоспособность подключения, выполнив простой запрос. Например, запросите список категорий с помощью метода $client->getCategories(). Выведите результат на экран, чтобы убедиться, что всё работает корректно.

Добавьте обработку ошибок. Оберните запросы в блоки try-catch, чтобы корректно обрабатывать возможные исключения. Это поможет быстрее находить и исправлять проблемы.

Не забудьте добавить проект в систему контроля версий, например Git. Инициализируйте репозиторий командой git init и создайте файл .gitignore, чтобы исключить папку vendor и другие временные файлы.

Работа с основными функциями Яндекс Маркет API

Для начала работы с API Яндекс Маркет, получите токен доступа через OAuth 2.0. Используйте метод GET /oauth/token, передав client_id, client_secret и grant_type. Токен потребуется для всех последующих запросов.

Получите информацию о товарах с помощью метода GET /v1/model. Укажите параметры, такие как region_id, category_id или query, чтобы фильтровать результаты. Ответ вернет массив данных с характеристиками товаров, включая цены, рейтинги и доступность.

Для работы с заказами используйте метод GET /v1/orders. Он позволяет получить список заказов, их статусы и детали. Чтобы обновить статус заказа, вызовите метод PUT /v1/orders/{orderId}, передав новый статус в теле запроса.

Для получения аналитики по продажам обратитесь к методу GET /v1/statistics. Укажите период и параметры, такие как region_id или category_id, чтобы получить данные о спросе, просмотрах и конверсиях.

Используйте метод POST /v1/feedback для отправки отзывов о товарах. Передайте в теле запроса текст отзыва, оценку и идентификатор товара. Это поможет улучшить рейтинг ваших товаров на платформе.

Для управления акциями и скидками вызовите метод POST /v1/campaigns/{campaignId}/offers. Укажите идентификаторы товаров и параметры акции, такие как скидка или срок действия. Это повысит видимость ваших товаров в поиске.

Обрабатывайте ошибки, проверяя код ответа и тело запроса. Например, код 400 указывает на неверные параметры, а 403 – на отсутствие прав доступа. Используйте логирование для отслеживания проблем и их устранения.

Получение списка товаров и фильтрация данных

Для получения списка товаров через Яндекс Маркет API используйте метод GET /models. Этот метод позволяет запрашивать данные о товарах с учётом заданных параметров. Например, можно указать категорию, ценовой диапазон или бренд.

Чтобы отфильтровать результаты, добавьте параметры в запрос. Например, для поиска товаров в категории «Смартфоны» используйте category_id, а для ограничения по цене – price_min и price_max. Это поможет сузить выборку до нужных позиций.

Если требуется сортировка, добавьте параметр sort. Например, sort=price отсортирует товары по возрастанию цены, а sort=-price – по убыванию. Для пагинации используйте page и page_size, чтобы управлять количеством элементов на странице.

Для более точного поиска применяйте параметр query, который позволяет искать товары по названию или ключевым словам. Например, запрос с query=iPhone 13 вернёт только соответствующие модели.

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

Добавление и обновление товаров через API

Для добавления товаров в каталог Яндекса используйте метод POST /campaigns/{campaignId}/offer-mapping-entries/update. В теле запроса передайте массив объектов с данными о товарах, включая offerId, name, category, price и другие параметры. Убедитесь, что все обязательные поля заполнены корректно, чтобы избежать ошибок валидации.

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

Для массового обновления или добавления товаров используйте асинхронный режим. Отправьте запрос с параметром processingMode: "ASYNC", чтобы избежать задержек при обработке большого объема данных. После отправки запроса вы получите идентификатор задачи, по которому можно отслеживать статус выполнения.

Проверяйте статус задачи через метод GET /campaigns/{campaignId}/offer-mapping-entries/update/{taskId}. Если задача завершена успешно, товары будут добавлены или обновлены в каталоге. В случае ошибок API вернет список проблем, которые нужно исправить.

Используйте метод GET /campaigns/{campaignId}/offer-mapping-entries для получения текущего состояния товаров в каталоге. Это поможет убедиться, что данные обновлены корректно и соответствуют ожиданиям.

Для работы с изображениями товаров применяйте метод POST /campaigns/{campaignId}/offer-mapping-entries/images. Передайте массив ссылок на изображения и свяжите их с соответствующими товарами через offerId. Убедитесь, что изображения соответствуют требованиям платформы по формату и размеру.

Если нужно удалить товар из каталога, используйте метод POST /campaigns/{campaignId}/offer-mapping-entries/delete. Передайте массив offerId товаров, которые нужно убрать. После успешного выполнения запроса товары будут скрыты из каталога.

Удаление товаров и обработка исключений

Для удаления товаров через API Яндекс Маркета используйте метод DELETE /campaigns/{campaignId}/offer-mapping-entries/. В запросе укажите идентификаторы товаров, которые нужно удалить, в формате JSON. Например:


{
"offers": [
{"offerId": "12345"},
{"offerId": "67890"}
]
}

После отправки запроса проверьте статус ответа. Успешное удаление возвращает код 200 OK. Если товар не найден, API вернет ошибку 404 Not Found.

При работе с удалением учитывайте следующие рекомендации:

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

Для обработки исключений используйте try-catch блоки. Например:


try {
$response = $client->delete('/campaigns/12345/offer-mapping-entries/', $data);
} catch (Exception $e) {
error_log('Ошибка удаления товара: ' . $e->getMessage());
}

Если API возвращает ошибку 429 Too Many Requests, добавьте задержку между запросами. Например, используйте функцию sleep() с интервалом в 1-2 секунды.

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

Формирование отчетов по данным из API

Используйте метод GET /campaigns/{campaignId}/stats/main для получения данных о продажах, просмотрах и других метриках. Этот метод позволяет задать временной интервал и группировать данные по дням, неделям или месяцам. Например, чтобы получить статистику за последние 30 дней, укажите параметр interval с нужным диапазоном.

Для анализа данных по категориям товаров применяйте метод GET /campaigns/{campaignId}/stats/categories. Он возвращает информацию о продажах и просмотрах в разрезе категорий. Это поможет определить, какие категории приносят больше дохода или требуют дополнительного внимания.

Если нужно отследить эффективность отдельных товаров, используйте метод GET /campaigns/{campaignId}/stats/products. Он предоставляет данные по каждому товару, включая количество заказов, выручку и рейтинг. Это особенно полезно для выявления популярных товаров и оптимизации ассортимента.

Для автоматизации формирования отчетов создайте скрипт на PHP, который будет запрашивать данные через API и сохранять их в формате CSV или Excel. Используйте библиотеку PhpOffice/PhpSpreadsheet для работы с таблицами. Пример кода:


$client = new YandexMarketPartnerClientsCampaignClient($oauthToken);
$stats = $client->getCampaignStats($campaignId, ['interval' => 'LAST_30_DAYS']);
$spreadsheet = new PhpOfficePhpSpreadsheetSpreadsheet();
$sheet = $spreadsheet->getActiveSheet();
$sheet->fromArray($stats);
$writer = new PhpOfficePhpSpreadsheetWriterXlsx($spreadsheet);
$writer->save('report.xlsx');

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

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

Метод API	Описание
`GET /campaigns/{campaignId}/stats/main`	Основная статистика по кампании
`GET /campaigns/{campaignId}/stats/categories`	Статистика по категориям товаров
`GET /campaigns/{campaignId}/stats/products`	Статистика по отдельным товарам

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