contentBox API v2

Информация для разработчиков по API интеграции с сервисом.

Авторизация

Для работы по API требуется добавить магазин в contentBox и получить токен для выполнения запросов.

  • зарегистрируйтесь https://contentbox.ru/register

  • добавьте магазин

  • в настройках найдите параметр access_token

В каждом запросе необходимо указывать полученный токен в get параметре access-token или передавать токен в заголовке:

Authorization: Bearer {access_token}

Передача контента

URL фида добавляется в настройках площадки.

Яндекс.Маркет YML

Ограничения: так как в yml для некоторых сущностей нет идентификаторов (бренды, характеристики, изображения), то обратная синхронизация со стороны магазина будет затруднена. Для автоматизации процесса понадобится расширенная выгрузка.

Также в yml файле нет общего списка брендов, характеристик, они извлекаются из значений в товарах, поэтому будут ограничения при работе с характеристикам и брендами.

contentBox XML

Выгрузка товаров для работы осуществляется с помощью XML фида данных по стандарту contentBox. Для этого сделайте файл согласно приведенному примеру, рекомендуем обновлять фид 1 раз в сутки или чаще.

XSD схема: https://contentbox.ru/contentbox.xsd

Пример:

<catalog date="Year-mm-dd hh:mm">
    <categories>
        <category id="1">Каталог</category>
        <category id="2" parentId="1">Вложенная категория</category>
    </categories>
    <brands>
        <brand id="1">Производитель</brand>
    </brands>
    <attributes>
        <attribute id="1" name="Характеристика товара" unit="">
            <values>
                <value id="1" attributeId="1">Значение</value>
            </values>
        </attribute>
    </attributes>
    <productTypes>
        <productType id="1" name="Название типа товара">
            <attributes>
                <attribute id="1"/>
            </attributes>
        </productType> 
    </productTypes>
    <products>
        <product id="1">
            <url>http://domain.ru/</url>
            <name>Название товара</name>
            <categoryId>2</categoryId>
            <brandId>1</brandId>
            <!-- если присутсвует блок productTypeId, то этим значением будет перезаписано значение, указанное через сайт -->
            <productTypeId>1</productTypeId>
            <description/>
            <sku>100001</sku>
            <barcode>0123</barcode>
            <meta_title/>
            <meta_keywords/>
            <meta_description/>
            <video/>
            <images>
                <image id="1" title="">
                    http://domain.ru/image.jpg
                </image>
            </images>
            <attributeValues>
                <attributeValue attributeId="1" valueId="1"/>
            </attributeValues>
            <reviews>
                <review id="15">
                    <!-- от 0 до 5, обязательный элемент -->
                    <rating>5</rating>
                    <name>Имя автора отзыва</name>
                    <comment>Текст отзыва</comment>
                    <!-- дата публикации/создания отзыва, обязательный элемент -->
                    <publishedAt>2016-05-30T09:00:00</publishedAt>
                </review>
            </reviews>
        </product>
   </products>
</catalog>

У каждого элемента должен быть уникальный идентификатор (id, строка до 255 символов). Это может быть как первичный таблицы, так и любой другой ключ, по которому можно будет однозначно идентифицировать объект внутри магазина. Id используется на этапе импорта для поиска и сопоставления уже загруженных объектов и во время получения заданий.

Получение заданий

Задания

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

Статус выполнения заданий:

  • 1 - новый

  • 2 - в работе

  • 3 - завершен

Статус синхронизации заданий:

  • 0 - не синхронизировано

  • 1 - синхронизировано

Объекты

Товар

Описание товара содержит:

  • id - внутренний идентификатор contentBox

  • shop_id - идентификатор магазина

  • external_id - идентификатор товара в интернет-магазине

Пример:

{
    "id": 119793,
    "shop_id": 31,
    "brand_id": null,
    "external_id": "59428404",
    "url": "http://shop-58113.myinsales.ru/product/futbolka-ac-dc",
    "name": "Футболка \"AC/DC\"",
    "description": "<p>Тестовый товар для сайта интернет-магазина<br />Удалить товар можно в бэк-офисе магазина в разделе \"Товары\"</p>",
    "sku": null,
    "barcode": null,
    "meta_title": null,
    "meta_keywords": null,
    "meta_description": null,
    "video": null,
    "status": 1,
    "is_deleted": 0,
    "is_archived": 0,
    "type_id": 34,
    "created_at": "2016-11-23 00:08:31",
    "updated_at": "2017-04-22 17:59:37"
}

