Документация RESTful API DobraTrade - версия v1.1ООО "Добра" не...

© 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


Никакая часть данного руководства не может быть воспроизведена третьими лицами вкаком-либо виде без письменного разрешения ООО "Добра".ООО "Добра" не намерена нести ответственность перед другими лицами в случаепричинения им прямых, косвенных убытков, упущеной выгоды и других форс-мажорныхобстоятельств, возникших прямо или косвенно вследствие ненадлежащегоиспользования данного руководства.Другие лица, приняв к сведению изложенную в данном руководстве информацию,обязуются использовать ее исключительно в целях, указанных в данном руководстве.



Оглавление

Раздел I Основные положения 8

................................................................................................................................... 91 Общая характеристика

................................................................................................................................... 92 Подключение, установка соединения

................................................................................................................................... 113 Роли доступа

................................................................................................................................... 114 Отправка запросов

................................................................................................................................... 125 Статусы операций и обработка ошибок

................................................................................................................................... 146 Форматно-логический контроль

................................................................................................................................... 147 Служебные поля JSON-элементов

Раздел II Описание информационной схемы 16

................................................................................................................................... 171 Справочники

.......................................................................................................................................................... 17Справочник Товарные группы

......................................................................................................................................................... 17Назначение

......................................................................................................................................................... 17Структура JSON-элемента

.......................................................................................................................................................... 18Справочник Единицы измерений

......................................................................................................................................................... 18Назначение


.......................................................................................................................................................... 18Справочник Валюты

......................................................................................................................................................... 18Назначение


.......................................................................................................................................................... 18Справочник Страны

......................................................................................................................................................... 18Назначение


.......................................................................................................................................................... 19Справочник Регионы

......................................................................................................................................................... 19Назначение


.......................................................................................................................................................... 19Справочник Категории торговых объектов

......................................................................................................................................................... 19Назначение


................................................................................................................................... 202 Информационная группа Торговые объекты

.......................................................................................................................................................... 20Массив Пользователи

......................................................................................................................................................... 20Назначение


......................................................................................................................................................... 20Форматно-логический контроль

.......................................................................................................................................................... 20Массив Профили торговых объектов

......................................................................................................................................................... 21Назначение



.......................................................................................................................................................... 21Массив Бизнес-профили

......................................................................................................................................................... 21Назначение



................................................................................................................................... 223 Информационная группа Товары

5Оглавление

5


.......................................................................................................................................................... 22Массив Продукты/Товары

......................................................................................................................................................... 22Назначение



.......................................................................................................................................................... 24Массив Описания Продуктов/Товаров

......................................................................................................................................................... 24Назначение



.......................................................................................................................................................... 24Массив Изображения Продуктов/Товаров

......................................................................................................................................................... 24Назначение



Раздел III Работа со справочниками в API 26

................................................................................................................................... 271 Справочник Товарные группы

.......................................................................................................................................................... 27Получить коллекцию элементов

.......................................................................................................................................................... 27Получить элемент коллекции

................................................................................................................................... 282 Справочник Единицы измерений



................................................................................................................................... 293 Справочник Валюты



................................................................................................................................... 294 Справочник Страны



................................................................................................................................... 315 Справочник Регионы



................................................................................................................................... 326 Справочник Категории торговых объектов



Раздел IV Использование API в роли Subscriber(Подписчик) 34


.......................................................................................................................................................... 35Работа с Профилями

......................................................................................................................................................... 35Получить коллекцию элементов

......................................................................................................................................................... 36Получить элемент коллекции

.......................................................................................................................................................... 37Работа с Бизнес-Профилями




.......................................................................................................................................................... 38Работа с Продуктами/Описаниями/Изображениями



Раздел V Использование API в роли Publisher(Издатель) 45




.......................................................................................................................................................... 46Работа с Профилями



......................................................................................................................................................... 48Создать элемент

......................................................................................................................................................... 49Изменить элемент

......................................................................................................................................................... 49Удалить элемент

