Краткое описание работы API

Список актуальных сервисов

Вызов сервисов

Параметры вызова

Примеры вызова

Товары, основное (данные карточки, цены, остатки)
    ​​​​​​Сервис получения списка товарных групп («GetCommodityGroupsList»)
    Сервис получения иерархии категорий товаров («ProductsCategories») 
    Сервис получения списка номенклатуры («GetProductList»)

Новая структура данных выгрузки (после 20.07.2020), которые отдаются сервисом (ответы сервиса)

Конфигурация с обработкой для демонстрации работы с API

Список актуальных сервисов

 к содержанию

1. На данный момент поддерживается 17 сервисов, а именно:

• Сервис получения списка товарных групп («GetCommodityGroupsList»)
• Сервис получения иерархии категорий товаров («ProductsCategories») 
• Сервис получения списка номенклатуры («GetProductList»)
• Сервис получения данных карточки номенклатуры («GetProductInfo»)
• Сервис получения списка ассоциированных товаров по указанной номенклатуре(«ProductAssociations») 
• Сервис получения списка складов («GetWarehousesList»)
• Сервис получения и цен и остатков («ProductsPriceAndRest»)
• Сервис выгрузки цен и остатков по полученному (от клиента) целевому списку номенклатуры («PostProductsListPricesAndRests»)
• Сервис получения списка файлов конкретной позиции номенклатуры (для получения по API) («GetProductDataFilesList»)
• Сервис получения одного файла номенклатуры («GetProductDataFile»)
• Сервис получения основного изображения номенклатуры («GetProductMainImage»)
• Сервис создания Счета покупателя («PostCreateNewCustomerOrder»)
• Сервис получения списка документов (Счетов покупателей) («GetBuyerOrdersList»)
• Сервис получения списка неотгруженных Счетов покупателя («GetBuyerOrdersListUnshipped»)
• Сервис получения данных одного документа (Счета покупателя) («GetBuyerOrderInfo»)
• Сервис получения основной печатной формы документа Счет покупателя («GetBuyerOrderMainPrintedForm») (счет покупателя в формате PDF)
• Сервис получения списка доступных договоров («GetCustomerContracts»)

Вызов сервисов

 к содержанию

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

• Общая часть пути к Сервисам

• Имя конкретного Сервиса

• Параметры Сервиса

Данные части объединяются в строку вида: Общая часть пути к Сервисам/Имя конкретного Сервиса/Параметры Сервиса

ПРИМЕЧАНИЕ: для интерактивного вызова данных Сервисов не рекомендуется использовать браузер «Internet Explorer». Рекомендуются, например, «Google Chrome» или «Mozilla Firefox».

3. Общая часть пути к Сервисам представляет из себя следующую константную строку:

4. Имена Сервисов:

• Сервис получения списка товарных групп имеет следующее имя: /Products/GetCommodityGroupsList
• Сервис получения иерархии категорий товаров имеет следующее имя: /Products/ProductsCategories
• Сервис получения списка номенклатуры имеет следующее имя: /Products/GetProductList
• Сервис получения данных карточки номенклатуры имеет следующее имя: /Products/GetProductInfo
• Сервис получения списка ассоциированных товаров по указанной номенклатуре имеет следующее имя: /Products/ProductAssociations
• Сервис получения списка складов имеет следующее имя: /Products/GetWarehousesList
• Сервис получения и цен и остатков имеет следующее имя: /Products/ProductsPriceAndRest
• Сервис выгрузки цен и остатков по полученному (от клиента) целевому списку номенклатуры имеет следующее имя: /Products/PostProductsListPricesAndRests
• Сервис получения списка файлов номенклатуры (списка ссылок для получения по API) имеет следующее имя: /Products/GetProductDataFilesList
• Сервис получения одного файла номенклатуры имеет следующее имя: /Products/GetProductDataFile
• Сервис получения основного изображения номенклатуры имеет следующее имя: /Products/GetProductMainImage
• Сервис создания счета покупателя имеет следующее имя: /BuyersOrders/PostCreateNewCustomerOrder
• Сервис получения списка документов (счетов покупателей) имеет следующее имя: /BuyersOrders/GetBuyerOrdersList
• Сервис получения списка неотгруженных счетов покупателя имеет следующее имя: /BuyersOrders/GetBuyerOrdersListUnshipped
• Сервис получения данных одного документа (счета покупателя) имеет следующее имя: /BuyersOrders/GetBuyerOrderInfo
• Сервис получения основной печатной формы документа Счет покупателя имеет следующее имя: /BuyersOrders/GetBuyerOrderMainPrintedForm
• Сервис получения списка доступных договоров имеет следующее имя: /Customers/GetCustomerContracts

Параметры вызова

к содержанию 

5. Параметры Сервисов

• в общем случае существуют обязательные (один или несколько) и необязательные (один или несколько) параметры;

• обязательные параметры вставляются в строку адреса после имени сервиса через слэш («/»), примеры см. ниже;

• необязательные параметры вставляются в строку адреса после обязательных параметров через символ знака вопроса («?») см. пример ниже;

• как следует из названия, необязательные параметры могут не указываться в строке вызова, а при указании обеспечивают дополнительную функциональность (чаще всего какой-то дополнительный фильтр, например, по Договору или части артикула);

• для правильного указания необязательного параметра требуется указывать и его имя: ИмяНеобязательногоПараметра1=ЗначениеПараметра1;

ПРИМЕЧАНИЕ: одним из самых часто встречающихся обязательных параметров является так называемый «Ключ» (Контактного лица, Контрагента, Договора); Ключ контактного лица обязателен во всех Сервисах, т.к. по нему происходит идентификация пользователя;