Типы заданий для товара:

  • 2 - характеристики

  • 3 - описание

  • 4 - видео

  • 5 - изображения

  • 7 - название

  • 8 - метатеги

  • 17 - отзыв

  • 20 - произвольный текст

Результаты выполнения задания

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

Характеристики (тип 2)

{
    "attributes": [
        {
            "attribute_id": "123", // id в системе магазина, null если это новый атрибут
            "attribute_name" => "Цвет",
            "value_id": "222", // id в системе магазина, null если это новое значение
            "value_value": "Черный"
        },
        ...
    ]
}

Описание (тип 3)

{
    "description": "Текст описания"
}

Видео (тип 4)

{
    "video": "Youtube URL"
}

Изображения (тип 5)

{
    "images" : [
        {
            "id": "123", // id в системе магазина, null если новое
            "url": "ссылка на файл с изображением"
        },
        ...
    ]
}

Название (тип 7)

{
    "name": "Название товара"
}

Метатеги (тип 8)

{
    "meta_title": "Заголовок страницы",
    "meta_keywords": "Ключевые слова",
    "meta_description": "Описание страницы"
}

Отзыв (тип 17)

{
    "name": "Имя автора",
    "rating": "Оценка от 1 до 5",
    "comment": "Текст отзыва"
}

Произвольный текст (тип 20)

{
    "text": "Текст", // написанный текст
    "images" : [ // подобранные изображения
        {
            "url": "абсолютный url к файлу изображения"
        },
        ...
    ]
}

Работа

Получение и обработка выполненных заданий.

Получить задания

GET https://contentbox.ru/api/v2/work/items?shop_id=1&status=1&sync_status=0&type=17&page=1&per-page=20
Responses200
Headers
Content-Type: application/json
Body
[
    {
        "id": 74427,
        "shop_id": 31,
        "type": 7,
        "is_completed": 1,
        "status": 3,
        "sync_status": 1,
        "created_at": "2017-04-22 17:59:36",
        "finished_at": "2017-04-22 19:52:35",
        "synchronized_at": "2017-04-22 20:55:13",
        "source": {},
        "result": {} 
    },
    ...
]

Получить задания
GET/work/items{?shop_id,status,sync_status,type,page,per-page}

Получение всех отправленных в работу заданий.

Поле source содержит информацию об объекте, для которого выполняется задание, например, о товаре. В поле result находится результат выполенения задания.

URI Parameters
HideShow
shop_id
number (optional) Example: 1

ID магазина

status
number (optional) Example: 1

Статус заданий

sync_status
number (optional) Example: 0

Статус синхронизации заданий

type
number (optional) Example: 17

Тип заданий

page
number (optional) Example: 1

Номер страницы результатов

per-page
number (optional) Default: 50 Example: 20

Количество результатов на одной странице


Установить статус синхронизации

После загрузки результата выполнения задания рекомендуется отметить его как синхронизированное.

  • value - Статус синхронизации. 0 - не синхронизировано, 1 - синхронизировано
PUT https://contentbox.ru/api/v2/work/items/74427/set-sync-status
Requestsexample 1example 2
Headers
Content-Type: application/json
Body
{
  "value": 1
}
Responses200
Headers
Content-Type: application/json
Body
{
  "message": "Статус синхронизации установлен"
}
Headers
Content-Type: application/x-www-form-urlencoded
Body
value=1
Responses200
Headers
Content-Type: application/json
Body
{
  "message": "Статус синхронизации установлен"
}

Установить статус синхронизации
PUT/work/items/{item_id}/set-sync-status

URI Parameters
HideShow
item_id
number (required) Example: 74427

Id задания


Сценарии использования

Синхронизация выполненных работ

  1. Периодически проверять наличие выполненных работ (status=3,sync_status=0,shop_id={id магазина})

  2. Обновлять данные в товарах согласно типу задания

  3. Отмечать задание как синхронизированное, чтобы при следующем запросе результатов его не было в списке

Примеры реализации

Пример работы с сервисом на php https://gist.github.com/partster/52930516b2b8a903fa5ba13c60a7683c.

Generated by aglio on 19 Jul 2017