© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
Документация RESTful APIDobraTrade - версия v1.1.0
Руководство программиста
ООО "ДОБРА"
г. Минск, ООО "Добра", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
Документация RESTful API DobraTrade - версия v1.1.0
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
Никакая часть данного руководства не может быть воспроизведена третьими лицами вкаком-либо виде без письменного разрешения ООО "Добра".ООО "Добра" не намерена нести ответственность перед другими лицами в случаепричинения им прямых, косвенных убытков, упущеной выгоды и других форс-мажорныхобстоятельств, возникших прямо или косвенно вследствие ненадлежащегоиспользования данного руководства.Другие лица, приняв к сведению изложенную в данном руководстве информацию,обязуются использовать ее исключительно в целях, указанных в данном руководстве.
Документация RESTful API DobraTrade - версия v1.1.04
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
Оглавление
Раздел I Основные положения 8
................................................................................................................................... 91 Общая характеристика
................................................................................................................................... 92 Подключение, установка соединения
................................................................................................................................... 113 Роли доступа
................................................................................................................................... 114 Отправка запросов
................................................................................................................................... 125 Статусы операций и обработка ошибок
................................................................................................................................... 146 Форматно-логический контроль
................................................................................................................................... 147 Служебные поля JSON-элементов
Раздел II Описание информационной схемы 16
................................................................................................................................... 171 Справочники
.......................................................................................................................................................... 17Справочник Товарные группы
......................................................................................................................................................... 17Назначение
......................................................................................................................................................... 17Структура JSON-элемента
.......................................................................................................................................................... 18Справочник Единицы измерений
......................................................................................................................................................... 18Назначение
......................................................................................................................................................... 18Структура JSON-элемента
.......................................................................................................................................................... 18Справочник Валюты
......................................................................................................................................................... 18Назначение
......................................................................................................................................................... 18Структура JSON-элемента
.......................................................................................................................................................... 18Справочник Страны
......................................................................................................................................................... 18Назначение
......................................................................................................................................................... 19Структура JSON-элемента
.......................................................................................................................................................... 19Справочник Регионы
......................................................................................................................................................... 19Назначение
......................................................................................................................................................... 19Структура JSON-элемента
.......................................................................................................................................................... 19Справочник Категории торговых объектов
......................................................................................................................................................... 19Назначение
......................................................................................................................................................... 19Структура JSON-элемента
................................................................................................................................... 202 Информационная группа Торговые объекты
.......................................................................................................................................................... 20Массив Пользователи
......................................................................................................................................................... 20Назначение
......................................................................................................................................................... 20Структура JSON-элемента
......................................................................................................................................................... 20Форматно-логический контроль
.......................................................................................................................................................... 20Массив Профили торговых объектов
......................................................................................................................................................... 21Назначение
......................................................................................................................................................... 21Структура JSON-элемента
......................................................................................................................................................... 21Форматно-логический контроль
.......................................................................................................................................................... 21Массив Бизнес-профили
......................................................................................................................................................... 21Назначение
......................................................................................................................................................... 21Структура JSON-элемента
......................................................................................................................................................... 22Форматно-логический контроль
................................................................................................................................... 223 Информационная группа Товары
5Оглавление
5
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
.......................................................................................................................................................... 22Массив Продукты/Товары
......................................................................................................................................................... 22Назначение
......................................................................................................................................................... 22Структура JSON-элемента
......................................................................................................................................................... 23Форматно-логический контроль
.......................................................................................................................................................... 24Массив Описания Продуктов/Товаров
......................................................................................................................................................... 24Назначение
......................................................................................................................................................... 24Структура JSON-элемента
......................................................................................................................................................... 24Форматно-логический контроль
.......................................................................................................................................................... 24Массив Изображения Продуктов/Товаров
......................................................................................................................................................... 24Назначение
......................................................................................................................................................... 24Структура JSON-элемента
......................................................................................................................................................... 25Форматно-логический контроль
Раздел III Работа со справочниками в API 26
................................................................................................................................... 271 Справочник Товарные группы
.......................................................................................................................................................... 27Получить коллекцию элементов
.......................................................................................................................................................... 27Получить элемент коллекции
................................................................................................................................... 282 Справочник Единицы измерений
.......................................................................................................................................................... 28Получить коллекцию элементов
.......................................................................................................................................................... 28Получить элемент коллекции
................................................................................................................................... 293 Справочник Валюты
.......................................................................................................................................................... 29Получить коллекцию элементов
.......................................................................................................................................................... 29Получить элемент коллекции
................................................................................................................................... 294 Справочник Страны
.......................................................................................................................................................... 29Получить коллекцию элементов
.......................................................................................................................................................... 31Получить элемент коллекции
................................................................................................................................... 315 Справочник Регионы
.......................................................................................................................................................... 31Получить коллекцию элементов
.......................................................................................................................................................... 32Получить элемент коллекции
................................................................................................................................... 326 Справочник Категории торговых объектов
.......................................................................................................................................................... 33Получить коллекцию элементов
.......................................................................................................................................................... 33Получить элемент коллекции
Раздел IV Использование API в роли Subscriber(Подписчик) 34
................................................................................................................................... 351 Информационная группа Торговые объекты
.......................................................................................................................................................... 35Работа с Профилями
......................................................................................................................................................... 35Получить коллекцию элементов
......................................................................................................................................................... 36Получить элемент коллекции
.......................................................................................................................................................... 37Работа с Бизнес-Профилями
......................................................................................................................................................... 37Получить коллекцию элементов
......................................................................................................................................................... 38Получить элемент коллекции
................................................................................................................................... 382 Информационная группа Товары
.......................................................................................................................................................... 38Работа с Продуктами/Описаниями/Изображениями
......................................................................................................................................................... 39Получить коллекцию элементов
......................................................................................................................................................... 43Получить элемент коллекции
Раздел V Использование API в роли Publisher(Издатель) 45
Документация RESTful API DobraTrade - версия v1.1.06
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
................................................................................................................................... 461 Информационная группа Торговые объекты
.......................................................................................................................................................... 46Работа с Профилями
......................................................................................................................................................... 46Получить коллекцию элементов
......................................................................................................................................................... 47Получить элемент коллекции
......................................................................................................................................................... 48Создать элемент
......................................................................................................................................................... 49Изменить элемент
......................................................................................................................................................... 49Удалить элемент
......................................................................................................................................................... 49Получить коллекцию Продуктов/Товаров профиля
......................................................................................................................................................... 50Получить Продукт/Товар профиля по атрибуту article_code или sku
......................................................................................................................................................... 50Получить Профили по атрибуту email
.......................................................................................................................................................... 51Работа с Бизнес-Профилями
......................................................................................................................................................... 51Получить коллекцию элементов
......................................................................................................................................................... 52Получить элемент коллекции
......................................................................................................................................................... 53Создать элемент
......................................................................................................................................................... 53Изменить элемент
......................................................................................................................................................... 53Удалить элемент
................................................................................................................................... 542 Информационная группа Товары
.......................................................................................................................................................... 54Работа с Продуктами/Товарами
......................................................................................................................................................... 54Получить коллекцию элементов
......................................................................................................................................................... 57Получить элемент коллекции
......................................................................................................................................................... 58Создать элемент
......................................................................................................................................................... 59Изменить элемент
......................................................................................................................................................... 59Удалить элемент
.......................................................................................................................................................... 59Работа с Описаниями Продуктов/Товаров
......................................................................................................................................................... 59Получить коллекцию элементов
......................................................................................................................................................... 61Получить элемент коллекции
......................................................................................................................................................... 62Создать элемент
......................................................................................................................................................... 62Изменить элемент
......................................................................................................................................................... 63Удалить элемент
.......................................................................................................................................................... 63Работа с Изображениями Продуктов/Товаров
......................................................................................................................................................... 63Получить коллекцию элементов
......................................................................................................................................................... 63Получить элемент коллекции
......................................................................................................................................................... 64Создать элемент
......................................................................................................................................................... 64Изменить элемент
......................................................................................................................................................... 64Удалить элемент
Раздел VI История изменений 65
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
Раздел
I
Последние изменения: 02.04.2019
Основные положения
Основные положения 9
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
РАЗДЕЛ 1: Основные положения
Данное руководство описывает прикладной программный интерфейс (далее - API), спомощью которого сторонние разработчики могут создавать собственные приложения длявзаимодействия с информационной системой DobraTrade (далее - API-сервер). Для решенияподобных задач необходимо использовать инструментальные средства разработки, в которыхимеются библиотеки для работы с HTTP-протоколом и парсинга JSON-структур в качестве откликовот API-сервера. Разрабатываемое приложение будет выступать в роли клиента (далее - API-клиент)по отношению к API-серверу информационной системы DobraTrade.
§1.1 - Общая характеристика
Рассматриваемый API обладает рядом функциональных возможностей, наиболее важные изкоторых следующие:
· Аутентификация на основе учетной записи с подтверждением токеном доступа. Впроцессе аутентификации каждому аккаунту выдается уникальный сеансовый токендоступа, которым он должен подтверждать свою подлинность при выполнении API-операций. Длительность сеанса, в течении которого токен имеет действие, составляет 24часа. Подробнее см. раздел Подключение, установка соединения ;
· Многоролевая авторизация. API поддерживает несколько функциональных ролей"Подписчик" и "Издатель", каждая из которых обладает собственным наборомполномочий при обращении к методам API-сервера. Подробнее о ролях и доступныхдействиях см. разделы Использование API в роли Subscriber (Подписчик) иИспользование API в роли Publisher (Издатель) ;
· Версионность. При обращении к методам API имеется возможность указать версиюметода, которая необходима в данный момент API-клиенту. Если в указанной версииотсутствует реализация данного метода, то он будет запрошен в ниже идущей версии дотех пор, пока не будет найдена его реализация или не будет достигнута версия, индекскоторой задан в API по умолчанию - v1. Подробнее см. раздел Режимы доступа, отправказапросов ;
· REST-архитектура, ориентированная на реляционные CRUD-операции с данными (Create-Read-Update-Delete);
· Отклик в формате JSON. Все методы, если в них предусмотрена передача данных,формируют отклик в виде JSON-элемента или массива JSON-элементов. Для отдельныхметодов предусмотрена более сложная сериализация, при которой определенный элементявляется вложенным массивом JSON-элементов;
· Постраничная загрузка данных. Для случая, когда предполагается получение с API-сервера значительных объемов данных, имеется возможность получать их небольшимипорциями в виде страниц под номерами, начиная с 1. Число элементов, из которыхсостоит каждая страница, заложена в настройках API-сервера. Приложению API-клиентадля получения массива данных достаточно указать конкретный номер страницы впараметрах запроса или начать итерацию по страницам, начиная с любого номера, до техпор, пока не встретится первая страница с пустой коллекцией элементов.
· Обработка ошибок. Прикладной API содержит подсистему обработки ошибок и, в случаевозникновения таковых, формирует соответствующий код статуса и дополнительноесообщение о характере ошибки. Подробнее см. раздел Статусы операций и обработкаошибок .
§1.2 - Подключение, установка соединения
Перед началом работы с API-сервером необходимо однократно выполнить следующиепроцедуры:
· Пройти интерактивную регистрацию на сайте проекта по адресуhttp://iog.by/users/sign_up. Форма регистрации запрашивает ваш e-mail, который будетуникально обозначать вашу учетную запись в системе, а также использоваться для ряда
9
35
46
11
12
Документация RESTful API DobraTrade - версия v1.1.010
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
вспомогательных операций, таких как сброс забытого пароля и создание нового. Такжезапрашивается ваше описательное наименование как клиента системы и создаваемыйпароль с подтверждением;
· Связаться по телефону (указан на сайте) со службой технической поддержки, согласоватьсвои данные и получить активацию в одной из запрошенных вами ролей (Подписчик илиИздатель). См. подробнее о ролях раздел Режимы доступа ;
· После успешной регистрации, появляется возможность зайти в Личный кабинет, гденеобходимо заполнить дополнительную информацию по аккаунту. Если вырегистрируетесь как Издатель, то также необходимо составить список профилей(паспортов) торговых объектов, по которым ваш API-клиент будет загружать данные винформационную систему DobraTrade.
После регистрации и интерактивной настройки появляется возможность начатьвзаимодействие с API-сервером. Для начала вы можете проверить готовность к работе собственныхинструментальных средств разработки путем отправки запроса и получения соответствующегоотклика. Следующий запрос позволяет это сделать и не требует никакой предварительнойаутентификации:
HTTP-Метод: GETURL-действие: api.dobratrade.com/about
В результате ваше приложение должно получить json-структуру следующего вида приHTTP-статусе 200 OK:
{ "message": "DobraTrade REST API-server implementation"}
Из представленного выше примера видно, что в качестве целевого API-сервиса (endpointservice) следует использовать URL-адрес api.dobratrade.com. Для краткости в дальнейшем мы будетопускать эту часть URL-действия, представляя ее в форме многоточия - ... .
После проверки готовности можно перейти к следующей операции -аутентификация/получение сеансового токена для доступа к API-серверу. Данную операцию следуетпроизводить в следующих случаях:
· Последний раз токен пользователя был сформирован более чем 24 часа назад,следовательно, он устарел. Здесь мы исходим из того, что максимально возможнаядлительность последовательности различных операций текущего сеанса связи вашегоприложения с API-сервером укладывается во временной промежуток, равный 24 часа;
· Вам понадобилось войти в систему с помощью другого аккаунта. В этом случае выдолжны получить для него другой токен, а неиспользуемый токен другого аккаунтаутратит срок действия спустя 24 часа с момента появления.
· Ваше приложение непрерывно работает под конкретным аккаунтом, и в определённыймомент произошло устаревание действующего до этого токена. В этом случае припопытке выполнить следующую API-операцию, у вас произойдет отказ со http-статусомошибки 498 Token expired. Для продолжения работы следует предусмотретьвозбуждение исключительной ситуации и процедуру восстановления соединения путемзапроса нового токена и повторного выполнения "слетевшей" операции. В современныхязыках программирования для этого, например, могут послужить операторы типа raise,блочные конструкции begin...end с опциями rescue, ensure. В случае наличиявероятности неустойчивого соединения с API-сервером для большей надежности следуетпредусмотреть повторение определённое количество раз попытки получить новый токен(например, три раза с интервалом 5 с.).
· Вы можете запрашивать новый токен в любом случае каждый раз, когда начинаете сеансобмена с API-сервером. Каких-либо лимитов на количество генерируемых токенов несуществует.
Для установки соединения и получения сеансового токена необходимо отправить запросследующего вида:
11
Основные положения 11
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
HTTP-Метод: POSTURL-действие: .../auth/login?email=ваш_email&password=ваш_пароль
Если на API-сервере будет установлено соответствие между email-ом и указанным паролем,то в результате будет получен JSON-отклик с токеном авторизации, который необходимо будетуказывать при выполнении всех последующих операций:
{ "auth_token": "eyJhbGciOiJlUzl1Ni...47ZSNWbo"}
HTTP-статус операции при нормальном завершении устанавливается в 200 OK. Еслиуказаны неверные логин/пароль, то http-статус операции соответствует 401 Unauthorized.Обращаться к значению токена имеет смысл только в том случае, когда код статуса запроса будетсоответствовать 200. В остальных случаях значение токена будет недоступно, а величинапредставления зависеть от применяемого языка программирования (например, пустая строка илиnil). Полученный токен будет активным в течение 24 часов.
§1.3 - Роли доступа
API сервера системы DobraTrade обеспечивает двусторонний обмен данными склиентскими приложениями. С точки зрения направления обмена API поддерживает дваподмножества операций, для каждого из которых предусмотрены соответствующиефункциональные роли - Издатель и Подписчик. Тип роли, в которой будет функционировать API-клиент пользователя, настраивается по заявке администраторами сервиса и видна пользователю вего личном кабинете.
Каждая из ролей обладает следующими принципиальными особенностями:· Издатель - выполняет загрузку данных, относящихся к его табличному пространству, а
также актуализацию этих данных. При этом он не имеет возможности обращаться кданным других пользователей и модифицировать их. Подробнее о функциональностироли см. Использование API в роли Publisher (Издатель) ;
· Подписчик - может только читать данные, загруженные другими пользователями, атакже при необходимости накапливать их в собственной информационной базе данныхдля решения различного рода аналитических задач. Подробнее о функциональности ролисм. Использование API в роли Subscriber (Подписчик) .
Общим свойством для указанных ролей является возможность чтения по отношению к рядуклассификаторов/справочников, которые ведутся в системе DobraTrade и используются принаполнении её информационных массивов.
Подробнее о справочниках см. Справочники . Подробнее о доступных API-операциях сосправочниками см. Работа со справочниками посредством API .
§1.4 - Отправка запросов
После регистрации и настройки аккаунта можно приступать к формированию запросов иобработке результатов. В данном разделе рассмотрим общие требования к запросам любого типа.Детальное описание форматов вызова для конкретных запросов рассматриваются всоответствующих разделах руководства.
Для того, чтобы сервер смог обработать любой входящий запрос на уровне API-сервера,необходимо в HTTP-заголовке указать два параметра следующего вида:
Параметр Значение ОписаниеAccept application/vnd.dobra.
v1+jsonСодержит указание на формат отклика поставщикасервиса. С помощью префикса vnd указываетсяпоставщик dobra. Также важным элементом имениявляется суффикс версии - v1.
46
35
17
27
Документация RESTful API DobraTrade - версия v1.1.012
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
Параметр Значение ОписаниеЕсли в будущих релизах вам потребуетсяопределённая версия действия API, то вы можетеявно указать индекс версии после буквы v. Если в запрошенной версии по каким-то причинамотсутствует реализация указанного действия, топроисходит его поиск в более ранних версиях. Этопродолжается, пока не встретится его наиболееранняя реализация или не будет достигнута версияпо умолчанию. Таковой в данный момент считаетсяверсия v1.
Authorization ваш_уникальный_токен
Уникальный токен доступа, полученный приаутентификации. Значение токена следует "извлечь"из JSON-структуры, полученной при выполнениидействия /auth/login как описано в разделеПодключение, установка соединения . Токендействует 24 часа с момента его генерации сервероми указывает на аккаунт, от имени которогопроизводилась аутентификация.
Пример указания параметров заголовка в интерактивном режиме имеет вид:
Accept: application/vnd.dobra.v1+json
Authorization:
eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoyNywiZXhwIjoxNTQ4MTg2ODkxfQ.dz_OuCyJ2XlHBvr-
s5Dq2ZI13nZeDKiL3jmQBt6aMSY
Если по каким-то причинам при выполнении очередного запроса токен доступа не получилподтверждения, то обратитесь в раздел Статусы операций и обработка ошибок , чтобы узнать,как распознать и обработать подобные ситуации в вашем клиентском приложении.
§1.5 - Статусы операций и обработка ошибок
В процессе работы API-сервера каждый поступивший HTTP-запрос формирует код статусазавершения. Некоторые из них обрабатываются самим API-сервером и, помимо стандартного кодазавершения, в клиентском приложении имеется возможность получить также JSON-структуру споясняющим описанием статуса выполненной операции. Подобную функциональность можноиспользовать, например, для логирования процессов взаимодействия между API-клиентом исервером.
В следующей таблице представлены коды, которые формирует API-сервер, а также ситуации,при которых они возникают и какими при этом могут сопровождаться JSON-сообщениями.
Код HTTP-статуса Причина JSON-отклик200 ОК HTTP-запрос был успешно
выполнен.JSON-структура с записями всоответствии с содержаниемзапроса. См. подробнее разделы"Использование API ...".
201 Created Был успешно выполнен запрос насоздание записи в базе данных.
JSON-структура с содержимымсозданной записи.
204 No Content Был успешно выполнен запрос наудаление/изменение записи в базеданных.
Нет.
401 Unauthorized В запросе была примененанедопустимая комбинацияemail/пароль. В результате былоотказано в выдаче токена доступа.
{ "message": "Invalid credentials"}
9
12
Основные положения 13
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
Код HTTP-статуса Причина JSON-откликИспользуйте повторную попытку сдругими данными.
403 Forbidden Запрашиваемая операциянедоступна текущемупользователю. Например,Подписчик не имеет правизменять записи.
{ "message": "not allowed to<action>? this #<...>"}где: · <action> - название
запрещенного действия,например, update, destroy и т.д.;
· #<...> - содержимое записи, вотношении которой естьданное ограничение.
403 Forbidden Издатель не может иметь доступак "чужим" данным.
{ "message": "Creating data inanother dataspace is not allowed"}или{ "message": "Updating data inanother dataspace is not allowed"}или{ "message": "Touching data inanother dataspace is not allowed"}
404 Not Found Не удалось найти запись в базеданных; Издатель не имеет прав надоступ к чужим данным.
{ "message": "Sorry, record notfound."}
422 Unprocessable Entity При создании записи произошлаошибка, запись не создается.Например, для создаваемогоэлемента ошибочно указан коднесуществующего "родительского"элемента. Также возможен отказсоздать или изменить запись состороны процедур форматно-логического контроля на сервереAPI.
{ "message": "Invalid record"}
422 Unprocessable Entity Среди заголовочных HTTP-параметров отсутствует параметрпо имени Authorization. Егонеобходимо указать и придать емуверное значение для успешноговыполнения операции.Также ошибка возникает при"смешивании контента", т.е. когдатокен был сформирован попротоколу https, а затем тот же"клиент" предпринимает попыткуиспользовать его в запросе по http.
{ "message": "Missing token"}
422 Unprocessable Entity Применяемый токен несоответствует данному
{ "message": "Invalid token"
Документация RESTful API DobraTrade - версия v1.1.014
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
Код HTTP-статуса Причина JSON-откликпользователю. Возможно он доэтого не получил подтвержденияпри аутентификации или токениспользуется ошибочно, подменен.
}
498 Token expired У применяемого токена истек срокдействия.
{ "message": "Sorry, your token hasexpired. Please login to continue."}
500 Internal Server Error Произошла серьезная внутренняяошибка в работе приложения,которая завершилась аварийнымостановом работы сеанса.
Нет.
§1.6 - Форматно-логический контроль
Форматно-логический контроль (ФКЛ) - это совокупность процедур, осуществляемых API-сервером перед тем, как произойдет фиксация изменений в информационной базе данных. Составпроцедур ФЛК описан в соответствующих разделах руководства для тех ресурсов, по которым винтерфейсе API предусмотрены модифицирующие действия.
Если процедурой ФЛК было выявлено наличие ошибок, то клиентскому приложениювозвращается отказ на проведение операции с кодом HTTP-статуса ошибки 422 UnprocessableEntity и соответствующее сообщение в JSON-отклике, например:
HTTP-Метод: POST URL-действие: api.dobratrade.com/images?product_id=15&image_path=Dummy+URL...
В параметре image_path мы пытаемся передать URL недействительного формата.Содержание соответствующего JSON-отклика содержит описание ошибки и имеет вид:
{ "message": "Validation failed: Image path is not a valid URL"}
Если операция имеет несколько ошибок ФЛК, то сообщение об ошибках имеет вид списка сразделителем через запятую, например:
{ "message": "Validation failed: Refs country must exist, Refs country can't be blank, Address can'tbe blank, Email is invalid"}
§1.7 - Служебные поля JSON-элементов
На уровне табличных массивов в информационной базе данных DobraTrade предусмотреныстандартные поля, которые присутствуют в каждом из них. Они заполняются автоматически ииграют служебную роль в ряде процессов по обработке информации. Т.е., например, Издателю ненужно беспокоится о том, что поместить в служебные поля, так как сервер базы данных самсформирует для них нужные значения при соответствующем модифицирующем запросе.
Для краткости последующего изложения мы их будем пропускать, предполагая, что данныеполя имеются в составе каждого JSON-элемента любого из массивов.
Структура каждого JSON-элемента содержит следующие служебные поля:
Идентификатор поля Описаниеid Уникальный ключ записи в массиве.created_at Момент времени физического создания записи в массиве.
Основные положения 15
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
Идентификатор поля Описаниеupdated_at Момент времени физической последней модификации записи в массиве.
Момент времени представляется в относительно UTC, т.е. показывается в соответствии совсемирным координированным временем. Для перевода на свой часовой пояс, необходимодобавить смещение, имея в виду, что в связи с сезонным переводом часов (весна/осень) данноесмещение изменяется соответственно (UTC-время остается неизменным при таких переходах). Так,для временного пояса Минск смещение составляет +03:00 (https://time.is/ru/UTC).
Например, значение в виде "2018-01-21T20:03:47.434Z" содержит следущие элементы:· 2018-01-21 - дата в формате YYYY-MM-DD;· T20:03:47.434 - время в формате HH:MM:SS с повышенной точностью;· Z - смещение по зоне. В данном варианте его нет, т.е. это время по UTC.
Раздел
II
Последние изменения: 07.06.2019
Описание информационнойсхемы
Описание информационной схемы 17
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
РАЗДЕЛ 2: Описание информационной схемы
Массивы данных (или ресурсы) информационной схемы DobraTrade разделяются наследующие функциональные группы:
· Справочники. Объединяет массивы, которые содержат различные классификации длясистемы DobraTrade. См. подробнее Справочники .
· Торговые объекты. Объединяет массивы, содержащие сведения об их наименовании,местоположении, характере и способах торговли, режимы работы и др. . См. подробнееИнформационная группа Торговые объекты .
· Товары. Объединяет массивы, содержащие сведения о наличии товаров в торговыхобъектах, а также описания их потребительских характеристик. См. подробнееИнформационная группа Товары .
Так как над элементами справочников средствами API не предусмотрены модифицирующиеhttp-действия типа POST/DELETE/PATCH, то для них перечень процедур форматно-логическогоконтроля отсутствует.
§2.1 - Справочники
Справочники, доступные через методы API, можно просматривать в личном кабинетепользователя в режиме "только чтение". Непосредственное ведение и актуализация содержимогосамих справочников производится силами службы техподдержки системы DobraTrade.
Сами пользователи не имеют возможности интерактивно модифицировать содержимоесправочников. Среди методов API также отсутствуют модифицирующие действия. Если возниклапотребность в изменении каких-либо данных в справочниках, необходимо обратиться с запросом вслужбу техподдержки DobraTrade.
В состав информационной группы Справочники входят следующиие элементы:· Справочник Товарные группы ;· Справочник Единицы измерений ;· Справочник Валюты ;· Справочник Страны ;· Справочник Регионы ;· Справочник Категории торговых объектов .
§2.1.1 - Справочник Товарные группы
Доступ к справочнику Товарные группы на уровне API производится через URL-ресурсвида:
.../refs/product_groups
§2.1.1.1 - Назначение
Справочник Товарные группы классифицирует товары по группам назначения. Каждаятоварная позиция должна быть закреплена к той или иной товарной группе. Если Издательобнаружит, что его товарные позиции невозможно отнести к какой-либо из существующих всистеме DobraTrade групп, то ему следует обратиться с запросом в службу техподдержки, котораясоздаст необходимую группу товара и присвоит ей код идентификации.
§2.1.1.2 - Структура JSON-элемента
Структура JSON-элемента в теле http-отклика для справочника Товарные группы содержитследующие информационные поля:
Идентификатор поля Описаниеname Наименование товарной группы.products_count Количество товарных позиций, относящихся к данной группе. Итог по
группе накапливается в пределах всей информационой базы системы.
17
20
22
17
18
18
18
19
19
Документация RESTful API DobraTrade - версия v1.1.018
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
§2.1.2 - Справочник Единицы измерений
Доступ к справочнику Единицы измерений на уровне API производится через URL-ресурсвида:
.../refs/units
§2.1.2.1 - Назначение
Справочник Единицы измерений классифицирует единицы измерений для данных оналичии товаров в натуральных измерителях. Каждая товарная позиция хранит количествоактуального остатка на конкретном торговом объекте.
§2.1.2.2 - Структура JSON-элемента
Структура JSON-элемента в теле http-отклика для справочника Единицы измеренийсодержит следующие информационные поля:
Идентификатор поля Описаниеnumcode Числовой код по ОКЕИ.full_name Полная форма наименования.short_name Краткая форма наименования.
§2.1.3 - Справочник Валюты
Доступ к справочнику Валюты на уровне API производится через URL-ресурс вида:.../refs/currencies
§2.1.3.1 - Назначение
Справочник Валюты классифицирует валюты в соответствии с международным стандартомISO 4217 (ИСО 4217). Для каждой валюты указывается трёхбуквенное алфавитное и трёхзначноецифровое представление. Справочник используется при формировании мультивалютных "витрин"для торговых объектов и "потребительских корзин".
§2.1.3.2 - Структура JSON-элемента
Структура JSON-элемента в теле http-отклика для справочника Валюты содержитследующие информационные поля:
Идентификатор поля Описаниеnumcode Трёхзначное цифровое представление.abbr Трёхбуквенное алфавитное представление.name Полная форма наименования.
§2.1.4 - Справочник Страны
Доступ к справочнику Страны на уровне API производится через URL-ресурс вида:.../refs/countries
§2.1.4.1 - Назначение
Справочник Страны классифицирует страны в соответствии с международным стандартомISO 3166 (ИСО 3166). Помимо наименования, для каждой страны указаны двух- и трехзначныйсимвольные коды, а также числовой код. Справочник используется в механизме геолокализацииместоположения торговых объектов совместно со справочником Справочник "Регионы" .19
Описание информационной схемы 19
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
§2.1.4.2 - Структура JSON-элемента
Структура JSON-элемента в теле http-отклика для справочника Страны содержит следующиеинформационные поля:
Идентификатор поля Описаниеiso_name Наименование по стандарту ISO (заглавными).iso Двухсимвольный алфвитный код.iso3 Трехсимвольный алфавитный код.name Наименование по стандарту ISO.numcode Числовой код страны.states_required Признак, есть ли деление по регионам.refs_currency Корень для связанного JSON-элемента из Справочника Валюты .refs_currency_id Код id для ссылки на элемент типа валюты в Справочнике Валюты .
§2.1.5 - Справочник Регионы
Доступ к справочнику Регионы на уровне API производится через URL-ресурс вида:.../refs/states
§2.1.5.1 - Назначение
Справочник Регионы классифицирует регионы стран в соответствии с международнымстандартом ISO 3166 (ИСО 3166). Помимо наименования, для каждого региона указан кодаббревиатуры. Справочник используется в механизме геолокализации местоположения торговыхобъектов совместно со справочником Справочник "Страны" .
§2.1.5.2 - Структура JSON-элемента
Структура JSON-элемента в теле http-отклика для справочника Регионы содержитследующие информационные поля:
Идентификатор поля Описаниеname Наименование.abbr Алфавитное представление региона, аббревиатура.refs_country Корень для связанного JSON-элемента из Справочника Страны .refs_country_id Код id для ссылки на страну в Справочнике Страны .
§2.1.6 - Справочник Категории торговых объектов
Доступ к справочнику Категории торговых объектов на уровне API производится черезURL-ресурс вида:
.../refs/retail_categories
§2.1.6.1 - Назначение
Справочник Категории торговых объектов классифицирует типы торговых объектов,площадок, на которых представлены товары в информационной базе данных DobraTrade. С егопомощью можно образовывать направление аналитики, описывающее распределение товаров повидам, формам и способам торговли.
§2.1.6.2 - Структура JSON-элемента
Структура JSON-элемента в теле http-отклика из справочника Категории торговыхобъектов содержит следующие информационные поля:
Идентификатор поля Описаниеname Наименование категории.
18
18
18
18
18
Документация RESTful API DobraTrade - версия v1.1.020
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
§2.2 - Информационная группа Торговые объекты
В состав информационной группы Торговые объекты входят следующие элементы:· Массив Пользователи ;· Массив Профили торговых объектов ;· Массив Бизнес-профили .
§2.2.1 - Массив Пользователи
Доступ к массиву Пользователи на уровне API отсутствует за исключением единственногоPOST-метода, предназначенного для аутентификации /auth/login и описанного в Подключение,установка соединения .
С помощью режима Личного кабинета в web-приложении пользователи могут обслуживатьсвои личные аккаунты. Соответственно, при регистрации создается элемент массива Пользователь.После успешной аутентификации на сайте в Личном кабинете пользователь может редактироватьнастройки своего аккаунта, видеть статистику по его использованию, а также осуществлять инуюактивность, предусмотреную соответствующей ролью. При необходимости он там же может егоудалить, в результате чего удаляется вся связанная с аккаунтом информация (профили, товары,сохраненные запросы, товарные корзины и т.д.).
Сразу после регистрации пользователю присваивается первоначальная роль User. Онапредназначается для обычных посетителей, которые выполняют поиск товаров на сайте, и являетсясвободно-доступной.
Чтобы иметь доступ к коммерческим сервисам, предусмотренными ролями Издатель иПодписчик, необходимо обратиться с запросом в службу техподдержки, которая проведетнеобходимую верификацию созданного аккаунта. В результате он будет "продвинут" донеобходимой роли в соответствии с завкой владельца аккаунта.
§2.2.1.1 - Назначение
Массив Пользователи содержит сведения об аккаунтах, ассоциированных с владельцамиторговых объектов (только для Издателей). В свою очередь, один пользователь-Издатель можетиметь один и более связанных с ним торговых объектов (Профили). Для пользователей в ролиПодписчик не предусмотрено наличие профилей и других данных в информационных массивахсистемы DobraTrade.
§2.2.1.2 - Структура JSON-элемента
Структура JSON-элемента в теле http-отклика для массива Пользователи входит в составСтруктура JSON-элемента массива Профили торговых объектов в виде элемента user исодержит следующие информационные поля:
Идентификатор поля Описаниеname Наименование пользователя.
§2.2.1.3 - Форматно-логический контроль
В отношении массива Пользователи со стороны API не предусмотрено какого-либоформатно-логического контроля, так как в API не предусматривается модифицирующих http-действий типа POST/DELETE/PATCH. Все изменения производятся интерактивно в Личномкабинете аутентифицированного пользователя.
§2.2.2 - Массив Профили торговых объектов
Доступ к массиву Профили торговых объектов на уровне API производится через URL-ресурс вида:
.../profiles
20
20
21
9
21 20
Описание информационной схемы 21
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
§2.2.2.1 - Назначение
Массив Профили торговых объектов содержит контактные данные по каждому изторговых объектов владельца/пользователя.
§2.2.2.2 - Структура JSON-элемента
Структура JSON-элемента в теле http-отклика для массива Профили торговых объектовсодержит следующие информационные поля:
Идентификатор поля Описаниеaddress Адрес нахождения торгового объекта.latitude Широта для координат геолокации торгового объекта.longitude Долгота для координат геолокации торгового объекта.email Контактный email.name Наименование торгового объекта.phone_number Контактный телефон.products_count Количество товарных позиций, размещенных к продаже на торговом
объекте.refs_country Корень для связанного JSON-элемента из Справочника Страны .refs_country_id Код id для ссылки на страну в Справочнике Страны .user Корень для связанного JSON-элемента из Массива Пользователи .user_id Код id для ссылки на элемент из Массива Пользователи .
§2.2.2.3 - Форматно-логический контроль
В отношении массива Профили торговых объектов при выполнении модифицирующихhttp-действий типа POST/DELETE/PATCH предусмотрены следующие процедуры форматно-логического контроля:
Параметр Тип Контрольaddress Строковый. Обязательный.email Строковый. Обязательный. Формат e-mail.name Строковый. Обязательный.phone_number Строковый.refs_country_id Целочисленный. Обязательный.
§2.2.3 - Массив Бизнес-профили
Доступ к массиву Бизнес-профили на уровне API производится через URL-ресурс вида:.../business_profiles
§2.2.3.1 - Назначение
Массив Бизнес-профили содержит дополнительные сведения о торговом объекте, которыеобразуют его бизнес-профиль.
§2.2.3.2 - Структура JSON-элемента
Структура JSON-элемента в теле http-отклика для массива Бизнес-профили содержитследующие информационные поля:
Идентификатор поля Описаниеoperation_hours Описание режима работы торгового объекта.logo_path URL-ссылка на изображение логотипа торгового объекта.cert_path URL-ссылка на изображение удостоверяющего сертификата
(свидетельства) для торгового объекта.
29
29
20 20
20
Документация RESTful API DobraTrade - версия v1.1.022
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
Идентификатор поля Описаниеprofile Корень для связанного JSON-элемента из массиве Профилей .profile_id Код id для ссылки на элемент в массиве Профилей .refs_retail_categories Ссылка на коллекцию связанных JSON-элементов из массива
Справочник Категории торговых объектов .
§2.2.3.3 - Форматно-логический контроль
В отношении массива Бизнес-профили при выполнении модифицирующих http-действийтипа POST/DELETE/PATCH предусмотрены следующие процедуры форматно-логического контроля:
Параметр Тип Контрольoperation_hours Строковый.logo_path Строковый. Формат URL-ссылки.cert_path Строковый. Формат URL-ссылки.profile_id Целочисленный. Обязательный.refs_retail_category_ids Массив скалярных целочисленных
значений.
§2.3 - Информационная группа Товары
В состав информационной группы Товары входят следующие элементы:· Массив Продукты/Товары ;· Массив Описание Продуктов/Товаров ;· Массив Изображения Продуктов/Товаров .
§2.3.1 - Массив Продукты/Товары
Доступ к массиву Продукты/Товары на уровне API производится через URL-ресурс вида:.../products
§2.3.1.1 - Назначение
Массив Продукты/Товары содержит ассортиментый перечень товаров на торговыхобъектах с указанием данных о наличии товара на объекте в натуральных единицах измерений.Опционально может указываться цена позиции в базовой валюте пользователя и другая полезнаяинформация (товарная группа, артикул, баркоды и т.д.).
§2.3.1.2 - Структура JSON-элемента
Структура JSON-элемента в теле http-отклика для массива Продукты/Товары содержитследующие информационные поля:
Идентификатор поля Описаниеarticle_code Код артикула продукта. Служит для внутри-системной идентификации
цены товара, в том числе при партионном учете.balance Величина остатка по товарной позиции продукта на торговом объекте
(для указанного profile_id). Представляется в виде текста с содержимым вчисловой форме. Также возможные варианты хранения в этом атрибутеданных в виде поясняющего текста:· Уточнять;· Уточнять наличие;· Всегда в наличии;· Нет в наличии.
barcode_ean Европейский код артикула для товара, присвоенный его производителем.
35
35
19
19
22
24
24
Описание информационной схемы 23
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
Идентификатор поля Описаниеbarcode_sku Значение для кода SKU (Stock Keeping Unit), предназначенного для
идентификации товаров при хранении на складах и внутреннихлогистических операциях.
barcode_upc Универсальный код для глобального отслеживания товара, в т.ч. наторговых объектах.
description Корень для связанного JSON-элемента из массива ОписанияПродуктов/Товаров .
images Ссылка на коллекцию связанных JSON-элементов из массиваИзображения Продуктов/Товаров .
name Наименование товарной позиции.price Цена товарной позиции.profile Корень для связанного JSON-элемента из массива Профили торговых
объектов .profile_id Код id для ссылки на профиль в массиве Профили торговых объектов .refs_product_group Корень для связанного JSON-элемента из массива Товарные
группыrefs_product_group_id Код id для ссылки на профиль в массиве Товарные группы .refs_unit Корень для связанного JSON-элемента в массиве Единицы
измерений .refs_unit_id Код id для ссылки на профиль в массиве Единицы измерений .
§2.3.1.3 - Форматно-логический контроль
В отношении массива Продукты/Товары при выполнении модифицирующих http-действий типа POST/DELETE/PATCH предусмотрены следующие процедуры форматно-логическогоконтроля:
Параметр Тип Контрольarticle_code Строковый. Обязательный. Уникальный в пределах каждого
profile_id.balance Числовой с
фиксированнойзапятой(точность 4знака).
Обязательный. При записи должны сохранятьсячисловые величины. Обычно остаток является >0. Еслибыло записано отрицательное значение, то при чтенииони могут возвращать текстовые литералы последующим правилам:· -1 - 'Уточнять';· -2 - 'Уточнять наличие';· -3 - 'Всегда в наличии';· -4 - 'Нет в наличии'.
barcode_ean Строковый.barcode_sku Строковый.barcode_upc Строковый.name Строковый. Обязательный.price Числовой с
фиксированнойзапятой(точность 2знака).
profile_id Целочисленный. Обязательный.refs_product_group_id Целочисленный. Обязательный.refs_unit_id Целочисленный. Обязательный.
24
24
24
24
21
20
20
17
17
17
18
18
18
Документация RESTful API DobraTrade - версия v1.1.024
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
§2.3.2 - Массив Описания Продуктов/Товаров
Доступ к массиву Описания Продуктов/Товаров на уровне API производится через URL-ресурс вида:
.../descriptions
§2.3.2.1 - Назначение
Массив Описания Продуктов/Товаров содержит по каждому товару опциональную запись сдополнительными данными о его потребительских свойствах.
§2.3.2.2 - Структура JSON-элемента
Структура JSON-элемента в теле http-отклика для массива Описания Продуктов/Товаровсодержит следующие информационные поля:
Идентификатор поля Описаниеbrutto Данные о массе брутто.description Текст с подробным описанием характеристик товара.dimensions Данные о размерных признаках товара.manufacturer Сведения о производителе.netto Данные о массе нетто.refs_country_id Код id для ссылки на страну в массиве Справочник Страны . Страна
происхождения товара.product_id Код id для ссылки на товар в массиве Продукты/Товары .reserved Поле для прочих отметок.
§2.3.2.3 - Форматно-логический контроль
В отношении массива Описания Продуктов/Товаров при выполнении модифицирующихhttp-действий типа POST/DELETE/PATCH предусмотрены следующие процедуры форматно-логического контроля:
Параметр Тип Контрольbrutto Строковый.description Строковый. Обязательный.dimensions Строковый.manufacturer Строковый.netto Строковый.refs_country_id Целочисленный. Обязательный.product_id Целочисленный. Обязательный.reserved Строковый.
§2.3.3 - Массив Изображения Продуктов/Товаров
Доступ к массиву Изображения Продуктов/Товаров на уровне API производится черезURL-ресурс вида:
.../images
§2.3.3.1 - Назначение
Массив Изображения Продуктов/Товаров содержит по каждому товару коллекцию записейсо статическими URL-ссылками на его изображения.
§2.3.3.2 - Структура JSON-элемента
Структура JSON-элемента в теле http-отклика для массива ИзображенияПродуктов/Товаров содержит следующие информационные поля:
18
22
Описание информационной схемы 25
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
Идентификатор поля Описаниеimage_path URL-ссылка на изображение товара.product_id Код id для ссылки на товар в массиве Продукты/Товары .
§2.3.3.3 - Форматно-логический контроль
В отношении массива Изображения Продуктов/Товаров при выполнениимодифицирующих http-действий типа POST/DELETE/PATCH предусмотрены следующие процедурыформатно-логического контроля:
Параметр Тип Контрольimage_path Строковый. Обязательный. Формат URL-ссылки.product_id Целочисленный. Обязательный.
22
Раздел
III
Последние изменения: 26.03.2018
Работа со справочниками вAPI
Работа со справочниками в API 27
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
РАЗДЕЛ 3: Работа со справочниками в API
API-действия, связанные со справочниками, являются "только читающие" и доступныкаждой из ролей: Подписчик и Издатель.
§3.1 - Справочник Товарные группы
Рассмотрим какие действия доступны на уровне API для соответствующегоресурса /refs/product_groups.
§3.1.1 - Получить коллекцию элементов
HTTP-метод: GETURL-действие: .../refs/product_groupsОписание: Возвращает коллекцию JSON-элементов для всех записей справочника Товарныегруппы.На выходе:[ { "created_at": "2018-01-17T20:07:30.157Z", "id": 1, "name": "Товары для дома: сантехника", "products_count": 0, "updated_at": "2018-01-17T20:07:30.157Z" }, { "created_at": "2018-03-09T23:56:49.052Z", "id": 2, "name": "Товары для ухода за животными", "products_count": 0, "updated_at": "2018-03-09T23:56:54.573Z" }, { "created_at": "2018-03-09T23:57:31.728Z", "id": 3, "name": "Галантерейные товары", "products_count": 0, "updated_at": "2018-03-09T23:57:35.132Z" }, { "created_at": "2018-03-09T23:58:04.720Z", "id": 4, "name": "Бытовая химия", "products_count": 0, "updated_at": "2018-03-09T23:58:08.379Z" }, ...]
§3.1.2 - Получить элемент коллекции
HTTP-метод: GET URL-действие: .../refs/product_groups/:idПараметры: :id - число, соответствующее значению из поля id массива.Описание: Возвращает JSON-элемент для записи из справочника Товарные группы с указаннымзначением параметра id.Пример: .../refs/product_groups/1На выходе: { "created_at": "2018-01-17T20:07:30.157Z",
17
17
Документация RESTful API DobraTrade - версия v1.1.028
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
"id": 1, "name": "Товары для дома: сантехника", "products_count": 0, "updated_at": "2018-01-17T20:07:30.157Z"}
§3.2 - Справочник Единицы измерений
Рассмотрим какие действия доступны на уровне API для соответствующегоресурса /refs/units.
§3.2.1 - Получить коллекцию элементов
HTTP-метод: GETURL-действие: .../refs/unitsОписание: Возвращает коллекцию JSON-элементов для всех записей справочника Единицыизмерений.На выходе: [ { "created_at": "2018-01-15T00:33:57.403Z", "full_name": "метр", "id": 1, "numcode": "006", "short_name": "м.", "updated_at": "2018-01-15T00:33:57.403Z" }, { "created_at": "2018-01-15T00:33:57.423Z", "full_name": "Квадратный метр", "id": 2, "numcode": "055", "short_name": "м2", "updated_at": "2018-01-15T00:33:57.423Z" }, { "created_at": "2018-01-15T00:33:57.448Z", "full_name": "Кубический сантиметр", "id": 3, "numcode": "111", "short_name": "см3", "updated_at": "2018-01-15T00:33:57.448Z" },...]
§3.2.2 - Получить элемент коллекции
HTTP-метод: GETURL-действие: .../refs/units/:idПараметры: :id - число, соответствующее значению из поля id массива.Описание: Возвращает JSON-элемент для записи из справочника Единицы измерений суказанным значением параметра id.Пример: .../refs/units/3На выходе: { "created_at": "2018-01-15T00:33:57.448Z", "full_name": "Кубический сантиметр", "id": 3, "numcode": "111", "short_name": "см3", "updated_at": "2018-01-15T00:33:57.448Z"
18
18
Работа со справочниками в API 29
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
}
§3.3 - Справочник Валюты
Рассмотрим какие действия доступны на уровне API для соответствующегоресурса /refs/currencies.
§3.3.1 - Получить коллекцию элементов
HTTP-метод: GETURL-действие: .../refs/currenciesОписание: Возвращает коллекцию JSON-элементов для всех записей справочника Валюты.На выходе: [... { "abbr": "ZWN", "created_at": "2018-01-15T00:34:02.244Z", "id": 184, "name": "Zimbabwean Dollar", "numcode": "942", "updated_at": "2018-01-15T00:34:02.244Z" }, { "abbr": "ZWR", "created_at": "2018-01-15T00:34:02.266Z", "id": 185, "name": "Zimbabwean Dollar", "numcode": "935", "updated_at": "2018-01-15T00:34:02.266Z" }]
§3.3.2 - Получить элемент коллекции
HTTP-метод: GETURL-действие: .../refs/currencies/:idПараметры: :id - число, соответствующее значению из поля id массива.Описание: Возвращает JSON-элемент для записи из справочника Валюты с указанным значениемпараметра id.Пример: .../refs/currencies/172На выходе: { "abbr": "BTC", "created_at": "2018-01-15T00:34:02.015Z", "id": 172, "name": "Bitcoin", "numcode": "", "updated_at": "2018-01-15T00:34:02.015Z"}
§3.4 - Справочник Страны
Рассмотрим какие действия доступны на уровне API для соответствующегоресурса /refs/countries.
§3.4.1 - Получить коллекцию элементов
HTTP-метод: GETURL-действие: .../refs/countriesОписание: Возвращает коллекцию JSON-элементов для всех записей справочника Страны.
18
18
19
Документация RESTful API DobraTrade - версия v1.1.030
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
На выходе: [... { "created_at": "2018-01-15T00:34:14.082Z", "id": 246, "iso": "ZA", "iso3": "ZAF", "iso_name": "ЮАР", "name": "ЮАР", "numcode": 710, "refs_currency": { "abbr": "ZAR", "created_at": "2018-01-15T00:34:01.971Z", "id": 169, "name": "South African Rand", "numcode": "710", "updated_at": "2018-01-15T00:34:01.971Z" }, "refs_currency_id": 169, "states_required": true, "updated_at": "2018-01-15T00:34:14.082Z" }, { "created_at": "2018-01-15T00:34:14.099Z", "id": 247, "iso": "ZM", "iso3": "ZMB", "iso_name": "Замбия", "name": "Замбия", "numcode": 894, "refs_currency": { "abbr": "ZMW", "created_at": "2018-01-15T00:34:02.001Z", "id": 171, "name": "Zambian Kwacha", "numcode": "967", "updated_at": "2018-01-15T00:34:02.001Z" }, "refs_currency_id": 171, "states_required": true, "updated_at": "2018-01-15T00:34:14.099Z" }, { "created_at": "2018-01-15T00:34:14.117Z", "id": 248, "iso": "ZW", "iso3": "ZWE", "iso_name": "Зимбабве", "name": "Зимбабве", "numcode": 716, "refs_currency": { "abbr": "ZWD", "created_at": "2018-01-15T00:34:02.206Z", "id": 182, "name": "Zimbabwean Dollar", "numcode": "716", "updated_at": "2018-01-15T00:34:02.206Z" }, "refs_currency_id": 182, "states_required": true, "updated_at": "2018-01-15T00:34:14.117Z" }]
Работа со справочниками в API 31
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
§3.4.2 - Получить элемент коллекции
HTTP-метод: GETURL-действие: .../refs/countries/:idПараметры: :id - число, соответствующее значению из поля id массива.Описание: Возвращает JSON-элемент для записи из справочника Страны с указанным значениемпараметра id.Пример: .../refs/countries/57На выходе: { "created_at": "2018-01-15T00:34:07.944Z", "id": 57, "iso": "DE", "iso3": "DEU", "iso_name": "Германия", "name": "Германия", "numcode": 276, "refs_currency": { "abbr": "EUR", "created_at": "2018-01-15T00:33:59.014Z", "id": 45, "name": "Euro", "numcode": "978", "updated_at": "2018-01-15T00:33:59.014Z" }, "refs_currency_id": 45, "states_required": true, "updated_at": "2018-01-15T00:34:07.944Z"}
§3.5 - Справочник Регионы
Рассмотрим какие действия доступны на уровне API для соответствующегоресурса /refs/states.
§3.5.1 - Получить коллекцию элементов
HTTP-метод: GETURL-действие: .../refs/states?page=:value Параметры: page - номер страницы коллекции. Размер страницы равен 50 элементов. Если неуказан номер страницы, то считается, что page=1.Описание: Возвращает постранично коллекцию JSON-элементов для всех записей справочникаРегионы.Пример: .../refs/states?page=1На выходе:[ { "abbr": "02", "created_at": "2018-01-15T00:34:14.465Z", "id": 1, "name": "Canillo", "refs_country": { "created_at": "2018-01-15T00:34:05.914Z", "id": 1, "iso": "AD", "iso3": "AND", "iso_name": "Андорра", "name": "Андорра", "numcode": 20, "refs_currency_id": 45, "states_required": true, "updated_at": "2018-01-15T00:34:05.914Z"
19
19
Документация RESTful API DobraTrade - версия v1.1.032
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
}, "refs_country_id": 1, "updated_at": "2018-01-15T00:34:14.465Z" }, { "abbr": "03", "created_at": "2018-01-15T00:34:14.478Z", "id": 2, "name": "Encamp", "refs_country": { "created_at": "2018-01-15T00:34:05.914Z", "id": 1, "iso": "AD", "iso3": "AND", "iso_name": "Андорра", "name": "Андорра", "numcode": 20, "refs_currency_id": 45, "states_required": true, "updated_at": "2018-01-15T00:34:05.914Z" }, "refs_country_id": 1, "updated_at": "2018-01-15T00:34:14.478Z" }, ...]
§3.5.2 - Получить элемент коллекции
HTTP-метод: GETURL-действие: .../refs/states/:idПараметры: :id - число, соответствующее значению из поля id массива.Описание: Возвращает JSON-элемент для записи из справочника Регионы с указаннымзначением параметра id.Пример: .../refs/states/424На выходе: { "abbr": "ON", "created_at": "2018-01-15T00:34:24.984Z", "id": 424, "name": "Ontario", "refs_country": { "created_at": "2018-01-15T00:34:07.307Z", "id": 38, "iso": "CA", "iso3": "CAN", "iso_name": "Канада", "name": "Канада", "numcode": 124, "refs_currency_id": 26, "states_required": true, "updated_at": "2018-01-15T00:34:07.307Z" }, "refs_country_id": 38, "updated_at": "2018-01-15T00:34:24.984Z"}
§3.6 - Справочник Категории торговых объектов
Рассмотрим какие действия доступны на уровне API для соответствующегоресурса /refs/retail_categories.
19
Работа со справочниками в API 33
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
§3.6.1 - Получить коллекцию элементов
HTTP-метод: GETURL-действие: .../refs/retail_categoriesОписание: Возвращает коллекцию JSON-элементов для всех записей справочника Категорииторговых объектов. На выходе: [ { "created_at": "2018-01-15T00:33:57.055Z", "id": 1, "name": "Универмаг", "updated_at": "2018-01-15T00:33:57.055Z" }, { "created_at": "2018-01-15T00:33:57.135Z", "id": 5, "name": "Павильон рынка", "updated_at": "2018-01-15T00:33:57.135Z" }, { "created_at": "2018-01-15T00:33:57.089Z", "id": 3, "name": "Магазин розничной сети", "updated_at": "2018-01-15T00:33:57.089Z" }, { "created_at": "2018-01-15T00:33:57.127Z", "id": 4, "name": "Павильон торгового центра", "updated_at": "2018-01-15T00:33:57.127Z" }, { "created_at": "2018-03-10T02:55:20.478Z", "id": 10, "name": "Торговое место на рынке", "updated_at": "2018-03-10T02:55:25.112Z" }, { "created_at": "2018-03-10T02:58:41.003Z", "id": 11, "name": "Интернет-магазин", "updated_at": "2018-03-10T02:59:02.424Z" }]
§3.6.2 - Получить элемент коллекции
HTTP-метод: GETURL-действие: .../refs/retail_categories/:idПараметры: :id - число, соответствующее значению из поля id массива.Описание: Возвращает JSON-элемент для записи из справочника Категории торговых объектовс указанным значением параметра id.Пример: .../refs/retail_categories/4На выходе:{ "created_at": "2018-01-15T00:33:57.127Z", "id": 4, "name": "Павильон торгового центра", "updated_at": "2018-01-15T00:33:57.127Z"}
19
19
Раздел
IV
Последние изменения: 28.03.2018
Использование API в ролиSubscriber (Подписчик)
Использование API в роли Subscriber (Подписчик) 35
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
РАЗДЕЛ 4: Использование API в роли Subscriber(Подписчик)
Роль Подписчик (Subsriber) характеризуется тем, что в соответствии с политиками еенастройки, аутентифицированные пользователи в данной роли имеют доступ к действиям,позволяющим "только читать" данные из информационной базы DobraTrade, опубликованныедругими пользователями в роли Издатель (Publisher). При попытках произвести модифицирющеедействие API-сервер формирует отказ с кодом завершения 403 Forbiden.
§4.1 - Информационная группа Торговые объекты
Рассмотрим API-методы для получения Подписчиками данных о торговых объектах болееподробно.
§4.1.1 - Работа с Профилями
При сериализации элемента ресурса profiles в нём дополнительно указываются связанныеJSON-элементы ресурсов refs_countries и users.
§4.1.1.1 - Получить коллекцию элементов
HTTP-метод: GETURL-действие: .../profiles?page=:valueПараметры: page - номер страницы коллекции. Размер страницы равен 50 элементов. Если неуказан номер страницы, то считается, что page=1.Описание: Возвращает постранично коллекцию JSON-элементов для всех записей массиваПрофили.Пример: .../profiles?page=1На выходе: [ { "address": "г.Приморск, ул.Передовая, д.4", "latitude": 31222.0, "longitude": 45565.0, "created_at": "2018-01-21T20:02:45.134Z", "email": "[email protected]", "id": 1, "name": "Магазин стильной одежды", "phone_number": "(22)-222-22-22", "products_count": 1500, "refs_country": { "created_at": "2018-01-15T00:34:07.242Z", "id": 36, "iso": "BY", "iso3": "BLR", "iso_name": "Беларусь", "name": "Беларусь", "numcode": 112, "refs_currency_id": 24, "states_required": true, "updated_at": "2018-01-15T00:34:07.242Z" }, "refs_country_id": 36, "updated_at": "2018-01-21T20:02:48.123Z", "user": { "id": 2, "name": "Торговая сеть \"Оптима\"" }, "user_id": 2 },
21
Документация RESTful API DobraTrade - версия v1.1.036
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
{ "address": "г.Загорск, ул. Дорожная, д.3", "created_at": "2018-01-21T20:03:18.048Z", "email": "[email protected]", "id": 2, "name": "Магазин детской одежды", "phone_number": "(11)-111-11-11", "products_count": 5000, "refs_country": { "created_at": "2018-01-15T00:34:07.242Z", "id": 36, "iso": "BY", "iso3": "BLR", "iso_name": "Беларусь", "name": "Беларусь", "numcode": 112, "refs_currency_id": 24, "states_required": true, "updated_at": "2018-01-15T00:34:07.242Z" }, "refs_country_id": 36, "updated_at": "2018-01-21T20:03:21.247Z", "user": { "id": 2, "name": "Торговая сеть \"Оптима\"" }, "user_id": 2 }...]
§4.1.1.2 - Получить элемент коллекции
HTTP-метод: GETURL-действие: .../profiles/:idПараметры: :id - число, соответствующее значению из поля id массива.Описание: Возвращает JSON-элемент для записи из массива Профилей с указанным значениемпараметра id.Пример: .../profiles/2На выходе: { "address": "г.Загорск, ул. Дорожная, д.3", "latitude": 31222.0, "longitude": 45565.0, "created_at": "2018-01-21T20:03:18.048Z", "email": "[email protected]", "id": 2, "name": "Магазин детской одежды", "phone_number": "(11)-111-11-11", "products_count": 5000, "refs_country": { "created_at": "2018-01-15T00:34:07.242Z", "id": 36, "iso": "BY", "iso3": "BLR", "iso_name": "Беларусь", "name": "Беларусь", "numcode": 112, "refs_currency_id": 24, "states_required": true, "updated_at": "2018-01-15T00:34:07.242Z" }, "refs_country_id": 36, "updated_at": "2018-01-21T20:03:21.247Z",
21
Использование API в роли Subscriber (Подписчик) 37
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
"user": { "id": 2, "name": "Торговая сеть \"Оптима\"" }, "user_id": 2}
§4.1.2 - Работа с Бизнес-Профилями
При сериализации элемента ресурса business_profiles в нём дополнительно указываютсясвязанные JSON-элементы ресурсов profiles и refs_retail_categories.
§4.1.2.1 - Получить коллекцию элементов
HTTP-метод: GETURL-действие: .../business_profiles?page=:valueПараметры: page - номер страницы коллекции. Размер страницы равен 50 элементов. Если неуказан номер страницы, то считается, что page=1.Описание: Возвращает постранично коллекцию JSON-элементов для всех записей массиваБизнес-профилей.Пример: .../business_profiles?page=1На выходе: [ { "created_at": "2018-03-11T15:21:44.666Z", "id": 1, "operation_hours": "Пн-Пт, 9:00-17:00, без перерыва", "logo_path": "http://...", "cert_path": "http://...", "profile": { "address": "г.Загорск, ул. Дорожная, д.3", "created_at": "2018-01-21T20:03:18.048Z", "email": "[email protected]", "id": 2, "name": "Магазин детской одежды", "phone_number": "(11)-111-11-11", "products_count": 5000, "refs_country_id": 36, "updated_at": "2018-01-21T20:03:21.247Z", "user_id": 2 }, "profile_id": 2, "refs_retail_categories": [ { "id": 3, "name": "Универсам" } ], "updated_at": "2018-03-11T15:21:51.261Z" }, { "created_at": "2018-03-11T15:23:34.610Z", "id": 2, "operation_hours": "9:00-17:00, без выходных и перерыва", "profile": { "address": "г.Приморск, ул.Передовая, д.4", "created_at": "2018-01-21T20:02:45.134Z", "email": "[email protected]", "id": 1, "name": "Магазин стильной одежды", "phone_number": "(22)-222-22-22", "products_count": 1500, "refs_country_id": 36, "updated_at": "2018-01-21T20:02:48.123Z",
21
Документация RESTful API DobraTrade - версия v1.1.038
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
"user_id": 2 }, "profile_id": 1, "refs_retail_categories": [ { "id": 4, "name": "Павильон торгового центра" } ], "updated_at": "2018-03-11T15:23:40.323Z" }...]
§4.1.2.2 - Получить элемент коллекции
HTTP-метод: GETURL-действие: .../business_profiles/:idПараметры: :id - число, соответствующее значению из поля id массива.Описание: Возвращает JSON-элемент для записи из массива Бизнес-профилей с указаннымзначением параметра id.Пример: .../business_profiles/2На выходе: { "created_at": "2018-03-11T15:23:34.610Z", "id": 2, "operation_hours": "9:00-17:00, без выходных и перерыва", "logo_path": "http://...", "cert_path": "http://...", "profile": { "address": "г.Приморск, ул.Передовая, д.4", "created_at": "2018-01-21T20:02:45.134Z", "email": "[email protected]", "id": 1, "name": "Магазин стильной одежды", "phone_number": "(22)-222-22-22", "products_count": 1500, "refs_country_id": 36, "updated_at": "2018-01-21T20:02:48.123Z", "user_id": 2 }, "profile_id": 1, "refs_retail_categories": [ { "id": 4, "name": "Павильон торгового центра" } ], "updated_at": "2018-03-11T15:23:40.323Z"}
§4.2 - Информационная группа Товары
Рассмотрим API-методы для получения Подписчиками данных о товарах более подробно.
§4.2.1 - Работа с Продуктами/Описаниями/Изображениями
При сериализации элемента ресурса products в нём дополнительно указываются связанныеJSON-элементы ресурсов descriptions, images, profiles, refs_product_groups и refs_units.
21
Использование API в роли Subscriber (Подписчик) 39
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
§4.2.1.1 - Получить коллекцию элементов
HTTP-метод: GETURL-действие: .../products?page=:valueПараметры: page - номер страницы коллекции. Размер страницы равен 50 элементов. Если неуказан номер страницы, то считается, что page=1.Описание: Возвращает постранично коллекцию JSON-элементов для всех записей массиваПродукты/Товары.Пример: .../products?page=1На выходе: [ { "article_code": "ML-4336", "balance": "Уточнять наличие", "barcode_ean": null, "barcode_sku": null, "barcode_upc": null, "created_at": "2018-02-11T00:00:00.000Z", "description": { "brutto": null, "created_at": "2018-03-11T23:03:35.033Z", "description": "In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullamdictum felis eu pede mollis pretium. Integer tincidunt. ", "dimensions": "5,6,7,8", "id": 6, "manufacturer": "Simple JSC", "netto": null, "refs_country_id": 112, "product_id": 5, "reserved": null, "updated_at": "2018-03-11T23:03:38.649Z" }, "id": 5, "images":[ { "id":2, "product_id":5, "image_path":"https://....jpg", "created_at":"2018-06-21T11:11:58.161Z", "updated_at":"2018-08-25T13:18:05.557Z" }, { "id":3, "product_id":5, "image_path":"https://....jpg", "created_at":"2018-06-21T11:14:23.708Z", "updated_at":"2018-08-25T13:18:05.590Z" }, { "id":3, "product_id":5, "image_path":"https://....jpg", "created_at":"2018-09-11T10:55:51.167Z", "updated_at":"2018-09-11T10:55:51.167Z" } ], "name": "Шорты детские", "price": "15.0", "profile": { "address": "г.Загорск, ул. Дорожная, д.3", "created_at": "2018-01-21T20:03:18.048Z", "email": "[email protected]", "id": 2, "name": "Магазин детской одежды",
22
Документация RESTful API DobraTrade - версия v1.1.040
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
"phone_number": "(11)-111-11-11", "products_count": null, "refs_country_id": 36, "updated_at": "2018-01-21T20:03:21.247Z", "user_id": 2 }, "profile_id": 2, "refs_product_group": { "created_at": "2018-03-11T22:17:18.577Z", "id": 9, "name": "Верхняя одежда,трикотаж", "products_count": 0, "updated_at": "2018-03-11T22:17:23.354Z" }, "refs_product_group_id": 9, "refs_unit": { "created_at": "2018-01-15T00:33:58.024Z", "full_name": "Штука", "id": 33, "numcode": "796", "short_name": "шт.", "updated_at": "2018-01-15T00:33:58.024Z" }, "refs_unit_id": 33, "updated_at": "2018-02-11T00:00:00.000Z" }, { "article_code": "2364-H5", "balance": "14.1223", "barcode_ean": null, "barcode_sku": null, "barcode_upc": null, "created_at": "2018-01-22T07:28:21.632Z", "description": { "brutto": null, "created_at": "2018-01-29T01:36:16.081Z", "description": "Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem.Nulla consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget,arcu.", "dimensions": "4,3,2,1", "id": 2, "manufacturer": "XYZ JSC", "netto": null, "refs_country_id": 112, "product_id": 3, "reserved": null, "updated_at": "2018-01-29T01:36:21.056Z" }, "id": 3, "images":[ { "id":4, "product_id":3, "image_path":"https://....jpg", "created_at":"2018-06-21T11:11:58.161Z", "updated_at":"2018-08-25T13:18:05.557Z" }, { "id":5, "product_id":3, "image_path":"https://....jpg", "created_at":"2018-09-11T10:55:51.167Z", "updated_at":"2018-09-11T10:55:51.167Z" } ],
Использование API в роли Subscriber (Подписчик) 41
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
"name": "Халат женский", "price": "50.0", "profile": { "address": "г.Приморск, ул.Передовая, д.4", "created_at": "2018-01-21T20:02:45.134Z", "email": "[email protected]", "id": 1, "name": "Магазин стильной одежды", "phone_number": "(22)-222-22-22", "products_count": null, "refs_country_id": 36, "updated_at": "2018-01-21T20:02:48.123Z", "user_id": 2 }, "profile_id": 1, "refs_product_group": { "created_at": "2018-03-11T22:17:18.577Z", "id": 9, "name": "Верхняя одежда,трикотаж", "products_count": 0, "updated_at": "2018-03-11T22:17:23.354Z" }, "refs_product_group_id": 9, "refs_unit": { "created_at": "2018-01-15T00:33:58.024Z", "full_name": "Штука", "id": 33, "numcode": "796", "short_name": "шт.", "updated_at": "2018-01-15T00:33:58.024Z" }, "refs_unit_id": 33, "updated_at": "2018-01-22T07:28:25.622Z" }, { "article_code": "С233-14", "balance": "Нет в наличии", "barcode_ean": null, "barcode_sku": null, "barcode_upc": null, "created_at": "2018-01-21T20:09:28.516Z", "description": { "brutto": null, "created_at": "2018-01-29T04:39:44.267Z", "description": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodoligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes,nascetur ridiculus mus.", "dimensions": "1,2,3,4", "id": 1, "manufacturer": "ABC Company", "netto": null, "refs_country_id": 179, "product_id": 1, "reserved": null, "updated_at": "2018-01-29T04:39:49.686Z" }, "id": 1, "images":[ { "id":6, "product_id":1, "image_path":"https://....jpg", "created_at":"2018-06-21T11:11:58.161Z", "updated_at":"2018-08-25T13:18:05.557Z" },
Документация RESTful API DobraTrade - версия v1.1.042
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
{ "id":7, "product_id":1, "image_path":"https://....jpg", "created_at":"2018-09-11T10:55:51.167Z", "updated_at":"2018-09-11T10:55:51.167Z" } ], "name": "Сандалии летние", "price": "20.0", "profile": { "address": "г.Загорск, ул. Дорожная, д.3", "created_at": "2018-01-21T20:03:18.048Z", "email": "[email protected]", "id": 2, "name": "Магазин детской одежды", "phone_number": "(11)-111-11-11", "products_count": null, "refs_country_id": 36, "updated_at": "2018-01-21T20:03:21.247Z", "user_id": 2 }, "profile_id": 2, "refs_product_group": { "created_at": "2018-03-09T23:58:48.524Z", "id": 6, "name": "Обувь", "products_count": 0, "updated_at": "2018-03-09T23:58:51.707Z" }, "refs_product_group_id": 6, "refs_unit": { "created_at": "2018-01-15T00:33:57.723Z", "full_name": "Пара", "id": 20, "numcode": "715", "short_name": "пар", "updated_at": "2018-01-15T00:33:57.723Z" }, "refs_unit_id": 20, "updated_at": "2018-01-21T20:09:31.223Z" }, { "article_code": "Y-XXL-80", "balance": "Уточнять", "barcode_ean": null, "barcode_sku": null, "barcode_upc": null, "created_at": "2018-02-11T00:00:00.000Z", "description": { "brutto": null, "created_at": "2018-03-11T23:03:49.650Z", "description": "Cras dapibus. Vivamus elementum semper nisi. Aenean vulputate eleifendtellus. Aenean leo ligula, porttitor eu, consequat vitae, eleifend ac, enim.", "dimensions": "8,7,6,5", "id": 7, "manufacturer": "JSC Brave", "netto": null, "refs_country_id": 48, "product_id": 6, "reserved": null, "updated_at": "2018-03-11T23:03:52.503Z" }, "id": 6, "images":[
Использование API в роли Subscriber (Подписчик) 43
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
{ "id":8, "product_id":6, "image_path":"https://....jpg", "created_at":"2018-06-21T11:11:58.161Z", "updated_at":"2018-08-25T13:18:05.557Z" } ], "name": "Мужской костюм", "price": "110.0", "profile": { "address": "г.Приморск, ул.Передовая, д.4", "created_at": "2018-01-21T20:02:45.134Z", "email": "[email protected]", "id": 1, "name": "Магазин стильной одежды", "phone_number": "(22)-222-22-22", "products_count": null, "refs_country_id": 36, "updated_at": "2018-01-21T20:02:48.123Z", "user_id": 2 }, "profile_id": 1, "refs_product_group": { "created_at": "2018-03-11T22:17:18.577Z", "id": 9, "name": "Верхняя одежда,трикотаж", "products_count": 0, "updated_at": "2018-03-11T22:17:23.354Z" }, "refs_product_group_id": 9, "refs_unit": { "created_at": "2018-01-15T00:33:58.024Z", "full_name": "Штука", "id": 33, "numcode": "796", "short_name": "шт.", "updated_at": "2018-01-15T00:33:58.024Z" }, "refs_unit_id": 33, "updated_at": "2018-02-11T00:00:00.000Z" }]
§4.2.1.2 - Получить элемент коллекции
HTTP-метод: GETURL-действие: .../products/:idПараметры: :id - число, соответствующее значению из поля id массива.Описание: Возвращает JSON-элемент для записи из массива Продукты/Товары с указаннымзначением параметра id.Пример: .../products/3На выходе: { "article_code": "2364-H5", "balance": "14.1223", "barcode_ean": null, "barcode_sku": null, "barcode_upc": null, "created_at": "2018-01-22T07:28:21.632Z", "description": { "brutto": null, "created_at": "2018-01-29T01:36:16.081Z",
22
Документация RESTful API DobraTrade - версия v1.1.044
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
"description": "Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nullaconsequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu.", "dimensions": "4,3,2,1", "id": 2, "manufacturer": "XYZ JSC", "netto": null, "refs_country_id": 112, "product_id": 3, "reserved": null, "updated_at": "2018-01-29T01:36:21.056Z" }, "id": 3, "images":[ { "id":4, "product_id":3, "image_path":"https://....jpg", "created_at":"2018-06-21T11:11:58.161Z", "updated_at":"2018-08-25T13:18:05.557Z" }, { "id":5, "product_id":3, "image_path":"https://....jpg", "created_at":"2018-09-11T10:55:51.167Z", "updated_at":"2018-09-11T10:55:51.167Z" } ], "name": "Халат женский", "price": "50.0", "profile": { "address": "г.Приморск, ул.Передовая, д.4", "created_at": "2018-01-21T20:02:45.134Z", "email": "[email protected]", "id": 1, "name": "Магазин стильной одежды", "phone_number": "(22)-222-22-22", "products_count": null, "refs_country_id": 36, "updated_at": "2018-01-21T20:02:48.123Z", "user_id": 2 }, "profile_id": 1, "refs_product_group": { "created_at": "2018-03-11T22:17:18.577Z", "id": 9, "name": "Верхняя одежда,трикотаж", "products_count": 0, "updated_at": "2018-03-11T22:17:23.354Z" }, "refs_product_group_id": 9, "refs_unit": { "created_at": "2018-01-15T00:33:58.024Z", "full_name": "Штука", "id": 33, "numcode": "796", "short_name": "шт.", "updated_at": "2018-01-15T00:33:58.024Z" }, "refs_unit_id": 33, "updated_at": "2018-01-22T07:28:25.622Z"}
Раздел
V
Последние изменения: 18.10.2018
Использование API в ролиPublisher (Издатель)
Документация RESTful API DobraTrade - версия v1.1.046
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
РАЗДЕЛ 5: Использование API в роли Publisher (Издатель)
Роль Издатель (Publisher) характеризуется тем, что в соответствии с политиками еенастройки, аутентифицированные пользователи в данной роли имеют доступ к методам API,реализующим полный набор CRUD-операций, но только в пределах своего "пространстваданных" (далее - датаспейс; dataspace) в информационной базе DobraTrade.
Каждый датаспейс образуется в контексте конкретного пользовательского аккаунтаИздателя и предоставляет все ассоциированные с ним данные. При попытках произвести чтениеили модифицирющее действие по отношению к данным в других датаспейсах API-сервер формируетотказ с кодом завершения 403 Forbidden.
§5.1 - Информационная группа Торговые объекты
Перед тем как формировать содержимое массивов данной группы, следует рассмотретьвозможность использования режима Личного кабинета и после регистрации/аутентификациивручную ввести в нем данные о профилях торговых объектов. Если предполагаемый объеминформации значителен, то можно применить API для разработки программы обмена данными и сее помощью выполнить начальную загрузку профилей с уровнем доступа аккаунта как Издатель(Publisher). Дальнейшую актуализацию в виде незначительных правок можно производитьнепосредствено в Личном кабинете.
Инфогруппа Торговые объекты описывает торговые объекты, относящиеся к аккаунтутекущего пользователя. К данной группе принадлежат следующие массивы, требующие наполненияв указанном порядке:
· Массив Профили торговых объектов - каждый элемент описывает торговый объект, покоторому текущий пользователь с правами Издателя может разместить в своемдатаспейсе актуальные сведения о наличии товаров на объекте;
· Массив Бизнес-профили - некоторые торговые объекты при необходимости могутсодержать дополнительные сведения, связанные с осуществляемой торговойдеятельностью. Они включают такие сведения, как часы и режимы работы,геокоординаты расположения розничной точки, виды и способы торговой деятельностии др. .
Рассмотрим API-методы для публикации Издателями данных о торговых объектах:· Работа с Профилями ;· Работа с Бизнес-Профилями .
§5.1.1 - Работа с Профилями
API-сервер предоставляет Издателям полный набор стандартных REST-действий надресурсом profiles.
Помимо стандартных REST-действий ресурс profiles предоставляет Издателям рядметодов, обеспечивающих дополнительный контроль над процессом загрузки данных винформационную базу DobraTrade.
§5.1.1.1 - Получить коллекцию элементов
HTTP-метод: GETURL-действие: .../profiles?page=:value или .../profiles/list?page=:valueПараметры: page - номер страницы коллекции. Размер страницы равен 50 элементов. Если неуказан номер страницы, то считается, что page=1.Описание: Возвращает постранично коллекцию JSON-элементов записей датаспейса текущегопользователя из массива Профили.Пример: .../profiles?page=1На выходе:[ { "address": "г.Приморск, ул.Передовая, д.4",
20
21
46
51
21
Использование API в роли Publisher (Издатель) 47
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
"latitude": 31222.0, "longitude": 45565.0, "created_at": "2018-01-21T20:02:45.134Z", "email": "[email protected]", "id": 1, "name": "Магазин стильной одежды", "phone_number": "(22)-222-22-22", "products_count": 1500, "refs_country": { "created_at": "2018-01-15T00:34:07.242Z", "id": 36, "iso": "BY", "iso3": "BLR", "iso_name": "Беларусь", "name": "Беларусь", "numcode": 112, "refs_currency_id": 24, "states_required": true, "updated_at": "2018-01-15T00:34:07.242Z" }, "refs_country_id": 36, "updated_at": "2018-01-21T20:02:48.123Z", "user": { "id": 2, "name": "Торговая сеть \"Оптима\"" }, "user_id": 2 }, { "address": "г.Загорск, ул. Дорожная, д.3", "latitude": 31222.0, "longitude": 45565.0, "created_at": "2018-01-21T20:03:18.048Z", "email": "[email protected]", "id": 2, "name": "Магазин детской одежды", "phone_number": "(11)-111-11-11", "products_count": 5000, "refs_country": { "created_at": "2018-01-15T00:34:07.242Z", "id": 36, "iso": "BY", "iso3": "BLR", "iso_name": "Беларусь", "name": "Беларусь", "numcode": 112, "refs_currency_id": 24, "states_required": true, "updated_at": "2018-01-15T00:34:07.242Z" }, "refs_country_id": 36, "updated_at": "2018-01-21T20:03:21.247Z", "user": { "id": 2, "name": "Торговая сеть \"Оптима\"" }, "user_id": 2 }]
§5.1.1.2 - Получить элемент коллекции
HTTP-метод: GETURL-действие: .../profiles/:idПараметры: :id - число, соответствующее значению из поля id массива.
Документация RESTful API DobraTrade - версия v1.1.048
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
Описание: Возвращает JSON-элемент записи датаспейса текущего пользователя из массиваПрофилей с указанным значением параметра id.Пример: .../profiles/2На выходе:{ "address": "г.Загорск, ул. Дорожная, д.3", "latitude": 31222.0, "longitude": 45565.0, "created_at": "2018-01-21T20:03:18.048Z", "email": "[email protected]", "id": 2, "name": "Магазин детской одежды", "phone_number": "(11)-111-11-11", "products_count": 5000, "refs_country": { "created_at": "2018-01-15T00:34:07.242Z", "id": 36, "iso": "BY", "iso3": "BLR", "iso_name": "Беларусь", "name": "Беларусь", "numcode": 112, "refs_currency_id": 24, "states_required": true, "updated_at": "2018-01-15T00:34:07.242Z" }, "refs_country_id": 36, "updated_at": "2018-01-21T20:03:21.247Z", "user": { "id": 2, "name": "Торговая сеть \"Оптима\"" }, "user_id": 2}
§5.1.1.3 - Создать элемент
HTTP-метод: POSTURL-действие: .../profilesПараметры: См. подробно Форматно-логический контроль .Описание: Создает запись в датаспейсе текущего пользователя массива Профилей с указаннымизначениями параметров.Пример: .../profiles?address="г.Загорск, ул. Дорожная, д.3"&email="[email protected]"&name="Магазиндетской одежды"&phone_number="(11)-111-11-11"&refs_country_id=36На выходе:{ "address": "г.Загорск, ул. Дорожная, д.3", "latitude": 31222.0, "longitude": 45565.0, "created_at": "2018-01-21T20:03:18.048Z", "email": "[email protected]", "id": 2, "name": "Магазин детской одежды", "phone_number": "(11)-111-11-11", "products_count": 0, "refs_country": { "created_at": "2018-01-15T00:34:07.242Z", "id": 36, "iso": "BY", "iso3": "BLR", "iso_name": "Беларусь", "name": "Беларусь", "numcode": 112,
21
21
Использование API в роли Publisher (Издатель) 49
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
"refs_currency_id": 24, "states_required": true, "updated_at": "2018-01-15T00:34:07.242Z" }, "refs_country_id": 36, "updated_at": "2018-01-21T20:03:21.247Z", "user": { "id": 2, "name": "Торговая сеть \"Оптима\"" }, "user_id": 2}
§5.1.1.4 - Изменить элемент
HTTP-метод: PATCHURL-действие: .../profiles/:idПараметры: :id - число, соответствующее значению из поля id массива. См. подробно Форматно-логический контроль .Описание: Модифицирует запись с указанным значением параметра :id в датаспейсе текущегопользователя массива Профилей.Пример: .../profiles/2?address="г.Дорожный, ул.Загорская, д.3"
§5.1.1.5 - Удалить элемент
HTTP-метод: DELETEURL-действие: .../profiles/:idПараметры: :id - число, соответствующее значению из поля id массива.Описание: Удаляет запись с указанным значением параметра :id в датаспейсе текущегопользователя массива Профилей. Предварительно происходит каскадное удаление связаннойнепосредственно с профилем информации в массивах Продукты/Товары , Бизнес-профили .Пример: .../profiles/2
§5.1.1.6 - Получить коллекцию Продуктов/Товаров профиля
HTTP-метод: GETURL-действие: ...profiles/:id/products?page=:valueПараметры: :id - число, соответствующее значению из поля id массива; page - номер страницыколлекции. Размер страницы равен 50 элементов. Если не указан номер страницы, то считается, чтоpage=1.Описание: Для указанного id: профиля из датаспейса текущего пользователя постраничновозвращает коллекцию JSON-элементов записей массива Продукты/Товары.Пример: ...profiles/2/products?page=1На выходе:[ { "article_code": "ML-4336", "balance": "Уточнять наличие", "barcode_ean": null, "barcode_sku": null, "barcode_upc": null, "created_at": "2018-02-11T00:00:00.000Z", "id": 5, "name": "Шорты детские", "price": "15.0", "profile_id": 2, "refs_product_group_id": 9, "refs_unit_id": 33, "updated_at": "2018-02-11T00:00:00.000Z" }, { "article_code": "С233-14",
21
22 21
22
Документация RESTful API DobraTrade - версия v1.1.050
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
"balance": "Нет в наличии", "barcode_ean": null, "barcode_sku": null, "barcode_upc": null, "created_at": "2018-01-21T20:09:28.516Z", "id": 1, "name": "Сандалии летние", "price": "20.0", "profile_id": 2, "refs_product_group_id": 6, "refs_unit_id": 20, "updated_at": "2018-01-21T20:09:31.223Z" } ]
§5.1.1.7 - Получить Продукт/Товар профиля по атрибуту article_code или sku
HTTP-метод: GETURL-действие: ...profiles/:id/product?article=:value или ...profiles/:id/product?sku=:valueПараметры: :id - число, соответствующее значению из поля id массива; article - код артикулапроизводителя товара; sku - складской номер хранения товара (Stock Keeping Unit).Описание: Для указанного id: профиля из датаспейса текущего пользователя возвращает JSON-элемент записи из массива Продукты/Товары со значением :value для указанного атрибута(article или sku).Пример: ...profiles/2/product?article=ML-4336На выходе:{ "article_code": "ML-4336", "balance": "Уточнять наличие", "barcode_ean": null, "barcode_sku": null, "barcode_upc": null, "created_at": "2018-02-11T00:00:00.000Z", "id": 5, "name": "Шорты детские", "profile_id": 2, "refs_product_group_id": 9, "refs_unit_id": 33, "updated_at": "2018-02-11T00:00:00.000Z"}
§5.1.1.8 - Получить Профили по атрибуту email
HTTP-метод: GETURL-действие: .../profiles/lookup?profile_email=:valueПараметры: profile_email - строка адреса email, принадлежащего искомому профилю.Описание: Возвращает коллекцию JSON-элементов записей датаспейса текущего пользователя измассива Профилей с указанным значением параметра profile_email.Пример: .../profiles/[email protected]На выходе:[ { "address": "г.Загорск, ул. Дорожная, д.3", "created_at": "2018-01-21T20:03:18.048Z", "email": "[email protected]", "id": 2, "name": "Магазин детской одежды", "phone_number": "(11)-111-11-11", "products_count": 5000, "refs_country": { "created_at": "2018-01-15T00:34:07.242Z", "id": 36, "iso": "BY",
22
21
Использование API в роли Publisher (Издатель) 51
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
"iso3": "BLR", "iso_name": "Беларусь", "name": "Беларусь", "numcode": 112, "refs_currency_id": 24, "states_required": true, "updated_at": "2018-01-15T00:34:07.242Z" }, "refs_country_id": 36, "updated_at": "2018-01-21T20:03:21.247Z", "user": { "id": 2, "name": "Торговая сеть \"Оптима\"" }, "user_id": 2 }]
§5.1.2 - Работа с Бизнес-Профилями
API-сервер предоставляет Издателям полный набор стандартных REST-действий надресурсом business_profiles.
При формировании элементов массива Бизнес-Профилей важно следовать типу отношенийс массивом Профили как "одни-к-одному". У любого Профиля допускается отсутствие Бизнес-Профиля. В случае необходимости у любого Профиля должен быть только один Бизнес-Профиль.
§5.1.2.1 - Получить коллекцию элементов
HTTP-метод: GETURL-действие: .../business_profiles?page=:valueПараметры: page - номер страницы коллекции. Размер страницы равен 50 элементов. Если неуказан номер страницы, то считается, что page=1.Описание: Возвращает постранично коллекцию JSON-элементов записей датаспейса текущегопользователя из массива Бизнес-Профили.Пример: .../business_profiles?page=1На выходе:[ { "created_at": "2018-03-11T15:21:44.666Z", "id": 1, "operation_hours": "Пн-Пт, 9:00-17:00, без перерыва", "logo_path": "http://...", "cert_path": "http://...", "profile": { "address": "г.Загорск, ул. Дорожная, д.3", "created_at": "2018-01-21T20:03:18.048Z", "email": "[email protected]", "id": 2, "name": "Магазин детской одежды", "phone_number": "(11)-111-11-11", "products_count": 5000, "refs_country_id": 36, "updated_at": "2018-01-21T20:03:21.247Z", "user_id": 2 }, "profile_id": 2, "refs_retail_categories": [ { "id": 3, "name": "Универсам" } ], "updated_at": "2018-03-11T15:21:51.261Z"
21
Документация RESTful API DobraTrade - версия v1.1.052
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
}, { "created_at": "2018-03-11T15:23:34.610Z", "id": 2, "operation_hours": "9:00-17:00, без выходных и перерыва", "logo_path": "http://...", "cert_path": "http://...", "profile": { "address": "г.Приморск, ул.Передовая, д.4", "created_at": "2018-01-21T20:02:45.134Z", "email": "[email protected]", "id": 1, "name": "Магазин стильной одежды", "phone_number": "(22)-222-22-22", "products_count": 1500, "refs_country_id": 36, "updated_at": "2018-01-21T20:02:48.123Z", "user_id": 2 }, "profile_id": 1, "refs_retail_categories": [ { "id": 4, "name": "Павильон торгового центра" } ], "updated_at": "2018-03-11T15:23:40.323Z" }]
§5.1.2.2 - Получить элемент коллекции
HTTP-метод: GETURL-действие: .../business_profiles/:idПараметры: :id - число, соответствующее значению из поля id массива.Описание: Возвращает JSON-элемент записи датаспейса текущего пользователя из массиваБинес-Профилей с указанным значением параметра id.Пример: .../business_profiles/2На выходе:{ "created_at": "2018-03-11T15:23:34.610Z", "id": 2, "operation_hours": "9:00-17:00, без выходных и перерыва", "logo_path": "http://...", "cert_path": "http://...", "profile": { "address": "г.Приморск, ул.Передовая, д.4", "created_at": "2018-01-21T20:02:45.134Z", "email": "[email protected]", "id": 1, "name": "Магазин стильной одежды", "phone_number": "(22)-222-22-22", "products_count": 1500, "refs_country_id": 36, "updated_at": "2018-01-21T20:02:48.123Z", "user_id": 2 }, "profile_id": 1, "refs_retail_categories": [ { "id": 3, "name": "Универсам" }, {
21
Использование API в роли Publisher (Издатель) 53
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
"id": 4, "name": "Павильон торгового центра" } ], "updated_at": "2018-03-11T15:23:40.323Z"}
§5.1.2.3 - Создать элемент
HTTP-метод: POSTURL-действие: .../business_profilesПараметры: См. подробно Форматно-логический контроль .Описание: Создает запись в датаспейсе текущего пользователя массива Бизнес-Профилей суказанными значениями параметров.Пример: .../business_profiles?operation_hours="9:00-17:00, без выходных иперерыва"&profile_id=1&refs_retail_category_ids[]=3&refs_retail_category_ids[]=4На выходе:{ "created_at": "2018-03-11T15:23:34.610Z", "id": 2, "operation_hours": "9:00-17:00, без выходных и перерыва", "logo_path": "", "cert_path": "", "profile": { "address": "г.Приморск, ул.Передовая, д.4", "created_at": "2018-01-21T20:02:45.134Z", "email": "[email protected]", "id": 1, "name": "Магазин стильной одежды", "phone_number": "(22)-222-22-22", "products_count": 1500, "refs_country_id": 36, "updated_at": "2018-01-21T20:02:48.123Z", "user_id": 2 }, "profile_id": 1, "refs_retail_categories": [ { "id": 3, "name": "Универсам" }, { "id": 4, "name": "Павильон торгового центра" } ], "updated_at": "2018-03-11T15:23:40.323Z"}
§5.1.2.4 - Изменить элемент
HTTP-метод: PATCHURL-действие: .../business_profiles/:idПараметры: :id - число, соответствующее значению из поля id массива. См. подробно Форматно-логический контроль .Описание: Модифицирует запись с указанным значением параметра :id в датаспейсе текущегопользователя массива Бизнес-Профилей.Пример: .../business_profiles/2?operation_hours="9:00-17:00, выходной - воскресенье"
§5.1.2.5 - Удалить элемент
HTTP-метод: DELETEURL-действие: .../business_profiles/:id
22
22
Документация RESTful API DobraTrade - версия v1.1.054
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
Параметры: :id - число, соответствующее значению из поля id массива.Описание: Удаляет запись с указанным значением параметра :id в датаспейсе текущегопользователя массива Бизнес-Профилей. Предварительно происходит каскадное удаление привязокк элементам массива Категории торговых объектов .Пример: .../business_profiles/2
§5.2 - Информационная группа Товары
Инфогруппа Товары включает массивы, хранящие данные о товарах. К данной группепринадлежат следующие массивы, требующие наполнения в указанном порядке:
· Массив Продукты/Товары . Содержит ассортиментый перечень товаров по каждому изторговых объектов с указанием данных о наличии товара на объекте в натуральныхединицах измерений. Опционально может указываться цена позиции в базовой валютепользователя и другая идентифицирующая информация (товарная группа, артикул,баркоды и т.д.);
· Массив Описание Продуктов/Товаров . Опционально при необходимости каждаятоварная позиция может снабжаться записью с данными, которые раскрываютдополнительные сведения о потребительских свойствах товара (детальное описание,массо-габариты, производитель, страна происхождения).
Рассмотрим API-методы для публикации Издателями данных о продуктах/товарах:· Работа с Продуктами/Товарами ;· Работа с Описаниями Продуктов/Товаров ;· Работа с Изображениями Продуктов/Товаров .
§5.2.1 - Работа с Продуктами/Товарами
API-сервер предоставляет Издателям полный набор стандартных REST-действий надресурсом products.
§5.2.1.1 - Получить коллекцию элементов
HTTP-метод: GETURL-действие: .../products?page=:valueПараметры: page - номер страницы коллекции. Размер страницы равен 50 элементов. Если неуказан номер страницы, то считается, что page=1.Описание: Возвращает постранично коллекцию JSON-элемента записей датаспейса текущегопользователя из массива Продукты/Товары.Пример: .../products?page=1На выходе:[ { "article_code": "ML-4336", "balance": "Уточнять наличие", "barcode_ean": null, "barcode_sku": null, "barcode_upc": null, "created_at": "2018-02-11T00:00:00.000Z", "description": { "brutto": null, "created_at": "2018-03-11T23:03:35.033Z", "description": "In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullamdictum felis eu pede mollis pretium. Integer tincidunt. ", "dimensions": "5,6,7,8", "id": 6, "manufacturer": "Simple JSC", "netto": null, "refs_country_id": 48, "product_id": 5, "reserved": null, "updated_at": "2018-03-11T23:03:38.649Z"
19
22
24
54
59
63
22
Использование API в роли Publisher (Издатель) 55
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
}, "id": 5, "images":[ { "id":2, "product_id":5, "image_path":"https://....jpg", "created_at":"2018-06-21T11:11:58.161Z", "updated_at":"2018-08-25T13:18:05.557Z" }, { "id":3, "product_id":5, "image_path":"https://....jpg", "created_at":"2018-06-21T11:14:23.708Z", "updated_at":"2018-08-25T13:18:05.590Z" }, { "id":3, "product_id":5, "image_path":"https://....jpg", "created_at":"2018-09-11T10:55:51.167Z", "updated_at":"2018-09-11T10:55:51.167Z" } ], "name": "Шорты детские", "price": "15.0", "profile": { "address": "г.Загорск, ул. Дорожная, д.3", "created_at": "2018-01-21T20:03:18.048Z", "email": "[email protected]", "id": 2, "name": "Магазин детской одежды", "phone_number": "(11)-111-11-11", "products_count": null, "refs_country_id": 36, "updated_at": "2018-01-21T20:03:21.247Z", "user_id": 2 }, "profile_id": 2, "refs_product_group": { "created_at": "2018-03-11T22:17:18.577Z", "id": 9, "name": "Верхняя одежда,трикотаж", "products_count": 0, "updated_at": "2018-03-11T22:17:23.354Z" }, "refs_product_group_id": 9, "refs_unit": { "created_at": "2018-01-15T00:33:58.024Z", "full_name": "Штука", "id": 33, "numcode": "796", "short_name": "шт.", "updated_at": "2018-01-15T00:33:58.024Z" }, "refs_unit_id": 33, "updated_at": "2018-02-11T00:00:00.000Z" }, { "article_code": "С233-14", "balance": "Нет в наличии", "barcode_ean": null, "barcode_sku": null, "barcode_upc": null,
Документация RESTful API DobraTrade - версия v1.1.056
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
"created_at": "2018-01-21T20:09:28.516Z", "description": { "brutto": null, "created_at": "2018-01-29T04:39:44.267Z", "description": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodoligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes,nascetur ridiculus mus.", "dimensions": "1,2,3,4", "id": 1, "manufacturer": "ABC Company", "netto": null, "refs_country_id": 179, "product_id": 1, "reserved": null, "updated_at": "2018-01-29T04:39:49.686Z" }, "id": 1, "images":[ { "id":6, "product_id":1, "image_path":"https://....jpg", "created_at":"2018-06-21T11:11:58.161Z", "updated_at":"2018-08-25T13:18:05.557Z" }, { "id":7, "product_id":1, "image_path":"https://....jpg", "created_at":"2018-09-11T10:55:51.167Z", "updated_at":"2018-09-11T10:55:51.167Z" } ], "name": "Сандалии летние", "price": "20.0", "profile": { "address": "г.Загорск, ул. Дорожная, д.3", "created_at": "2018-01-21T20:03:18.048Z", "email": "[email protected]", "id": 2, "name": "Магазин детской одежды", "phone_number": "(11)-111-11-11", "products_count": null, "refs_country_id": 36, "updated_at": "2018-01-21T20:03:21.247Z", "user_id": 2 }, "profile_id": 2, "refs_product_group": { "created_at": "2018-03-09T23:58:48.524Z", "id": 6, "name": "Обувь", "products_count": 0, "updated_at": "2018-03-09T23:58:51.707Z" }, "refs_product_group_id": 6, "refs_unit": { "created_at": "2018-01-15T00:33:57.723Z", "full_name": "Пара", "id": 20, "numcode": "715", "short_name": "пар", "updated_at": "2018-01-15T00:33:57.723Z" }, "refs_unit_id": 20,
Использование API в роли Publisher (Издатель) 57
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
"updated_at": "2018-01-21T20:09:31.223Z" } ]
§5.2.1.2 - Получить элемент коллекции
HTTP-метод: GETURL-действие: .../products/:idПараметры: :id - число, соответствующее значению из поля id массива.Описание: Возвращает JSON-элемент записи датаспейса текущего пользователя из массиваПродукты/Товары с указанным значением параметра id.Пример: .../products/5На выходе:{ "article_code": "ML-4336", "balance": "Уточнять наличие", "barcode_ean": null, "barcode_sku": null, "barcode_upc": null, "created_at": "2018-02-11T00:00:00.000Z", "description": { "brutto": null, "created_at": "2018-03-11T23:03:35.033Z", "description": "In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullam dictum felis eu pede mollis pretium. Integer tincidunt. ", "dimensions": "5,6,7,8", "id": 6, "manufacturer": "Simple JSC", "netto": null, "refs_country_id": 48, "product_id": 5, "reserved": null, "updated_at": "2018-03-11T23:03:38.649Z" }, "id": 5, "images":[ { "id":2, "product_id":5, "image_path":"https://....jpg", "created_at":"2018-06-21T11:11:58.161Z", "updated_at":"2018-08-25T13:18:05.557Z" }, { "id":3, "product_id":5, "image_path":"https://....jpg", "created_at":"2018-06-21T11:14:23.708Z", "updated_at":"2018-08-25T13:18:05.590Z" }, { "id":3, "product_id":5, "image_path":"https://....jpg", "created_at":"2018-09-11T10:55:51.167Z", "updated_at":"2018-09-11T10:55:51.167Z" } ], "name": "Шорты детские", "price": "15.0", "profile": { "address": "г.Загорск, ул. Дорожная, д.3", "created_at": "2018-01-21T20:03:18.048Z", "email": "[email protected]", "id": 2,
22
Документация RESTful API DobraTrade - версия v1.1.058
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
"name": "Магазин детской одежды", "phone_number": "(11)-111-11-11", "products_count": 0, "refs_country_id": 36, "updated_at": "2018-01-21T20:03:21.247Z", "user_id": 2 }, "profile_id": 2, "refs_product_group": { "created_at": "2018-03-11T22:17:18.577Z", "id": 9, "name": "Верхняя одежда,трикотаж", "products_count": 0, "updated_at": "2018-03-11T22:17:23.354Z" }, "refs_product_group_id": 9, "refs_unit": { "created_at": "2018-01-15T00:33:58.024Z", "full_name": "Штука", "id": 33, "numcode": "796", "short_name": "шт.", "updated_at": "2018-01-15T00:33:58.024Z" }, "refs_unit_id": 33, "updated_at": "2018-02-11T00:00:00.000Z"}
§5.2.1.3 - Создать элемент
HTTP-метод: POSTURL-действие: .../productsПараметры: См. подробно Форматно-логический контроль .Описание: Создает запись в датаспейсе текущего пользователя массива Продукты/Товары суказанными значениями параметров.Пример: .../products?profile_id=2&barcode_ean=&barcode_upc=&barcode_sku=&article_code="ML-4336"&refs_product_group_id=9&refs_unit_id=33&price=15.0&balance=-2&name="Шортыдетские"На выходе:{ "article_code": "ML-4336", "balance": "Уточнять наличие", "barcode_ean": null, "barcode_sku": null, "barcode_upc": null, "created_at": "2018-02-11T00:00:00.000Z", "description": {...}, "id": 5, "images": [], "name": "Шорты детские", "price": "15.0", "profile": { "address": "г.Загорск, ул. Дорожная, д.3", "created_at": "2018-01-21T20:03:18.048Z", "email": "[email protected]", "id": 2, "name": "Магазин детской одежды", "phone_number": "(11)-111-11-11", "products_count": 0, "refs_country_id": 36, "updated_at": "2018-01-21T20:03:21.247Z", "user_id": 2 }, "profile_id": 2,
23
Использование API в роли Publisher (Издатель) 59
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
"refs_product_group": { "created_at": "2018-03-11T22:17:18.577Z", "id": 9, "name": "Верхняя одежда,трикотаж", "products_count": 0, "updated_at": "2018-03-11T22:17:23.354Z" }, "refs_product_group_id": 9, "refs_unit": { "created_at": "2018-01-15T00:33:58.024Z", "full_name": "Штука", "id": 33, "numcode": "796", "short_name": "шт.", "updated_at": "2018-01-15T00:33:58.024Z" }, "refs_unit_id": 33, "updated_at": "2018-02-11T00:00:00.000Z"}
§5.2.1.4 - Изменить элемент
HTTP-метод: PATCHURL-действие: .../products/:idПараметры: :id - число, соответствующее значению из поля id массива. См. подробно Форматно-логический контроль .Описание: Модифицирует запись с указанным значением параметра :id в датаспейсе текущегопользователя массива Продукты/Товары.Пример: .../products/5?balance=10
§5.2.1.5 - Удалить элемент
HTTP-метод: DELETEURL-действие: .../products/:idПараметры: :id - число, соответствующее значению из поля id массива.Описание: Удаляет запись с указанным значением параметра :id в датаспейсе текущегопользователя массива Продукты/Товары. Предварительно происходит каскадное удалениесвязанного элемента массива Описание Продуктов/Товаров и связанных элементов массиваИзображения Продуктов/Товаров , если таковые имелись на момент выполнения операции.Пример: .../products/5
§5.2.2 - Работа с Описаниями Продуктов/Товаров
API-сервер предоставляет Издателям полный набор стандартных REST-действий надресурсом descriptions.
При формировании элементов массива Описания Продуктов/Товаров важно следоватьтипу отношений с массивом Продукты/Товары как "одни-к-одному". У любого Продукта/Товарадопускается отсутствие Описания Продуктов/Товаров. В случае необходимости у любогоПродукта/Товара должно быть только одно Описание Продукта/Товара.
§5.2.2.1 - Получить коллекцию элементов
HTTP-метод: GETURL-действие: .../descriptions?page=:valueПараметры: page - номер страницы коллекции. Размер страницы равен 50 элементов. Если неуказан номер страницы, то считается, что page=1.Описание: Возвращает постранично коллекцию JSON-элементов записей датаспейса текущегопользователя из массива Описания Продуктов/Товаров.Пример: .../descriptions?page=1
23
24
24
24
Документация RESTful API DobraTrade - версия v1.1.060
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
На выходе:[{ "id": 6, "product_id": 5, "refs_country_id": 36, "brutto": null, "netto": null, "description": "In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullam dictumfelis eu pede mollis pretium. Integer tincidunt. ", "dimensions": "5,6,7,8", "manufacturer": "Simple JSC", "reserved": null, "created_at": "2018-03-11T23:03:35.033Z", "updated_at": "2018-03-11T23:03:38.649Z", "refs_country": { "id": 36, "iso": "BY", "iso3": "BLR", "iso_name": "Беларусь", "name": "Беларусь", "numcode": 112, "refs_currency_id": 24, "states_required": true, "updated_at": "2018-01-15T00:34:07.242Z", "created_at": "2018-01-15T00:34:07.242Z" }}, { "id": 2, "product_id": 3, "refs_country_id": 13, "brutto": null, "netto": null, "description": "Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nullaconsequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu.", "dimensions": "4,3,2,1", "manufacturer": "XYZ JSC", "reserved": null, "created_at": "2018-01-29T01:36:16.081Z", "updated_at": "2018-01-29T01:36:21.056Z", "refs_country": { "id": 13, "iso": "AU", "iso3": "AUS", "iso_name": "Австралия", "name": "Австралия", "numcode": 36, "refs_currency_id": 8, "states_required": true, "updated_at": "2018-01-15T00:34:06.427Z", "created_at": "2018-01-15T00:34:06.427Z" }}, { "id": 1, "product_id": 1, "refs_country_id": 112, "brutto": null, "netto": null, "description": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligulaeget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nasceturridiculus mus.", "dimensions": "1,2,3,4", "manufacturer": "ABC Company", "reserved": null, "created_at": "2018-01-29T04:39:44.267Z", "updated_at": "2018-01-29T04:39:49.686Z",
Использование API в роли Publisher (Издатель) 61
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
"refs_country": { "id": 112, "iso": "JM", "iso3": "JAM", "iso_name": "Ямайка", "name": "Ямайка", "numcode": 388, "refs_currency_id": 67, "states_required": true, "updated_at": "2018-01-15T00:34:09.626Z", "created_at": "2018-01-15T00:34:09.626Z" }}, { "id": 7, "product_id": 6, "refs_country_id": 232, "brutto": null, "netto": null, "description": "Cras dapibus. Vivamus elementum semper nisi. Aenean vulputate eleifend tellus.Aenean leo ligula, porttitor eu, consequat vitae, eleifend ac, enim.", "dimensions": "8,7,6,5", "manufacturer": "JSC Brave", "reserved": null, "created_at": "2018-03-11T23:03:49.650Z", "updated_at": "2018-03-11T23:03:52.503Z", "refs_country": { "id": 232, "iso": "US", "iso3": "USA", "iso_name": "Соединенные Штаты Америки", "name": "Соединенные Штаты Америки", "numcode": 840, "refs_currency_id": 147, "states_required": true, "updated_at": "2018-01-15T00:34:13.453Z", "created_at": "2018-01-15T00:34:13.453Z" }}]
§5.2.2.2 - Получить элемент коллекции
HTTP-метод: GETURL-действие: .../descriptions/:idПараметры: :id - число, соответствующее значению из поля id массива.Описание: Возвращает JSON-элемент записи датаспейса текущего пользователя из массиваОписания Продуктов/Товаров с указанным значением параметра id.Пример: .../descriptions/1На выходе:{ "id": 1, "product_id": 1, "refs_country_id": 112, "brutto": null, "netto": null, "description": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligulaeget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nasceturridiculus mus.", "dimensions": "1,2,3,4", "manufacturer": "ABC Company", "reserved": null, "created_at": "2018-01-29T04:39:44.267Z", "updated_at": "2018-01-29T04:39:49.686Z", "refs_country": { "id": 112,
24
Документация RESTful API DobraTrade - версия v1.1.062
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
"iso": "JM", "iso3": "JAM", "iso_name": "Ямайка", "name": "Ямайка", "numcode": 388, "refs_currency_id": 67, "states_required": true, "updated_at": "2018-01-15T00:34:09.626Z", "created_at": "2018-01-15T00:34:09.626Z" }}
§5.2.2.3 - Создать элемент
HTTP-метод: POSTURL-действие: .../descriptionsПараметры: См. подробно Форматно-логический контроль .Описание: Создает запись в датаспейсе текущего пользователя массива ОписанияПродуктов/Товаров с указанными значениями параметров. Пример: .../descriptions?product_id=1&refs_country_id=112&brutto=&netto=&description="Loremipsum...mus."&dimensions="1,2,3,4"&manufacturer="ABC Company"&reserved=На выходе:{ "id": 1, "product_id": 1, "refs_country_id": 112, "brutto": null, "netto": null, "description": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligulaeget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nasceturridiculus mus.", "dimensions": "1,2,3,4", "manufacturer": "ABC Company", "reserved": null, "created_at": "2018-01-29T04:39:44.267Z", "updated_at": "2018-01-29T04:39:49.686Z", "refs_country": { "id": 112, "iso": "JM", "iso3": "JAM", "iso_name": "Ямайка", "name": "Ямайка", "numcode": 388, "refs_currency_id": 67, "states_required": true, "updated_at": "2018-01-15T00:34:09.626Z", "created_at": "2018-01-15T00:34:09.626Z" }}
§5.2.2.4 - Изменить элемент
HTTP-метод: PATCHURL-действие: .../descriptions/:idПараметры: :id - число, соответствующее значению из поля id массива. См. подробно Форматно-логический контроль .Описание: Модифицирует запись с указанным значением параметра :id в датаспейсе текущегопользователя массива Описания Продуктов/Товаров.Пример: .../descriptions/1?reserved="Your notes goes here ..."
24
24
Использование API в роли Publisher (Издатель) 63
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
§5.2.2.5 - Удалить элемент
HTTP-метод: DELETEURL-действие: .../descriptions/:idПараметры: :id - число, соответствующее значению из поля id массива.Описание: Удаляет запись с указанным значением параметра :id в датаспейсе текущегопользователя массива Описания Продуктов/Товаров.Пример: .../descriptions/1
§5.2.3 - Работа с Изображениями Продуктов/Товаров
API-сервер предоставляет Издателям полный набор стандартных REST-действий надресурсом images.
При формировании элементов массива Изображения Продуктов/Товаров важно следоватьтипу отношений с массивом Продукты/Товары как "одни-ко-многим". У любого Продукта/Товарадопускается отсутствие Изображений Продуктов/Товаров. В случае необходимости у любогоПродукта/Товара может быть одно и более Изображение Продукта/Товара.
§5.2.3.1 - Получить коллекцию элементов
HTTP-метод: GETURL-действие: .../images?page=:valueПараметры: page - номер страницы коллекции. Размер страницы равен 50 элементов. Если неуказан номер страницы, то считается, что page=1.Описание: Возвращает постранично коллекцию JSON-элементов записей датаспейса текущегопользователя из массива Изображения Продуктов/Товаров.Пример: .../images?page=1На выходе:[ { "id":2, "product_id":5, "image_path":"https://....jpg", "created_at":"2018-06-21T11:11:58.161Z", "updated_at":"2018-08-25T13:18:05.557Z" }, { "id":3, "product_id":5, "image_path":"https://....jpg", "created_at":"2018-06-21T11:14:23.708Z", "updated_at":"2018-08-25T13:18:05.590Z" }, { "id":3, "product_id":5, "image_path":"https://....jpg", "created_at":"2018-09-11T10:55:51.167Z", "updated_at":"2018-09-11T10:55:51.167Z" }]
§5.2.3.2 - Получить элемент коллекции
HTTP-метод: GETURL-действие: .../images/:idПараметры: :id - число, соответствующее значению из поля id массива.Описание: Возвращает JSON-элемент записи датаспейса текущего пользователя из массиваИзображения Продуктов/Товаров с указанным значением параметра id.Пример: .../images/1На выходе:
24
24
Документация RESTful API DobraTrade - версия v1.1.064
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
{ "id":1, "product_id":1, "image_path":"https://....jpg", "created_at":"2018-06-21T11:11:58.161Z", "updated_at":"2018-08-25T13:18:05.557Z"}
§5.2.3.3 - Создать элемент
HTTP-метод: POSTURL-действие: .../imagesПараметры: См. подробно Форматно-логический контроль .Описание: Создает запись в датаспейсе текущего пользователя массива ИзображенияПродуктов/Товаров с указанными значениями параметров. Пример: .../images?product_id=1&image_path="https://....jpg"На выходе:{ "id":1, "product_id":1, "image_path":"https://....jpg", "created_at":"2018-06-21T11:11:58.161Z", "updated_at":"2018-08-25T13:18:05.557Z"}
§5.2.3.4 - Изменить элемент
HTTP-метод: PATCHURL-действие: .../images/:idПараметры: :id - число, соответствующее значению из поля id массива. См. подробно Форматно-логический контроль .Описание: Модифицирует запись с указанным значением параметра :id в датаспейсе текущегопользователя массива Изображения Продуктов/Товаров.Пример: .../images/1?image_path="https://....jpg"
§5.2.3.5 - Удалить элемент
HTTP-метод: DELETEURL-действие: .../images/:idПараметры: :id - число, соответствующее значению из поля id массива.Описание: Удаляет запись с указанным значением параметра :id в датаспейсе текущегопользователя массива Изображения Продуктов/Товаров.Пример: .../images/1
25
25
Раздел
VI
Последние изменения: 18.10.2018
История изменений
Документация RESTful API DobraTrade - версия v1.1.066
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]
РАЗДЕЛ 6: История изменений
Структура нумерации релизов API-сервера информационной системы DobraTrade - X.Y.Z,где:
· X - основная версия. Присваивается релизу, для обозначения важных свойств системы и еепринципиальных возможностей (новые ресурсы и/или URL-действия, в том числевызванные изменениями структур баз данных; новые функции обработки данных и т.д.);
· Y - вспомогательная версия. Обозначает наличие незначительных изменений в свойствахи функциональном поведении системы, улучшающих способы реализации существующихзадач;
· Z - версия сборки. Обозначает изменения, связанные с рефакторингом и оптимизациейкода, устранением уязвимостей и другими несущественными изменениями, а такжеошибки и дефекты в работе программного кода.
№ релиза Период введения Перечень изменений1.1.0 октябрь 2018 г. 1. Новый тип информационного ресурса - Изображения
Продуктов/Товаров (.../images);2. При создании/изменении экземпляров информационнрых
ресурсов в системе автоматически генерируется описательныйтекст для "дружественной ссылки" вместо числовых :id в URLресурса. В связи с этим введена обязательность заполненияполей, на основе которых формируется slug-атрибут дляиспользования в таких ссылках. Например, для ряда ресурсовтаким атрибутом является наименование. Следовательно,введена обязательность его наличия при модификацияхсоответствующих массивов информационной базы системы.На уровне API сохраняется возможность применять числовые:id для идентификации ресурсов. "Дружественные ссылки"отображаются при работе через web-интерфейс на сайтесистемы DobraTrade;
3. Для ресурса Продукты/Товары введен контроль науникальность кода артикула article_code в пределах профиляprofile_id, т.е. нельзя среди записей в базе иметь несколькоодинаковых артикулов для одного и того же торговогообъекта.
4. Для ресурса Бизнес-профили добавлены новые атрибуты:logo_path, cert_path.
5. Для информационого ресурса Профили (.../profiles) из APIудалено действие purge.
67
© 2020 ООО "ДОБРА", УНП 192701469, тел. +375-29-750-08-86, email: [email protected]