......................................................................................................................................................... 49Получить коллекцию Продуктов/Товаров профиля

......................................................................................................................................................... 50Получить Продукт/Товар профиля по атрибуту article_code или sku

......................................................................................................................................................... 50Получить Профили по атрибуту email

.......................................................................................................................................................... 51Работа с Бизнес-Профилями



......................................................................................................................................................... 53Создать элемент


......................................................................................................................................................... 53Удалить элемент


.......................................................................................................................................................... 54Работа с Продуктами/Товарами



......................................................................................................................................................... 58Создать элемент


......................................................................................................................................................... 59Удалить элемент

.......................................................................................................................................................... 59Работа с Описаниями Продуктов/Товаров



......................................................................................................................................................... 62Создать элемент


......................................................................................................................................................... 63Удалить элемент

.......................................................................................................................................................... 63Работа с Изображениями Продуктов/Товаров



......................................................................................................................................................... 64Создать элемент


......................................................................................................................................................... 64Удалить элемент

Раздел VI История изменений 65

Раздел

I

Последние изменения: 02.04.2019

Основные положения

Основные положения 9


РАЗДЕЛ 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

http://iog.by/users/sign_up



вспомогательных операций, таких как сброс забытого пароля и создание нового. Такжезапрашивается ваше описательное наименование как клиента системы и создаваемыйпароль с подтверждением;

· Связаться по телефону (указан на сайте) со службой технической поддержки, согласоватьсвои данные и получить активацию в одной из запрошенных вами ролей (Подписчик илиИздатель). См. подробнее о ролях раздел Режимы доступа ;

· После успешной регистрации, появляется возможность зайти в Личный кабинет, гденеобходимо заполнить дополнительную информацию по аккаунту. Если вырегистрируетесь как Издатель, то также необходимо составить список профилей(паспортов) торговых объектов, по которым ваш 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



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



Параметр Значение ОписаниеЕсли в будущих релизах вам потребуетсяопределённая версия действия 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



Код 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"



Код 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 Момент времени физического создания записи в массиве.



Идентификатор поля Описание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.

https://time.is/ru/UTC

Раздел

II


Описание информационнойсхемы

Описание информационной схемы 17


РАЗДЕЛ 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



§2.1.2 - Справочник Единицы измерений

Доступ к справочнику Единицы измерений на уровне API производится через URL-ресурсвида:

.../refs/units


Справочник Единицы измерений классифицирует единицы измерений для данных оналичии товаров в натуральных измерителях. Каждая товарная позиция хранит количествоактуального остатка на конкретном торговом объекте.


Структура JSON-элемента в теле http-отклика для справочника Единицы измеренийсодержит следующие информационные поля:

Идентификатор поля Описаниеnumcode Числовой код по ОКЕИ.full_name Полная форма наименования.short_name Краткая форма наименования.

§2.1.3 - Справочник Валюты

Доступ к справочнику Валюты на уровне API производится через URL-ресурс вида:.../refs/currencies


Справочник Валюты классифицирует валюты в соответствии с международным стандартомISO 4217 (ИСО 4217). Для каждой валюты указывается трёхбуквенное алфавитное и трёхзначноецифровое представление. Справочник используется при формировании мультивалютных "витрин"для торговых объектов и "потребительских корзин".


Структура JSON-элемента в теле http-отклика для справочника Валюты содержитследующие информационные поля:

Идентификатор поля Описаниеnumcode Трёхзначное цифровое представление.abbr Трёхбуквенное алфавитное представление.name Полная форма наименования.

§2.1.4 - Справочник Страны

Доступ к справочнику Страны на уровне API производится через URL-ресурс вида:.../refs/countries


Справочник Страны классифицирует страны в соответствии с международным стандартомISO 3166 (ИСО 3166). Помимо наименования, для каждой страны указаны двух- и трехзначныйсимвольные коды, а также числовой код. Справочник используется в механизме геолокализацииместоположения торговых объектов совместно со справочником Справочник "Регионы" .19




Структура 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