Примеры вызова

к содержанию 

6. Вызовы Сервисов, их варианты и параметры

            Сервис получения списка номенклатуры («GetProductList»)

Целью данного сервиса является формирование и выгрузка списка товаров (с их кодами), которыми интересуется клиент; 

Т.е. по каждой номенклатуре сервис отдаёт минимальное количество полей (артикул, код, наименование, а так же код и наименование единицы измерения), основным из которых является код;

Код используется только в сервисе получения данных карточки номенклатуры «GetProductInfo» (см. описание ниже) и в некоторых других сервисах для составления узкого (целевого) списка номенклатурных позиций, например:

-в сервисе создания Счета покупателя («PostCreateNewCustomerOrder»), для описания массива заказываемой номенклатуры (см. описание ниже);

-в сервисе выгрузки цен и остатков по полученному (от клиента) списку номенклатуры «PostProductsListPricesAndRests» (см. описание ниже);

ВАЖНО: два отдельных сервиса для получения только цен «GetProductPrice» и только остатков «GetProductRest» (причем только по одной конкретной позиции номенклатуры) считаются устаревшими;

Для получения и цен и остатков одновременно одним сервисом, причем для большой группы номенклатурных позиций (а именно по товарной группе см.далее) рекомендуется использовать сервис «ProductsPriceAndRest» (см. описание ниже);

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

Для решения этой задачи в сервисе предусмотрен ряд важных (необязательных) параметров, а именно:

            -«CommodityGroupKey» - ключ товарной группы, позволяет отобрать номенклатурные позиции только одного определенного производителя (вендора), например: «AXIS», «DAHUA», «RITTAL» и т.д.

ПРИМЕЧАНИЕ: полный список ключей товарных групп (производителей) можно получить с помощью сервиса «GetCommodityGroupsList»" (см. описание ниже);

            -«CategoryKey» - ключ категории товара, позволяет отобрать номенклатурные позиции по определенной категории, например: «Системы видеонаблюдения», «Источники бесперебойного питания» и т.д.;

ПРИМЕЧАНИЕ: полный список ключей категорий товаров можно получить с помощью сервиса «ProductsCategories» (см. описание ниже);

ПРИМЕЧАНИЕ: в том случае, если в данный параметр передается ключ категории, которая является группой (содержит подчиненные подкатегории), то отбор будет выполнен по всем категориям входящим в эту группу;

            -«SinceDate» (с даты) - при указании данного параметра, сервис вернёт карточки номенклатурных позиций, чьи данные были изменены или добавлены только после этой даты;

Например, это может быть дата последней загрузки/обновления данных карточек в базе самого клиента;

ПРИМЕЧАНИЕ: формат параметра «SinceDate» должен отвечать следующим требованиям:

            -длина параметра должны быть 8 символов(только цифры);

            -иметь следующую последовательность:

             первые 4 цифры - год, далее 2 цифры - месяц, последние 2 цифры - день (БЕЗ Разделителей) ;

            -«PartArticle»(часть артикула) параметр даёт дополнительную функциональность, а именно: накладывает фильтр на Артикул (реквизит номенклатуры типа «Строка») с тем, чтобы отобрать только те из них, где встречаются определенная последовательность символов, например, где содержаться символы «DGS-1510»;

ПРИМЕЧАНИЕ: данные необязательные параметры можно использовать как независимо друг от друга так и совместно;

При совместном использовании они дополняют друг друга ещё более уточняя/сокращая перечень выгружаемых позиций;

Т.о. клиенты имеют возможность довольно точно выгружать нужные им целевые позиции номенклатуры;

Пример адреса вызова:

https://api.soft-tronik.ru/API/hs/Products/GetProductList/f1c45f07-e56e-49c5-9cb8-6945918988ad?SinceDate=20230323&CategoryKey=000000025&CommodityGroupKey=9f8f007e-3161-11e2-a565-028037fe0200&PartArticle=DGS-1510

ГДЕ:

 к содержанию

            Сервис получения данных карточки номенклатуры («GetProductInfo») имеет два обязательных параметра: «Ключ контактного лица» и «Код номенклатуры» и может иметь один необязательный параметр «Ключ договора» (его Имя: «ContractKey»);

Разработчики рекомендуют использовать сервис «GetProductInfo» в двух вариантах:

            1. Первоначальное наполнение своей базы данными карточек интересующих их товаров;

Рекомендуется делать это однократно;

            2. Обновление данных карточек только по тем позициям по которым в нашей базе произошла модификация (как получить список наших товаров только с измененными/добавленными данными карточек (с определенной даты) см. описание сервиса «GetProductList», параметр «SinceDate»);

Данный режим запуска позволяет:

-актуализировать данные по ранее выгруженным позициям;

-загрузить недавно созданные (новинки) позиции;

-оптимизирует этот процесс по времени и нагрузке на систему;

Рекомендуется выполнять периодически; 

Пример адреса вызова:

https://api.soft-tronik.ru/API/hs/Products/GetProductInfo/f1c45f07-e56e-49c5-9cb8-6945918988ad/000037943?ContractKey=d56cf421-20e7-11e6-b19a-9c8e99fc6c3e

ГДЕ:

 к содержанию

Сервис получения иерархии категорий товаров («ProductsCategories») 

имеет один обязательный параметр: «Ключ контактного лица» и не имеет необязательных параметров:

Пример адреса вызова

https://api.soft-tronik.ru/API/hs/Products/ProductsCategories/f1c45f07-e56e-49c5-9cb8-6945918988ad

            ГДЕ:

Данный Сервис формирует полную иерархию категорий товаров;

