Интеграция интернет-магазина с Яндекс.Маркет через Partner API

Представьте: у вас 15 000 товаров, цены меняются каждый час, а менеджер тратит 4 часа в день на ручное обновление в личном кабинете Яндекс.Маркета. Ошибки при ручном вводе — 5–8% позиций. После интеграции через Partner API всё автоматизируется: товары загружаются за 2 минуты, цены синхронизируются по расписанию, заказы обрабатываются без участия человека. Мы реализовали более 50 таких проектов для магазинов с оборотом от 500 тыс. до $450k–650k в месяц.

Яндекс.Маркет предоставляет Partner API — набор REST-методов для управления товарами, ценами, остатками и заказами. API поддерживает три модели работы: FBS (продавец хранит товары у себя), FBO (товары на складе Маркета) и DBS (продавец доставляет сам). В этой статье разберём технические детали интеграции: аутентификацию, загрузку товаров, обновление цен и остатков, обработку заказов через вебхуки.

Почему стоит автоматизировать работу с Яндекс.Маркетом?

Ручное управление ассортиментом на маркетплейсе — это не только долго, но и чревато ошибками. По нашим данным, автоматизация через API сокращает время на обновление каталога в 10–15 раз. Например, загрузка 100 товаров вручную занимает 30 минут, а через API — 2 минуты. Ошибки при ручном вводе встречаются в 5–8% случаев (неверная цена, неправильный остаток), при автоматической синхронизации — менее 0.1%. Кроме того, API позволяет выгружать заказы напрямую в вашу учётную систему, исключая двойной ввод данных.

Какие данные синхронизируются через API?

Partner API предоставляет методы для работы с ключевыми сущностями:

• Товары: создание, обновление, удаление; обязательные поля — offerId, name, price, count. Можно загружать до 1000 товаров за один запрос.
• Цены и остатки: регулярное обновление (например, каждый час) через POST /campaigns/{id}/offer-prices/updates и PUT /campaigns/{id}/offers/stocks.
• Заказы: получение новых заказов, изменение статусов, отмена. Вебхуки уведомляют об изменениях в реальном времени.

Важно учитывать лимиты API: не более 5000 запросов в день на кампанию, поэтому рекомендуется использовать пакетную обработку.

Аутентификация

Partner API использует OAuth2 токены. Авторизация через Яндекс OAuth:

class YandexMarketClient {
    private string $accessToken;
    private int $campaignId;
    private int $businessId;

    public function request(string $method, string $path, array $data = []): array {
        return Http::withHeaders([
            'Authorization' => "OAuth oauth_token={$this->accessToken}",
            'Content-Type' => 'application/json',
        ])->{strtolower($method)}(
            "https://api.partner.market.yandex.ru{$path}",
            $data
        )->json();
    }
}

Загрузка/обновление товаров

public function updateOffers(array $products): void {
    $offers = array_map(fn($product) => [
        'offerId' => $product['sku'],
        'name' => $product['name'],
        'category' => $product['category_name'],
        'pictures' => $product['images'],
        'vendor' => $product['brand'],
        'description' => $product['description'],
        'price' => ['value' => $product['price'], 'currencyId' => 'RUR'],
        'count' => $product['stock'],
        'barcodes' => [$product['barcode']],
    ], $products);

    $this->request('PUT', "/businesses/{$this->businessId}/offer-mappings", [
        'offerMappings' => array_map(fn($o) => ['offer' => $o], $offers)
    ]);
}

Цены и остатки

// Обновление цен
public function updatePrices(array $items): void
{
    $offers = array_map(fn($item) => [
        'id' => $item['sku'],
        'price' => [
            'value' => $item['price'],
            'currencyId' => 'RUR',
            'vat' => 'VAT_20',
        ],
    ], $items);

    $this->request('POST', "/campaigns/{$this->campaignId}/offer-prices/updates", [
        'offers' => $offers
    ]);
}

// Обновление остатков FBS
public function updateStocks(array $items, int $warehouseId): void
{
    $skus = array_map(fn($item) => [
        'sku' => $item['sku'],
        'items' => [
            ['count' => $item['stock'], 'type' => 'FIT']
        ],
    ], $items);

    $this->request('PUT', "/campaigns/{$this->campaignId}/offers/stocks", [
        'skus' => $skus,
        'warehouseId' => $warehouseId
    ]);
}

Обработка заказов

public function getNewOrders(): array
{
    $resp = $this->request('GET', "/campaigns/{$this->campaignId}/orders", ['status' => 'PROCESSING', 'substatus' => 'STARTED', 'pageSize' => 50] );
    return $resp['orders'] ?? [];
}

public function acceptOrder(int $orderId): void
{
    $this->request('PUT', "/campaigns/{$this->campaignId}/orders/{$orderId}/status", ['order' => ['status' => 'PROCESSING', 'substatus' => 'READY_TO_SHIP']] );
}

Push-уведомления о заказах

Яндекс.Маркет поддерживает push-уведомления через настройки в кабинете продавца:

Route::post('/webhooks/yandex-market', function (Request $request) {
    $events = $request->input('data');
    foreach ($events as $event) {
        match($event['type']) {
            'ORDER_STATUS_CHANGED' => ProcessYandexOrderStatus::dispatch($event['orderId']),
            default => null,
        };
    }
    return response()->json(['status' => 'ok']);
});

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

Интеграция проходит в несколько этапов:

1. Аналитика: изучаем текущую систему учёта, ассортимент, бизнес-процессы.
2. Проектирование: выбираем модель (FBS/FBO/DBS), проектируем архитектуру обмена.
3. Реализация: пишем код для синхронизации товаров, цен, остатков, заказов; настраиваем вебхуки.
4. Тестирование: проверяем на песочнице Маркета, затем на боевом контуре.
5. Деплой и обучение: разворачиваем решение, проводим вебинар для сотрудников, передаём документацию.

Что входит в работу под ключ?

Сравнение ручного и автоматического управления

Ручное обновление товаров на Маркете (через личный кабинет) занимает в среднем 30 минут на 100 позиций. Автоматическая интеграция через API — 1–3 минуты на весь каталог. Ошибки при ручном вводе встречаются в 5–8% случаев, а при автоматической синхронизации — менее 0.1%.

Типичные ошибки при интеграции

На основе нашего опыта, частые проблемы:

• Превышение лимитов API: при попытке загрузить более 1000 товаров за раз API возвращает 429. Решение — разбивать на пакеты по 1000.
• Неверный формат данных: например, неправильный формат штрихкода или отсутствие обязательного поля. Всегда проверяйте структуру запроса.
• Проблемы с OAuth-токеном: токен может истечь (срок жизни — 1 год), нужно предусмотреть его обновление.
• Конфликт версий: при изменении API со стороны Яндекса — следите за обновлениями в документации Partner API.

Сроки

Интеграция с Яндекс.Маркет Partner API: 12–16 рабочих дней. Свяжитесь с нами, чтобы оценить ваш проект — мы предложим оптимальное решение и точные сроки. Закажите интеграцию, и ваши товары будут всегда актуальны на Маркете.