Справочник Регионы классифицирует регионы стран в соответствии с международнымстандартом ISO 3166 (ИСО 3166). Помимо наименования, для каждого региона указан кодаббревиатуры. Справочник используется в механизме геолокализации местоположения торговыхобъектов совместно со справочником Справочник "Страны" .


Структура JSON-элемента в теле http-отклика для справочника Регионы содержитследующие информационные поля:

Идентификатор поля Описаниеname Наименование.abbr Алфавитное представление региона, аббревиатура.refs_country Корень для связанного JSON-элемента из Справочника Страны .refs_country_id Код id для ссылки на страну в Справочнике Страны .

§2.1.6 - Справочник Категории торговых объектов

Доступ к справочнику Категории торговых объектов на уровне API производится черезURL-ресурс вида:

.../refs/retail_categories


Справочник Категории торговых объектов классифицирует типы торговых объектов,площадок, на которых представлены товары в информационной базе данных DobraTrade. С егопомощью можно образовывать направление аналитики, описывающее распределение товаров повидам, формам и способам торговли.


Структура JSON-элемента в теле http-отклика из справочника Категории торговыхобъектов содержит следующие информационные поля:

Идентификатор поля Описаниеname Наименование категории.

18

18

18

18

18



§2.2 - Информационная группа Торговые объекты

В состав информационной группы Торговые объекты входят следующие элементы:· Массив Пользователи ;· Массив Профили торговых объектов ;· Массив Бизнес-профили .

§2.2.1 - Массив Пользователи

Доступ к массиву Пользователи на уровне API отсутствует за исключением единственногоPOST-метода, предназначенного для аутентификации /auth/login и описанного в Подключение,установка соединения .

С помощью режима Личного кабинета в web-приложении пользователи могут обслуживатьсвои личные аккаунты. Соответственно, при регистрации создается элемент массива Пользователь.После успешной аутентификации на сайте в Личном кабинете пользователь может редактироватьнастройки своего аккаунта, видеть статистику по его использованию, а также осуществлять инуюактивность, предусмотреную соответствующей ролью. При необходимости он там же может егоудалить, в результате чего удаляется вся связанная с аккаунтом информация (профили, товары,сохраненные запросы, товарные корзины и т.д.).

Сразу после регистрации пользователю присваивается первоначальная роль User. Онапредназначается для обычных посетителей, которые выполняют поиск товаров на сайте, и являетсясвободно-доступной.

Чтобы иметь доступ к коммерческим сервисам, предусмотренными ролями Издатель иПодписчик, необходимо обратиться с запросом в службу техподдержки, которая проведетнеобходимую верификацию созданного аккаунта. В результате он будет "продвинут" донеобходимой роли в соответствии с завкой владельца аккаунта.


Массив Пользователи содержит сведения об аккаунтах, ассоциированных с владельцамиторговых объектов (только для Издателей). В свою очередь, один пользователь-Издатель можетиметь один и более связанных с ним торговых объектов (Профили). Для пользователей в ролиПодписчик не предусмотрено наличие профилей и других данных в информационных массивахсистемы DobraTrade.


Структура 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




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


Структура JSON-элемента в теле http-отклика для массива Профили торговых объектовсодержит следующие информационные поля:

Идентификатор поля Описаниеaddress Адрес нахождения торгового объекта.latitude Широта для координат геолокации торгового объекта.longitude Долгота для координат геолокации торгового объекта.email Контактный email.name Наименование торгового объекта.phone_number Контактный телефон.products_count Количество товарных позиций, размещенных к продаже на торговом

объекте.refs_country Корень для связанного JSON-элемента из Справочника Страны .refs_country_id Код id для ссылки на страну в Справочнике Страны .user Корень для связанного JSON-элемента из Массива Пользователи .user_id Код id для ссылки на элемент из Массива Пользователи .


В отношении массива Профили торговых объектов при выполнении модифицирующихhttp-действий типа POST/DELETE/PATCH предусмотрены следующие процедуры форматно-логического контроля:

Параметр Тип Контрольaddress Строковый. Обязательный.email Строковый. Обязательный. Формат e-mail.name Строковый. Обязательный.phone_number Строковый.refs_country_id Целочисленный. Обязательный.

§2.2.3 - Массив Бизнес-профили

Доступ к массиву Бизнес-профили на уровне API производится через URL-ресурс вида:.../business_profiles


Массив Бизнес-профили содержит дополнительные сведения о торговом объекте, которыеобразуют его бизнес-профиль.


Структура JSON-элемента в теле http-отклика для массива Бизнес-профили содержитследующие информационные поля:

Идентификатор поля Описаниеoperation_hours Описание режима работы торгового объекта.logo_path URL-ссылка на изображение логотипа торгового объекта.cert_path URL-ссылка на изображение удостоверяющего сертификата

(свидетельства) для торгового объекта.

29

29

20 20

20



Идентификатор поля Описаниеprofile Корень для связанного JSON-элемента из массиве Профилей .profile_id Код id для ссылки на элемент в массиве Профилей .refs_retail_categories Ссылка на коллекцию связанных JSON-элементов из массива

Справочник Категории торговых объектов .


В отношении массива Бизнес-профили при выполнении модифицирующих 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


Массив Продукты/Товары содержит ассортиментый перечень товаров на торговыхобъектах с указанием данных о наличии товара на объекте в натуральных единицах измерений.Опционально может указываться цена позиции в базовой валюте пользователя и другая полезнаяинформация (товарная группа, артикул, баркоды и т.д.).


Структура JSON-элемента в теле http-отклика для массива Продукты/Товары содержитследующие информационные поля:

Идентификатор поля Описаниеarticle_code Код артикула продукта. Служит для внутри-системной идентификации

цены товара, в том числе при партионном учете.balance Величина остатка по товарной позиции продукта на торговом объекте

(для указанного profile_id). Представляется в виде текста с содержимым вчисловой форме. Также возможные варианты хранения в этом атрибутеданных в виде поясняющего текста:· Уточнять;· Уточнять наличие;· Всегда в наличии;· Нет в наличии.

barcode_ean Европейский код артикула для товара, присвоенный его производителем.

35

35

19

19

22

24

24



Идентификатор поля Описание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 для ссылки на профиль в массиве Единицы измерений .


В отношении массива Продукты/Товары при выполнении модифицирующих 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



§2.3.2 - Массив Описания Продуктов/Товаров

Доступ к массиву Описания Продуктов/Товаров на уровне API производится через URL-ресурс вида:

.../descriptions


Массив Описания Продуктов/Товаров содержит по каждому товару опциональную запись сдополнительными данными о его потребительских свойствах.


Структура JSON-элемента в теле http-отклика для массива Описания Продуктов/Товаровсодержит следующие информационные поля:

Идентификатор поля Описаниеbrutto Данные о массе брутто.description Текст с подробным описанием характеристик товара.dimensions Данные о размерных признаках товара.manufacturer Сведения о производителе.netto Данные о массе нетто.refs_country_id Код id для ссылки на страну в массиве Справочник Страны . Страна

происхождения товара.product_id Код id для ссылки на товар в массиве Продукты/Товары .reserved Поле для прочих отметок.


В отношении массива Описания Продуктов/Товаров при выполнении модифицирующихhttp-действий типа POST/DELETE/PATCH предусмотрены следующие процедуры форматно-логического контроля:

Параметр Тип Контрольbrutto Строковый.description Строковый. Обязательный.dimensions Строковый.manufacturer Строковый.netto Строковый.refs_country_id Целочисленный. Обязательный.product_id Целочисленный. Обязательный.reserved Строковый.

§2.3.3 - Массив Изображения Продуктов/Товаров

Доступ к массиву Изображения Продуктов/Товаров на уровне API производится черезURL-ресурс вида:

.../images


Массив Изображения Продуктов/Товаров содержит по каждому товару коллекцию записейсо статическими URL-ссылками на его изображения.