Данные выдаются в виде списка категорий с ключами для них и массивом подчиненных категорий (если текущая выгружаемая категория является группой);

ПРИМЕЧАНИЕ: выгрузка списка товаров (с кодами) в т.ч. по категориям см. описание сервиса «GetProductList»;

 к содержанию

Сервис выгрузки цен и остатков (POST) по полученному (от клиента) целевому списку номенклатуры («PostProductsListPricesAndRests»)

            Целью данного сервиса является одновременное получение цен и остатков по произвольному (целевому) списку товаров составленному клиентом;

Данный сервис является более оптимальным в случае получения данных именно по узкому списку товаров интересующих клиента в отличии получения тех же данных , но по всей палитре товарной группы сервисом «ProductsPriceAndRest»;

Составленный целевой список номенклатуры может быть, например в дальнейшем, использован для автоматического создания Счета клиента сервисом «PostCreateNewCustomerOrder»;

Общие требования к принимаемым/передаваемым данным (более детально требования будут рассмотрены ниже):

-Данные принимаются/отдаются сервисом в формате JSON;

-Данные принимаются/отдаются в виде строки в кодировке  «UTF-8»;

-В строке тела POSTзапроса (передаваемого сервису) должны содержаться строго только два элемента структуры данных:

                                   -Элемент с общими параметрами;

                                   -Элемент с массивом кодов номенклатуры по которым будут определяться цены и остатки;

ПРИМЕЧАНИЕ: никаких других структур данных, равно как и лишних полей в этих двух элементах быть не должно;

Данные, которые принимаются сервисом (тело POST-запроса)

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

Элемент с общими параметрами должен соответствовать следующим требованиям:

-Иметь идентификатор «GeneralParameters»;

-Иметь Тип «object» (JSONобъект);

Элемент с массивом кодов номенклатуры должен соответствовать следующим требованиям:

-Иметь идентификатор «ArrayProductsCodes»;

-Иметь Тип «array» (Массив);

-Внутри данного массива должны содержаться коды номенклатуры, для которой необходимо получение цен и остатков;

-Внутри данного массива не должно содержаться более 100 кодов;

Элемент с общими параметрами должен содержать в себе следующий состав полей:

Таблица №1

            ПРИМЕЧАНИЕ: «Ключ контактного лица» И «Ключ Договора» предоставляются компанией «Софт-Троник» и их формат и значения уже соответствуют необходимым требованиям к формату ключей;

            ПРИМЕЧАНИЕ: Коды номенклатурных позиций можно получить с помощью отдельного сервиса «GetProductList»(поле «Code»);

            ПРИМЕЧАНИЕ: оба эти поля «ContactPersonKey» И «ContractKey» являются обязательными;

Пример данных, принимаемых сервисом (тело POST Запроса с данными для получения цен и остатков)

{

"GeneralParameters": {

"ContractKey": "66f6120a-c5dc-11e6-abcd-9c8e99fc6c3e",

"ContactPersonKey": "f1c45f07-e56e-49c5-9cb8-6945918988ad"

},

"ArrayProductsCodes": [

"000005301",

"000107962",

"000024421",

"000035411"

]

}

Состав полей выгрузки данных сервиса показан в следующем Примере:

Пример ответа сервиса об успешной обработке данных:

{

"Header": {

"Code": 0,

"Message": " в строке следующей в Массиве Кодов Номенклатуры('ArrayProductsCodes') под номером: 3, обнаружено:  ПУСТОЕ ЗНАЧЕНИЕ Кода Номенклатуры. Оно будет проигнорировано. , , , "

},

"Body": {

"currency": [

{

"_id": "RUB",

"_rate": "1"

},

{

"_id": "USD",

"_rate": 61.8031

},

{

"_id": "EUR",

"_rate": 68.2924

}

],

"ProductsDataWithPricesAndBalances": [

{

"Article": null,

"Code": "000005301",

"Prices": null,

"StockBalance": null

},

{

"Article": null,

"Code": "2288",

"Prices": null,

"StockBalance": null

},

{

"Article": "DH-ZAZ660B",

"Code": "000107962",

"Prices": [

{

"PriceType": "DillerPrice",

"CurrencyId": "USD",

"Price": 0.01

},

{

"PriceType": "RetailPrice",

"CurrencyId": "RUB",

"Price": 0.01

},

{

"PriceType": "SalePrice",

"CurrencyId": "EUR",

"Price": 0.01

}

],

"StockBalance": [

{

"Warehouse": "101 Москва, основной",

"Rest": 1

},

{

"Warehouse": "201 С-Петербург, основной",

"Rest": 1

}

]

},

{

"Article": null,

"Code": "000024421",

"Prices": null,

"StockBalance": null

},

{

"Article": "HS-UR174E",

"Code": "000035411",

"Prices": [

{

"PriceType": "DillerPrice",

"CurrencyId": "USD",

"Price": 0.01

},

{

"PriceType": "RetailPrice",

"CurrencyId": "RUB",

"Price": 0.01

},

{

"PriceType": "SalePrice",

"CurrencyId": "EUR",

"Price": 0.01

}

],

"StockBalance": [

{

"Warehouse": "201 С-Петербург, основной",

"Rest": 1

}

]

}

],

"_date": "2021-04-01 10:54"

}

}

ПРИМЕЧАНИЕ:

-В самом начале выгружаются курсы валют на дату выгрузки (текущую дату);

-Количество выгружаемых валют всегда три (рубли, доллары и евро);

Выгрузка цен номенклатуры имеет ряд особенностей:

-Количество выгружаемых видов цен не превышает трех;

-Минимальное количество выгружаемых цен – одна;

