Синхронизация каталога со своего сайта

Ключ позиции

Площадка отличает ваши позиции по артикулу — тому, что уже есть в вашей системе. Первая передача артикула заводит объявление, повторная его обновляет. Второго идентификатора вести не нужно.

Пакет

Позиции передаются пакетом на POST /rest/v1/advertisement/seller/ads/sync. Каждый запрос несёт заголовок Idempotency-Key — любое уникальное значение прогона: повтор прерванного запроса с тем же ключом вернёт прежний ответ и не задвоит объявления. Пока прежняя передача с этим ключом ещё выполняется, ответом будет 409 с признаком IDEMPOTENCY_REQUEST_IN_FLIGHT и заголовком Retry-After — подождите названный срок и повторите тем же ключом. Оборвавшаяся передача ключ не запирает: по истечении этого срока повтор берёт ключ на себя. Потолок числа позиций пакета и адресов изображений позиции назван в справочнике операций, пакет сверх него отклоняется целиком кодом SELLER_SYNC_BATCH_TOO_LARGE либо SELLER_SYNC_IMAGES_TOO_MANY. Изображения площадка забирает по вашим ссылкам, поэтому обработка пакета занимает секунды на позицию: держите таймаут клиента в несколько минут.

{
  "publish": true,
  "items": [
    {
      "sku": "KR-5T-12",
      "title": "Кран мостовой опорный 5 т",
      "description": "Пролёт 12 м, высота подъёма 8 м",
      "categoryId": "0192f0c0-0000-7000-8000-000000000001",
      "offerType": "PRODUCT",
      "price": 1850000,
      "currency": "RUB",
      "quantity": 3,
      "attributes": { "loadCapacity": "5", "span": "12" },
      "imageUrls": ["https://example.org/img/kr-5t-12.jpg", "https://example.org/img/kr-5t-12-side.jpg"],
      "secondImageUrl": "https://example.org/img/kr-5t-12-side.jpg"
    }
  ]
}

Изображения площадка забирает сама по указанным адресам; повторная передача той же ссылки картинку не перезаливает. Фото, загруженные ключом в галерею MAIN, позиция называет идентификаторами imageFileIds — они идут перед адресами imageUrls. Первое изображение — обложка карточки, второе фото карточки в выдаче — secondImageFileId либо secondImageUrl: одно из изображений позиции, кроме первого, только одним из двух полей. Позиция без второго фото прежнюю отметку не меняет. Признак publish отправляет заведённые и обновлённые позиции на публикацию. Поле model3dUrl даёт объявлению модель для просмотрщика в формате GLB: модель одна, другой адрес её заменяет.

Цифровая выдача

В категории с оплатой на платформе позиция несёт варианты: имя, цену и файлы выдачи — адресами fileUrls либо идентификаторами fileIds уже загруженных файлов. Файл загружается двумя шагами — POST /rest/v1/file/seller/upload/initiate и POST /rest/v1/file/seller/upload/complete — под разрешением загрузки файлов; инициация называет галерею (gallery) и категорию позиции (categoryId), место хранения выбирает площадка. Категорию, в которой окажется позиция, отдаёт POST /rest/v1/advertisement/seller/ads/sync/categories — тело то же, что у пакета, ответ построчный: sku и categoryId либо отказ error, объявления не заводятся; позиция, уже известная площадке, остаётся в своей категории. Вариант с признаком includes3dModel требует у позиции model3dUrl, иначе публикация отклоняется кодом VARIANT_REQUIRES_3D_MODEL.

Ответ

Ответ построчный в порядке запроса: sku, advertisementId и publicNumber объявления, признак created либо причина отказа error. Отказ одной позиции не отменяет остальные — разберите results и повторите только отклонённые.

Снятие с продажи

Идентификатор объявления по своему артикулу возвращает GET /rest/v1/advertisement/seller/ads?sku={артикул}, снятие идёт запросом DELETE /rest/v1/advertisement/seller/ads/{id} — объявление уходит в архив.

Категории и характеристики

Идентификатор категории берётся из дерева категорий, ключи характеристик и допустимые значения — из состава атрибутов категории:

GET /rest/v1/catalog/public/categories
GET /rest/v1/catalog/public/categories/{id}/attributes
GET /rest/v1/catalog/public/categories/{id}/attributes/{attributeKey}/values

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

Категории своего магазина

Вместо categoryId позиция передаёт категорию своего магазина полем shopCategoryPath — названия уровней от корня. Позиция встаёт в категорию площадки, сопоставленную этой категории магазина в разделе «Разработчикам», — то же сопоставление действует для файлов и фидов. Новая категория магазина появляется в перечне сопоставления, позиция несопоставленной категории отклоняется кодом VALIDATION_ERROR с путём категории в errorDetails.category; после сопоставления повторите позицию.