Структура JSON-элемента в теле http-отклика для массива ИзображенияПродуктов/Товаров содержит следующие информационные поля:

18

22



Идентификатор поля Описаниеimage_path URL-ссылка на изображение товара.product_id Код id для ссылки на товар в массиве Продукты/Товары .


В отношении массива Изображения Продуктов/Товаров при выполнениимодифицирующих http-действий типа POST/DELETE/PATCH предусмотрены следующие процедурыформатно-логического контроля:

Параметр Тип Контрольimage_path Строковый. Обязательный. Формат URL-ссылки.product_id Целочисленный. Обязательный.

22

Раздел

III


Работа со справочниками вAPI

Работа со справочниками в API 27


РАЗДЕЛ 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



"id": 1, "name": "Товары для дома: сантехника", "products_count": 0, "updated_at": "2018-01-17T20:07:30.157Z"}

§3.2 - Справочник Единицы измерений

Рассмотрим какие действия доступны на уровне API для соответствующегоресурса /refs/units.


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" },...]


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



}

§3.3 - Справочник Валюты

Рассмотрим какие действия доступны на уровне API для соответствующегоресурса /refs/currencies.


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" }]


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.


HTTP-метод: GETURL-действие: .../refs/countriesОписание: Возвращает коллекцию JSON-элементов для всех записей справочника Страны.

18

18

19



На выходе: [... { "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" }]




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.


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



}, "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" }, ...]


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




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" }]


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


Использование API в ролиSubscriber (Подписчик)

Использование API в роли Subscriber (Подписчик) 35


РАЗДЕЛ 4: Использование API в роли Subscriber(Подписчик)

Роль Подписчик (Subsriber) характеризуется тем, что в соответствии с политиками еенастройки, аутентифицированные пользователи в данной роли имеют доступ к действиям,позволяющим "только читать" данные из информационной базы DobraTrade, опубликованныедругими пользователями в роли Издатель (Publisher). При попытках произвести модифицирющеедействие API-сервер формирует отказ с кодом завершения 403 Forbiden.


Рассмотрим 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



{ "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



"user": { "id": 2, "name": "Торговая сеть \"Оптима\"" }, "user_id": 2}

§4.1.2 - Работа с Бизнес-Профилями

При сериализации элемента ресурса business_profiles в нём дополнительно указываютсясвязанные JSON-элементы ресурсов profiles и refs_retail_categories.


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



"user_id": 2 }, "profile_id": 1, "refs_retail_categories": [ { "id": 4, "name": "Павильон торгового центра" } ], "updated_at": "2018-03-11T15:23:40.323Z" }...]


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"}


Рассмотрим API-методы для получения Подписчиками данных о товарах более подробно.

§4.2.1 - Работа с Продуктами/Описаниями/Изображениями

При сериализации элемента ресурса products в нём дополнительно указываются связанныеJSON-элементы ресурсов descriptions, images, profiles, refs_product_groups и refs_units.

21




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



"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" } ],



"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" },