-Совместно с данными собственно цены указываются данные валюты в которой она номинирована;

Выгрузка данных по остаткам имеет следующие особенности:

-Максимальное количество данных (складов) в массиве "StockBalance" заранее не определено, все зависит от того на скольких складах реально присутствует товар;

-В случае, когда товара нет на остатках ни на одном из складов, массив "StockBalance» все же будет присутствовать в выгрузке, но с нулевым количество (пустой);

Выгрузка данных по самой номенклатуры имеет следующие особенности:

-При анализе переданных кодов номенклатура, система проигнорирует пустые строковые значения, а так же значения НЕ строковых типов, при этом программа не будет останавливаться по ошибке, а создав соответствующее предупреждение продолжит работу;

-Если по переданному коду, соответствующей номенклатуры в базе не будет найдено (равно как и в случае, если вдруг она стала НЕ доступной), то данная позиция все же будет присутствовать в ответе сервиса, но все её поля (кроме кода) будут содержать значение «Null»(Неопределено), например данные по такой номенклатуре могут выглядеть так:

{

"Article": null,

"Code": "2288",

"Prices": null,

"StockBalance": null

}

 к содержанию

Сервис получения списка ассоциированных товаров по указанной номенклатуре(«ProductAssociations») 

имеет два обязательный параметр: «Ключ контактного лица» и «Код номенклатуры» и не имеет необязательных параметров:

Пример адреса вызова

https://api.soft-tronik.ru/API/hs/Products/ProductAssociations/f1c45f07-e56e-49c5-9cb8-6945918988ad/000106179

            ГДЕ:

Данный Сервис формирует массив ассоциированных номенклатурных позиций (если они существуют) с товаром, код которого передан как параметр сервиса;

Помимо собственно артикулов (поле «AssociatedPartnumber») ассоциированных товаров, сервис выдает тип ассоциации (поле «AssociationType»), например, «Аналог», «Аксессуар», «ОбязательноВКомплекте», «РекомендоватьВКомплекте», «РасходныеМатериалы» и т.д.;

А так же комментарий (поле «Comment»);

ПРИМЕЧАНИЕ: Коды номенклатурных позиций можно получить с помощью отдельного сервиса «GetProductList»(поле «Code»);

            Сервис для получения списка доступных договоров(«GetCustomerContracts») имеет два обязательных параметра: «Ключ контактного лица» и «Ключ контрагента» и не имеет необязательных параметров;

Пример адреса вызова:

https://api.soft-tronik.ru/API/hs/Customers/GetCustomerContracts/f1c45f07-e56e-49c5-9cb8-6945918988ad/4fec099d-b25e-4a27-8cef-849a05c606ac

ГДЕ:

к содержанию 

Сервис получения остатков конкретной позиции номенклатуры («GetProductRest») имеет два обязательных параметра: «Ключ контактного лица» и «Код номенклатуры» и не имеет необязательных параметров;

Пример адреса вызова:

https://api.soft-tronik.ru/API/hs/Products/GetProductRest/f1c45f07-e56e-49c5-9cb8-6945918988ad/000037943

ГДЕ:

ПРИМЕЧАНИЕ: 

• остатки выгружаются в разрезе Складов и только по товарным складам;

• в выгрузку попадают только склады с ненулевым свободным запасом;

к содержанию 

Сервис получения списка файлов(списка ссылок для получения по API) конкретной позиции номенклатуры («GetProductDataFilesList») имеет два обязательных параметра: «Ключ контактного лица» и «Код номенклатуры» и может иметь один необязательный параметр «Типы файлов»(его Имя: «TypeFiles»);

Пример адреса вызова:

https://api.soft-tronik.ru/API/hs/Products/GetProductDataFilesList/f1c45f07-e56e-49c5-9cb8-6945918988ad/000037943?TypeFiles=jpg

ГДЕ:

ПРИМЕЧАНИЕ: 

• необязательный параметр «TypeFiles» может быть как одиночным (как в примере), так и составным или обобщенным(только для файлов картинок), а именно:

• пример составного параметра «TypeFiles»: «png,jpeg,pdf», т.е. через запятую перечислены типы файлов, но не более 10 типов;

• пример обобщенного параметра «TypeFiles» (в данном случае возможен только один вариант и только для файлов картинок): «Image», который включает в себя следующие типы картинок: «jpg», «png», «jpeg», «gif»

к содержанию 

Сервис получения одного файла номенклатуры(«GetProductDataFile») имеет три обязательных параметра: «Ключ контактного лица», «Код номенклатуры», «Ключ файла»

Пример адреса вызова:

https://api.soft-tronik.ru/API/hs/Products/GetProductDataFile/f1c45f07-e56e-49c5-9cb8-6945918988ad/000037943/01e4b872-6ae5-11e7-a16f-9c8e99fc6c3e

ГДЕ:

ПРИМЕЧАНИЕ: как говорилось выше, полные ссылки (адреса) для вызова данного сервиса (вместе с Ключами файлов данных номенклатуры) можно получить с помощью выше описанного сервиса «Сервис получения списка файлов (списка ссылок для получения по API) конкретной позиции номенклатуры («GetProductDataFilesList»)»

к содержанию 

Сервис получения основного изображения номенклатуры («GetProductMainImage») имеет два обязательных параметра: «Ключ контактного лица» и «Код номенклатуры» и не имеет необязательных параметров

Пример адреса вызова:

https://api.soft-tronik.ru/API/hs/Products/GetProductMainImage/f1c45f07-e56e-49c5-9cb8-6945918988ad/000037943

ГДЕ:

к содержанию 

