Общее описание

Общие сведения

SellOut+ предоставляет API для экспорта загруженных и обработанных данных в другие информационные системы по протоколу https. API доступен по адресу https://app.sellout.plus/api/sellout/sync.

Для подключения к API требуется ключ аутентификации (токен), который предоставляется сотрудниками SellOut+ (support@sellout.plus).

API возвращает данные в одном из двух режимов:

• Полная выгрузка, т.е. все доступные данные из объекта;

• Инкрементальная выгрузка, т.е. изменившиеся (в т.ч. и удалённые) данные относительно прошлой выгрузки.

Таймаут запроса – 10 минут.

Аутентификация, параметры и пример запроса

Для аутентификации, в API нужно передать заголовок следующего вида:

Authorization: Bearer <ВАШ_ТОКЕН>

Доступные параметры приведены ниже:

• Mode — режим работы API. Следует указать режим asis.

• Table — название объекта, из которого будут получены данные.

• Take — максимальное количество строк в ответе.

  • Если параметр не передан, будет использовано значение по умолчанию = 5000000

• RowVersion — максимальное значение версии изменений (поле RowVersion) из последней выгрузки для выбранного объекта. Необязательный параметр.

• Fields — возвращаемые поля объекта. Обязательный параметр. Для перечисления нескольких полей используются символ-разделитель ,. Поле FlagDeleted возвращается только для объектов с полем RowVersion при указании хотя бы одного из параметров RowVersion или Take.

Пример подключения

Рассмотрим работу с API на примере получения данных из справочника ref.Company. Для обращений к API используем системную утилиту curl.

Запрашиваем первые 100 000 строк из объекта ref.Company:

curl -H "Authorization: Bearer <ВАШ_ТОКЕН>" "https://app.sellout.plus/api/sellout/sync?mode=asis&Table=ref.Company&Take=100000&Fields=ID,Code,Name" -o result.csv

Запрашиваем следующие 100 000 строк из объекта ref.Company, где RowVersion равен максимальному значению из прошлой выгрузки:

curl -H "Authorization: Bearer <ВАШ_ТОКЕН>" "https://app.sellout.plus/api/sellout/sync?mode=asis&Table=ref.Company&Take=100000&RowVersion=12356789&Fields=ID,Code,Name" -o result.csv

Запрос следует повторять, пока количество строк в ответе не станет меньше значения, указанного в параметре Take. Меньшее количество строк означает, что новых данных для синхронизации нет.
Через некоторое время можно повторить запрос с максимальным RowVersion из последней выгрузки, чтобы получить последние изменения в данных.

Отслеживание изменений в данных

На уровне записи в объекте поддерживается поле RowVersion.

RowVersion – это глобальный счётчик для всей системы SellOut+. Каждый раз, когда происходит изменение в данных, то счётчик увеличивается на единицу и значение счётчика записывается в поле RowVersion изменившейся записи. RowVersion присваивается не только новым или изменённым записям, но и удалённым.

Формат и структура получаемых данных

Данные представлены в виде таблицы с заголовками и разделителями между столбцами ;. Кодировка – UTF-8.

Во всех объектах есть следующие системные поля:

• ID — уникальный идентификатор записи в SellOut+.

• RowVersion — версия изменения данных.

• FlagDeleted — признак удаления записи.

Для удалённых записей хранятся только системные поля: ID, RowVersion, FlagDeleted. Идентификаторы удалённых записей хранятся в SellOut+ 14 календарных дней, после чего удаляются навсегда.

Загружаемые факты Таблицы фактов – плоские таблицы, которые хранят загруженные транзакционные данные.

Загружаемые справочники Справочники, в которые могут быть загружены данные, имеют двухуровневую структуру: запись источника и итоговая запись.

В строках таблиц справочников в API выгружаются загруженные записи источника и итоговые записи. Записи источника ссылаются на итоговые записи через поле ID_mapping_MDT (Parent-child). Итоговые записи всегда имеют ID_mapping_DataSource/Code равный MDT.

Рекомендации по использованию API

1. Всегда использовать параметр Take в запросах к API.

2. Сначала выгружать объекты с фактами, а затем справочники.

3. Настроить синхронизацию в нерабочее время, например в промежутке с 03:00 до 05:00 (МСК).

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

Коды ошибок

{
   "status": 400,
   "status_description": "BadRequest",
   "error_message": "Mode \"asiz\" is not supported"
}

{
   "status": 400,
   "status_description": "BadRequest",
   "error_message": "Missing required parameter \"Fields\""
}

{
   "status": 400,
   "status_description": "BadRequest",
   "error_message": "\"Take\" parameter can't be more than 5000000"
}