{ "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":[



{ "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" }]


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



"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


Использование API в ролиPublisher (Издатель)



РАЗДЕЛ 5: Использование API в роли Publisher (Издатель)

Роль Издатель (Publisher) характеризуется тем, что в соответствии с политиками еенастройки, аутентифицированные пользователи в данной роли имеют доступ к методам API,реализующим полный набор CRUD-операций, но только в пределах своего "пространстваданных" (далее - датаспейс; dataspace) в информационной базе DobraTrade.

Каждый датаспейс образуется в контексте конкретного пользовательского аккаунтаИздателя и предоставляет все ассоциированные с ним данные. При попытках произвести чтениеили модифицирющее действие по отношению к данным в других датаспейсах API-сервер формируетотказ с кодом завершения 403 Forbidden.


Перед тем как формировать содержимое массивов данной группы, следует рассмотретьвозможность использования режима Личного кабинета и после регистрации/аутентификациивручную ввести в нем данные о профилях торговых объектов. Если предполагаемый объеминформации значителен, то можно применить API для разработки программы обмена данными и сее помощью выполнить начальную загрузку профилей с уровнем доступа аккаунта как Издатель(Publisher). Дальнейшую актуализацию в виде незначительных правок можно производитьнепосредствено в Личном кабинете.

Инфогруппа Торговые объекты описывает торговые объекты, относящиеся к аккаунтутекущего пользователя. К данной группе принадлежат следующие массивы, требующие наполненияв указанном порядке:

· Массив Профили торговых объектов - каждый элемент описывает торговый объект, покоторому текущий пользователь с правами Издателя может разместить в своемдатаспейсе актуальные сведения о наличии товаров на объекте;

· Массив Бизнес-профили - некоторые торговые объекты при необходимости могутсодержать дополнительные сведения, связанные с осуществляемой торговойдеятельностью. Они включают такие сведения, как часы и режимы работы,геокоординаты расположения розничной точки, виды и способы торговой деятельностии др. .

Рассмотрим API-методы для публикации Издателями данных о торговых объектах:· Работа с Профилями ;· Работа с Бизнес-Профилями .

§5.1.1 - Работа с Профилями

API-сервер предоставляет Издателям полный набор стандартных REST-действий надресурсом profiles.

Помимо стандартных REST-действий ресурс profiles предоставляет Издателям рядметодов, обеспечивающих дополнительный контроль над процессом загрузки данных винформационную базу DobraTrade.


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


"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 }]


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", "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



"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



"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



"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.

При формировании элементов массива Бизнес-Профилей важно следовать типу отношенийс массивом Профили как "одни-к-одному". У любого Профиля допускается отсутствие Бизнес-Профиля. В случае необходимости у любого Профиля должен быть только один Бизнес-Профиль.


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



}, { "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" }]


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



"id": 4, "name": "Павильон торгового центра" } ], "updated_at": "2018-03-11T15:23:40.323Z"}


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"}


HTTP-метод: PATCHURL-действие: .../business_profiles/:idПараметры: :id - число, соответствующее значению из поля id массива. См. подробно Форматно-логический контроль .Описание: Модифицирует запись с указанным значением параметра :id в датаспейсе текущегопользователя массива Бизнес-Профилей.Пример: .../business_profiles/2?operation_hours="9:00-17:00, выходной - воскресенье"


HTTP-метод: DELETEURL-действие: .../business_profiles/:id

22

22



Параметры: :id - число, соответствующее значению из поля id массива.Описание: Удаляет запись с указанным значением параметра :id в датаспейсе текущегопользователя массива Бизнес-Профилей. Предварительно происходит каскадное удаление привязокк элементам массива Категории торговых объектов .Пример: .../business_profiles/2


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

· Массив Продукты/Товары . Содержит ассортиментый перечень товаров по каждому изторговых объектов с указанием данных о наличии товара на объекте в натуральныхединицах измерений. Опционально может указываться цена позиции в базовой валютепользователя и другая идентифицирующая информация (товарная группа, артикул,баркоды и т.д.);

· Массив Описание Продуктов/Товаров . Опционально при необходимости каждаятоварная позиция может снабжаться записью с данными, которые раскрываютдополнительные сведения о потребительских свойствах товара (детальное описание,массо-габариты, производитель, страна происхождения).

Рассмотрим API-методы для публикации Издателями данных о продуктах/товарах:· Работа с Продуктами/Товарами ;· Работа с Описаниями Продуктов/Товаров ;· Работа с Изображениями Продуктов/Товаров .

§5.2.1 - Работа с Продуктами/Товарами

API-сервер предоставляет Издателям полный набор стандартных REST-действий надресурсом products.


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



}, "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,



"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,



"updated_at": "2018-01-21T20:09:31.223Z" } ]


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



"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"}


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



"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"}


HTTP-метод: PATCHURL-действие: .../products/:idПараметры: :id - число, соответствующее значению из поля id массива. См. подробно Форматно-логический контроль .Описание: Модифицирует запись с указанным значением параметра :id в датаспейсе текущегопользователя массива Продукты/Товары.Пример: .../products/5?balance=10