Сервис получения списка документов (Счетов покупателей) («GetBuyerOrdersList») имеет два обязательных параметра: «Ключ контактного лица» и «Ключ Контрагента» » и может иметь пять необязательных параметров:

ПРИМЕЧАНИЕ:

• значения по умолчанию подобраны таким образом, чтобы обеспечить получение самой нужной (актуальной) информации для клиента;

• при использовании необязательных параметров время отклика возрастает;

1. Параметр «Дата начала периода» (его Имя: «DateStart»), ограничивает отбор счетов началом периода;

2. Параметр «Дата окончания периода» (его Имя: «DateEnd»), ограничивает отбор счетов периодом окончания;

ПРИМЕЧАНИЕ: 

• для удобства использования сервиса, приняты следующие положения о значениях по умолчанию для параметров периода:

• если не указаны значения ни для одного из параметров периода, то счета собираются с начала текущего года по текущую дату (включительно);

• если заполнен только один из параметров периода (дата начала, либо дата окончания), то второй параметр автоматически определяется на основании указанного параметра;

• период указывается в следующем формате: ГГГГММДД

3. Параметр «Статус счетов покупателя» (его Имя: «OrderStatus») - для отбора счетов по его рабочему статусу или (рабочему и техническому статусу);

Статус состояния:  «Новый», «Утвержден», «Отгружается», «Черновик», «Завершен» и т.д;

Признак: «Проведен», «Помечен на удаление», «Отменены все строки» и т.д.;

У данного параметра можно указать два значения:

• «Completed» - отбирает счета только в его рабочем статусе «Завершен»,

• «All» - собирает все счета (рабочие/актуальные, не рабочие, архивные и т.д.) данного контрагента в т.ч. со всевозможными признаками (помеченные на удаление, без сумм, с полной отменой всех строк, рабочие(актуальные) и т.д.);

• Если данный параметр не указан, то выдаются только активные незавершенные счета по данному контрагенту по всем его договорам, доступным данному контактному лицу;

4. Параметр «Ключ Договора контрагента» («ContractKey») - для отбора счетов только по определенному договору;

5. Параметр «Код номенклатурной позиции» (его Имя: «ProductCode»), для отбора счетов только по определенной номенклатурной позиции;

Пример адреса вызова (с максимальным количеством параметров):

https://api.soft-tronik.ru/API/hs/BuyersOrders/GetBuyerOrdersList/f1c45f07-e56e-49c5-9cb8-6945918988ad/4fec099d-b25e-4a27-8cef-849a05c606ac?DateStart=20160101&DateEnd=20161231&OrderStatus=All&ContractKey=d56cf421-20e7-11e6-b19a-9c8e99fc6c3e&ProductCode=000094124

ГДЕ:

Данные сервис выдаёт только часть информации по счетам покупателей, в частности, без данных табличных частей, а так же Ключи самих документов счетов(их уникальные идентификаторы);

За подробной информацией по конкретному Счету (в т.ч. по данным его табличных частей) следует обращаться с помощью другого сервиса («GetBuyerOrderInfo», см. описание ниже), который, в частности, в качестве обязательного параметра требует ввода Ключа документа Счет, соответственно, данный Ключ документа следует брать из результатов работы текущего описываемого сервиса;

к содержанию 

Сервис получения данных одного документа (Счета покупателя) («GetBuyerOrderInfo») имеет три обязательных параметра: «Ключ контактного лица», «Ключ Контрагента» и «Ключ документа Счет» и не имеет необязательных параметров

Пример адреса вызова (с максимальным количеством параметров):

https://api.soft-tronik.ru/API/hs/BuyersOrders/GetBuyerOrderInfo/f1c45f07-e56e-49c5-9cb8-6945918988ad/4fec099d-b25e-4a27-8cef-849a05c606ac/debc5eb4-2335-11e6-b19a-9c8e99fc6c3e

ГДЕ:

 Данный Сервис обеспечивает самую подробную информацию по счету покупателя, а именно:

• данные «шапки» документа Счет покупателя (номер, дата, статусы (рабочий и технический), валюта, курс, договор и т.д.);

• данные табличной части Товары (Услуги, если заполнена), с количеством, ценами, суммами, данные по резервированию, отгрузке и т.д. по каждой заказанной номенклатурной позиции;
• данные табличной части по условиям оплаты (наличие предоплаты, отсрочки и т.д.);

к содержанию 

Сервис получения списка неотгруженных Счетов покупателя («GetBuyerOrdersListUnshipped») имеет два обязательных параметра: «Ключ контактного лица» и «Ключ Контрагента» » и может иметь один необязательный параметр: «Ключ договора»(его Имя: «ContractKey»);

Пример адреса вызова:

https://api.soft-tronik.ru/API/hs/BuyersOrders/GetBuyerOrdersListUnshipped/f1c45f07-e56e-49c5-9cb8-6945918988ad/4fec099d-b25e-4a27-8cef-849a05c606ac?ContractKey=d56cf421-20e7-11e6-b19a-9c8e99fc6c3e 

ГДЕ:

Данный Сервис обеспечивает возможность получения подробной информации по всем, именно неотгруженным, Счетам покупателя (за всё время, т.е. без ограничения по периоду и только по табличной части Товары), а именно:

ПРИМЕЧАНИЕ: понятие неотгруженности Счета означает что хотя бы одна номенклатурная позиция, из Счета, не отгружена (либо полностью либо частично);

При этом отмененные строки Счета не учитываются;

- Данные «шапки» документа Счет покупателя (номер, дата, статусы (рабочий и технический), валюта, курс, договор и т.д.);

- Данные табличной части Товары, с количеством, ценами, суммами, данные по резервированию, отгрузке и т.д. по каждой заказанной номенклатурной позиции;

ПРИМЕЧАНИЕ: для полноты информации, Сервис выгружает данные по всем номенклатурным позициям из Счета, независимо от того отгружены они или нет;

к содержанию 

Сервис получения основной печатной формы документа Счет покупателя («GetBuyerOrderMainPrintedForm») имеет два обязательных параметра: «Ключ контактного лица» и «Ключ документа Счет покупателя» и не имеет необязательных параметров:

Пример адреса вызова

https://api.soft-tronik.ru/API/hs/BuyersOrders/GetBuyerOrderMainPrintedForm/f1c45f07-e56e-49c5-9cb8-6945918988ad/debc5eb4-2335-11e6-b19a-9c8e99fc6c3e

ГДЕ:

Данный Сервис формирует выгрузку печатной формы конкретного документа Счет покупателя, ключ которого передан в качестве второго обязательного параметра сервиса (с печатью и подписями) в формате PDF;

к содержанию

Сервис получения списка товарных групп («GetCommodityGroupsList») имеет один обязательный параметр: «Ключ контактного лица» и не имеет необязательных параметров:

Пример адреса вызова

https://api.soft-tronik.ru/API/hs/Products/GetCommodityGroupsList/f1c45f07-e56e-49c5-9cb8-6945918988ad

ГДЕ:

Данный Сервис формирует список актуальных товарных групп номенклатуры, которую предлагает наша организация;

к содержанию

Сервис получения списка складов («GetWarehousesList») имеет один обязательный параметр: «Ключ контактного лица» и не имеет необязательных параметров:

Пример адреса вызова

https://api.soft-tronik.ru/API/hs/Products/GetWarehousesList/f1c45f07-e56e-49c5-9cb8-6945918988ad

            ГДЕ:

Данный Сервис формирует список актуальных складов, на которых хранится номенклатура нашей организации;

к содержанию

Сервис получения цен номенклатуры («GetProductPrice») имеет один обязательный параметр: «Ключ контактного лица» и два необязательных параметра: «Код номенклатуры(его Имя: «ProductCode») ИЛИ «Ключ товарной группы» (его Имя: «CommodityGroupKey») и «Ключ договора» (его Имя: «ContractKey») ;

ПРИМЕЧАНИЕ: хотя параметры «Код номенклатуры и «Ключ товарной группы» формально необязательные, но система следит, чтобы один из них (или код номенклатуры или ключ товарной группы) был задан, иначе она не может определить по каким собственно номенклатурным позициям нужно выгружать цены;

Данное требование отражает тот факт, что, для удобства клиентов, данный сервис возможно вызывать как в варианте для отдельной номенклатурной позиции так и в варианте для товарной группы в целом, т.е. по номенклатурным позициям, отнесенным к выбранной товарной группе;

ПРИМЕЧАНИЕ: как было описано выше «Ключ товарной группы» можно скопировать из Сервиса Сервис получения списка товарных групп («GetCommodityGroupsList»);

Пример адреса вызова (в варианте по товарной группе):

https://api.soft-tronik.ru/API/hs/Products/GetProductPrice/f1c45f07-e56e-49c5-9cb8-6945918988ad?CommodityGroupKey=573308d3-e3e7-11e7-b212-9c8e99fc6c3e&ContractKey=d56cf421-20e7-11e6-b19a-9c8e99fc6c3e 

ГДЕ:

Данный сервис предназначен для получения/актуализации цен номенклатурных позиций, соответственно, он выдаёт минимум необходимой информации по самой номенклатуре и её цене.

В данном случае выводятся только её Артикул и Код, в дополнение к цене выгружается валюта, никакие другие данные самой номенклатуры не выводятся.

Для заполнения карточки номенклатуры данный сервис не подходит, а при возникновении подобной необходимости следует использовать Сервис получения данных карточки номенклатуры («GetProductInfo»);

В конце выгрузки заполняется дата, на которую выгружены цены.

к содержанию

Сервис получения и цен и остатков («ProductsPriceAndRest»)

Целью данного сервиса является выгрузка одновременно и цен и остатков по номенклатурным позициям, входящим в состав выбранной клиентом товарной группы;

Преимущества:

- Чтобы одновременно получить и цены и остатки по товарам не нужно вызывать два разных сервиса(отдельно по остаткам и отдельно по ценам), можно пользоваться этим одним;

- Данные получаются сразу списком(по товарной группе), что так же является удобным и экономит время(как машинное так и разработчика) ;

- Расширен состав выгружаемых цен (подробности см. далее);

Имеет три параметра:

• ключ контактного лица (имя «ContactPersonKey»);

• ключ товарной группы (имя «CommodityGroupKey»);

• ключ договора («ContractKey»);

Формально они являются не обязательными (в строке вызова указываются после знака вопроса «?»), но система строго контролирует их наличие;

ПРИМЕЧАНИЕ: ключ товарной группы можно получить с помощью сервиса получения списка товарных групп («GetCommodityGroupsList»);

Пример вызова:

https://api.soft-tronik.ru/API/hs/Products/ProductsPriceAndRest/?CommodityGroupKey=9f8f007e-3161-11e2-a565-028037fe0200&ContactPersonKey=f1c45f07-e56e-49c5-9cb8-6945918988ad&ContractKey=d56cf421-20e7-11e6-b19a-9c8e99fc6c3e

ГДЕ:

- В общем случае, программа пытается выгрузить цены по трём Видам цен (если они есть):

- Розничная цена (Имя в выгрузке «RetailPrice») – рекомендуемая розничная цена продажи;