HTTP-метод: DELETEURL-действие: .../products/:idПараметры: :id - число, соответствующее значению из поля id массива.Описание: Удаляет запись с указанным значением параметра :id в датаспейсе текущегопользователя массива Продукты/Товары. Предварительно происходит каскадное удалениесвязанного элемента массива Описание Продуктов/Товаров и связанных элементов массиваИзображения Продуктов/Товаров , если таковые имелись на момент выполнения операции.Пример: .../products/5

§5.2.2 - Работа с Описаниями Продуктов/Товаров

API-сервер предоставляет Издателям полный набор стандартных REST-действий надресурсом descriptions.

При формировании элементов массива Описания Продуктов/Товаров важно следоватьтипу отношений с массивом Продукты/Товары как "одни-к-одному". У любого Продукта/Товарадопускается отсутствие Описания Продуктов/Товаров. В случае необходимости у любогоПродукта/Товара должно быть только одно Описание Продукта/Товара.


HTTP-метод: GETURL-действие: .../descriptions?page=:valueПараметры: page - номер страницы коллекции. Размер страницы равен 50 элементов. Если неуказан номер страницы, то считается, что page=1.Описание: Возвращает постранично коллекцию JSON-элементов записей датаспейса текущегопользователя из массива Описания Продуктов/Товаров.Пример: .../descriptions?page=1

23

24

24

24



На выходе:[{ "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",



"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" }}]


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



"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" }}


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" }}


HTTP-метод: PATCHURL-действие: .../descriptions/:idПараметры: :id - число, соответствующее значению из поля id массива. См. подробно Форматно-логический контроль .Описание: Модифицирует запись с указанным значением параметра :id в датаспейсе текущегопользователя массива Описания Продуктов/Товаров.Пример: .../descriptions/1?reserved="Your notes goes here ..."

24

24




HTTP-метод: DELETEURL-действие: .../descriptions/:idПараметры: :id - число, соответствующее значению из поля id массива.Описание: Удаляет запись с указанным значением параметра :id в датаспейсе текущегопользователя массива Описания Продуктов/Товаров.Пример: .../descriptions/1

§5.2.3 - Работа с Изображениями Продуктов/Товаров

API-сервер предоставляет Издателям полный набор стандартных REST-действий надресурсом images.

При формировании элементов массива Изображения Продуктов/Товаров важно следоватьтипу отношений с массивом Продукты/Товары как "одни-ко-многим". У любого Продукта/Товарадопускается отсутствие Изображений Продуктов/Товаров. В случае необходимости у любогоПродукта/Товара может быть одно и более Изображение Продукта/Товара.


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" }]


HTTP-метод: GETURL-действие: .../images/:idПараметры: :id - число, соответствующее значению из поля id массива.Описание: Возвращает JSON-элемент записи датаспейса текущего пользователя из массиваИзображения Продуктов/Товаров с указанным значением параметра id.Пример: .../images/1На выходе:

24

24



{ "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"}


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"}


HTTP-метод: PATCHURL-действие: .../images/:idПараметры: :id - число, соответствующее значению из поля id массива. См. подробно Форматно-логический контроль .Описание: Модифицирует запись с указанным значением параметра :id в датаспейсе текущегопользователя массива Изображения Продуктов/Товаров.Пример: .../images/1?image_path="https://....jpg"


HTTP-метод: DELETEURL-действие: .../images/:idПараметры: :id - число, соответствующее значению из поля id массива.Описание: Удаляет запись с указанным значением параметра :id в датаспейсе текущегопользователя массива Изображения Продуктов/Товаров.Пример: .../images/1

25

25

Раздел

VI


История изменений



РАЗДЕЛ 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


Документация RESTful API DobraTrade - версия v1.1ООО "Добра" не...

Documents

Transcript of Документация RESTful API DobraTrade - версия v1.1ООО "Добра" не...