- Цена распродаж (Имя в выгрузке «SalePrice») – распродажная цена, если она действует в настоящий момент;

ПРИМЕЧАНИЕ: 

• как и ранее цены выгружаются вместе с названием валюты, в которой они номинированы;

• данные по видам цен с нулевыми значениями цен не выгружаются;

• данные по складам с нулевыми свободными остатками так же не выгружаются;

• данные по одной номенклатурной позиции, в выгрузке,  имеют четкую последовательность, а именно:

• данные самой номенклатуры (Артикул и Код);
• массив цен;
• массив остатков;

ПРИМЕЧАНИЕ: 

• если каких-то данных нет совсем, например, остатков, то сам массив будет присутствовать в выгрузке и в этом случае он будет пустой;

• в начале выгрузки идут данные по курсам валют на текущую дату, оформленные в виде массива («currency»);

Важно: в целях оптимизации нагрузки на сервер компании, по данному сервису введено ограничение частоты выгрузки данных;

Суть ограничения в следующем: один и то же клиент по одной и той же товарной группе не может вызвать данный сервис чаще, чем один раз в 30 минут (соответственно на вызовы по др. товарным группам никаких ограничений не накладывается);

к содержанию

Сервис создания Счета покупателя («PostCreateNewCustomerOrder»)

 к содержанию

Целью данного сервиса является автоматический(программный) приём Заявки покупателя с дальнейшем конвертированием её в Счет покупателя в базе компании «Софт-Троник»;

Для успешного приёма новой Заявки, следует передавать в данный сервис определенные наборы данных( в частности, номенклатурный состав и т.д.), поэтому, с технической точки зрения, обращение к сервису выполняется при помощи запросов с использованием метода HTTP-запроса POST;

Логически, сервис принимает И отдаёт следующие варианты данных:

• принимает данные для Заявки (тело POST Запроса);

• может отдавать данные(ответ сервиса) об ошибочной ситуации;

• может отдавать данные(ответ сервиса) об успешном приёме Заявки и создании на её основе Счета;

Общие требования к принимаемым/передаваемым данным (более детально требования будут рассмотрены ниже):

• данные принимаются/отдаются в формате JSON;

• данные принимаются/отдаются в виде строки в кодировке  «UTF-8»;

• данные Заявки, которые принимает данный сервис, должны иметь строго определенную структуру (см. ниже) без лишних элементов/структур данных и полей внутри этих структур;

• часть полей является обязательными, а часть имеет необязательный характер и может отсутствовать в данных для Заявки;

• т.к. JSON не содержит типа Дата (значения даты представляются в нём строкой), для всех дат, в принимаемых и отдаваемых данных, выбран следующий формат:

• формат даты: ISO;

• вариант записи даты: локальная дата;

ПРИМЕЧАНИЕ: т.о. ожидаемый формат даты выглядит следующим образом: "2020-04-28T12:10:02";

Все ошибочные ситуации, в процессе работы сервиса, можно разделить на две группы:

• Критические ошибки, например: ошибки структуры принимаемых данных в целом, некорректные имена, типы, значения обязательных полей, их отсутствие и т.д.;

• Не критические ошибки – Предупреждения, например: некорректные данные по необязательным полям, наличие недопустимых символов в комментариях, неверная кодировка символов кириллицы и пр.;

ПРИМЕЧАНИЕ: критичные ошибки останавливают процесс работы сервиса с выдачей ответа о соответствующей ошибочной ситуации, предупреждения напротив, накапливаются, не останавливая процесс приёма Заявки и формирования Счета и выдаются совместно с ответом об успешном выполнении сервиса (подробности см. раздел 7)

ПРИМЕР обработки с формированием тела POST-запроса (для передачи в сервис данных по Заявке), вызовом данного сервиса находится в демо-базе (в помощь программистам), которую можно скачать здесь (на этой странице);

Данные, которые принимаются сервисом (тело POST-запроса с данными для Заявки)

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

В строке тела POST-запроса должны содержаться строго только два элемента структуры данных:

• элемент с данными «шапки» Заявки;

• элемент с данными табличной части Заявки;

ПРИМЕЧАНИЕ: в соответствии с общими требованиями к принимаемым данным, никаких других структур данных, равно как и лишних полей в этих двух элементах быть не должно;

Элемент с данными «шапки» должен соответствовать следующим требованиям:

• иметь идентификатор «DocumentHeaderDetails»

• иметь Тип «object»(JSON-объект)

Элемент с данными табличной части должен соответствовать следующим требованиям:

• иметь идентификатор «SpreadsheetProducts»

• иметь Тип «array» (Массив)

• внутри данного массива должны содержаться элементы типа «object» (JSON-объект)
  

• внутри данного массива не должно содержаться более 100 «JSON-объектов» (ограничение в Заявке – не более 100 строк);

Элемент с данными «шапки» должен содержать в себе следующий состав полей:

Таблица №1

ПРИМЕЧАНИЕ:

- «Ключ контактного лица» и «Ключ Договора» предоставляются компанией «Софт-Троник» и их формат и значения уже соответствуют необходимым требованиям к формату ключей;

В комментариях:

• разрешается использование символов русского и латинского алфавита;

• разрешается использование цифр и символа пробела, а так же ряд символов: .,:;!?()"@№-_/\-

• все прочие символы запрещены для использования, и в случае если программа обнаружит не допустимые символы, то весь комментарий будет очищен и соответственно не попадет в документ;

• для строки тела POST-запроса необходимо использовать кодировку UTF-8. В ином случае все комментарии считаются не корректными и будут автоматически очищены;

• комментарий не должен превышать 800 символов, в противном случае он будет обрезан;

Элемент с данными табличной части должен содержать в себе следующий состав полей:

Таблица №2

ПРИМЕЧАНИЕ: Коды номенклатурных позиций можно получить с помощью отдельного сервиса «GetProductList»(поле «Code»);

ПРИМЕЧАНИЕ: в соответствии с требованиями предъявляемыми к принимаемому элементу структуры данных табличной части («SpreadsheetProducts»), количество строк в нем не может превышать 100;

Пример данных, принимаемых сервисом (тело POST Запроса с данными для Заявки)

{

"DocumentHeaderDetails": {

"OrderContactPersonID": "f1c45f07-e56e-49c5-9cb8-6945918988ad",

"OrderContractID": "d56cf421-20e7-11e6-b19a-9c8e99fc6c3e",

"OrderNumberFromCustomer": "102",

"OrderDateFromCustomer": "2020-05-18T00:00:00",

"OrderDesiredShipmentDate": "2020-06-01T00:00:00",

"OrderGeneralCommentFromCustomer": "№45 / 1212 ПРО"

},

"SpreadsheetProducts": [

{

"ProductCode": "000120337",

"Quantity": 1,

"LineComment": "отгрузить в первую очередь"

},

{

"ProductCode": "000113817",

"Quantity": 2,

"LineComment": "возможен дозаказ"

},

{

"ProductCode": "000122034",

"Quantity": 3,

"LineComment": "нужны доп.документы"

}

]

}

      Данные, которые отдаются сервисом (ответ сервиса)

        Общую структуру ответа об успешном выполнении сервиса и о его ошибочной ситуации описана в разделе 7;

        Наполнением элемента данных «Body» ответа сервиса об успешном приёме Заявки и создании Счета является ряд полей:

                        -«OrderDate» дата созданного Счета;

                        -«OrderNumber» номер созданного Счета;

                        -«ServiceGetBuyerOrderInfo» гиперссылка на сервис «GetBuyerOrderInfo» сформированная со всеми нужными параметрами для получения подробной информации по созданному Счету покупателя;

                        -«ServiceGetBuyerOrderMainPrintedForm» гиперссылка на сервис «GetBuyerOrderMainPrintedForm» (так же уже с параметрами) для получения печатной формы созданного Счет покупателя в формате PDF;

Пример ответа сервиса об успешном приёме Заявки и создании Счета:

{

"Header": {

"Code": 0,

"Message": ""

},

"Body": {

"OrderDate": "2020-05-10T19:07:21",

"OrderNumber": "СТ0001189",

"ServiceGetBuyerOrderInfo": "https://api.soft-tronik.ru/API/hs/BuyersOrders/GetBuyerOrderInfo/f1c45f07-e56e-49c5-9cb8-6945918988ad/4fec099d-b25e-4a27-8cef-849a05c606ac/032e7900-a32e-11ee-8186-908d78ae0952",

"ServiceGetBuyerOrderMainPrintedForm": "https://api.soft-tronik.ru/API/hs/BuyersOrders/GetBuyerOrderMainPrintedForm/f1c45f07-e56e-49c5-9cb8-6945918988ad/032e7900-a32e-11ee-8186-908d78ae0952";

}

}

 к содержанию

Новая структура данных выгрузки (после 20.07.2020), которые отдаются сервисом (ответы сервиса)

 к содержанию

Описание общей структуры данных, полей, их форматов и т.д.

• сервисы могут отдавать следующие структуры данных:

• могут отдавать данные(ответ) об ошибочной ситуации;

• могут отдавать данные(ответ) об успешном завершении своей работы;

• ответ об успешном завершении и ответ об ошибочной ситуации имеют одинаковую общую структуру и содержит следующие элементы данных этой структуры:

• элемент данных заголовка ответа сервиса: «Header»;

• элемент данных тела ответа сервиса: «Body»;

• наполнение элемента данных заголовка «Header» ответа сервиса об ошибочной ситуации:

• поле «Code» содержит значение: 1 (единица), оно означает, что выполнение сервиса закончилось с ошибкой;

• поле «Message» содержит само сообщение об ошибке, а так же (после него) может содержать текст предупреждений, если таковые имеются;

ПРИМЕЧАНИЕ: 

- текст об ошибке начинается со слов  «ВНИМАНИЕ!!! Ошибка:», а текст предупреждения – «ПРЕДУПРЕЖДЕНИЯ:»;

- текст с предупреждениям не сигнализирует о наличии серьезных проблем и сам сервис выполнит свою работу полностью, скорее это примечания о неких недочетах, которые выявила система, о них просто нужно знать и в случае необходимости можно исправить или оставить как есть;  

- Наполнение элемента данных «Body» ответа сервиса об ошибочной ситуации:

- В варианте ответа сервиса об ошибочной ситуации, само тело ответа будет содержать значение Null;

Пример ответа сервиса об ошибочной ситуации:

{

"Header": {

"Code": 1,

"Message": "ВНИМАНИЕ!!! Ошибка: … "

},

"Body": null

}

- Наполнение элемента данных заголовка «Header» ответа сервиса об успешном завершении своей работы:

- Поле «Code» содержит значение: 0 (ноль), оно означает, что выполнение сервиса закончилось без критических ошибок;

- Поле «Message» может содержать либо пустую строку, либо текст предупреждений, если таковые имеются;

- Наполнением элемента данных «Body» ответа сервиса об успешном завершении зависит от конкретного сервиса и может содержать в себе различные поля характерные именно для него;

Пример ответа сервиса об успешном завершении работы сервиса:

{

"Header": {

"Code": 0,

"Message": ""

},

"Body": {

…"

}

}

 к содержанию