Подключение
Адрес подключения
http://api.vtt.ru:8048/Portal.svc?singleWsdl
Аутентификация и авторизация
Аутентификация пользователей выполняется посредством передачи в каждый из вызываемых методов пары из логина и пароля, по которым определяется идентичность пользователя.
Некоторые методы требуют наличия у пользователя права на редактирование заказов.
Параметры, передаваемые в методы сервиса для аутентификации и авторизации:
| Параметр | Тип данных | Описание |
| login | string | Логин и пароль для доступа к методам сервиса. Выдаются клиенту менеджером. |
| password | string |
Операции
GetItems
Операция возвращает список товаров с полной информацией о товарах, доступных для заказа в ВТТ.
Доступна только аутентифицированным пользователям.
Входные параметры: логин и пароль пользователя.
Результат: список объектов ItemDto.
GetRuntimeItems
Операция возвращает оперативную информацию о товарах, доступных для заказа в ВТТ. К оперативным данным относятся идентификатор товара и количества (на складе, в доставке и т.д.) товара для заказа.
Доступна только аутентифицированным пользователям.
Входные параметры: логин и пароль пользователя.
Результат: список объектов ItemRuntimeDto.
GetItemPortion
Операция возвращает порцию товаров, ограниченную входными параметрами. Может использоваться для получения списка товаров в несколько запросов, так как набор данных, возвращаемый GetItems может быть слишком большим и его чтение может занять большое количество времени и памяти.
Порция данных ограничивается индексами начала и окончания порции включительно. Индексация элементов начинается с нуля.
Доступна только аутентифицированным пользователям.
Входные параметры:
|
Параметр |
Тип данных |
Описание |
|
login |
String |
Логин и пароль для доступа к методам сервиса. |
|
Password |
String |
|
|
From |
Int |
Индекс начала выборки включительно. Начинается с нуля. |
|
to |
Int |
Индекс последнего элемента выборки включительно. Сверху не ограничивается. Если индекс последнего элемента больше общего количества элементов в выборке, возвращаются все элементы, начиная с «from». |
Результат: объект типа ItemPortionDto. Общее количество товаров в порции составляет «from»-«to»+1.
GetRuntimeItemsPortion
Операция возвращает порцию оперативных данных товаров, ограниченную входными параметрами. Может использоваться для быстрого обновления оперативных данных в течение дня.
Порция данных ограничивается индексами начала и окончания порции включительно. Индексация элементов начинается с нуля.
Доступна только аутентифицированным пользователям.
Входные параметры:
|
Параметр |
Тип данных |
Описание |
|
login |
String |
Логин и пароль для доступа к методам сервиса. |
|
Password |
String |
|
|
From |
Int |
Индекс начала выборки включительно. Начинается с нуля. |
|
to |
Int |
Индекс последнего элемента выборки включительно. Сверху не ограничивается. Если индекс последнего элемента больше общего количества элементов в выборке, возвращаются все элементы, начиная с «from». |
Результат: объект типа ItemRuntimePortionDto. Общее количество товаров в порции составляет «from»-«to»+1 элементов.
GetItem
Операция возвращает полный набор данных о товаре по его идентификатору.
Доступна только аутентифицированным пользователям.
|
Параметр |
Тип данных |
Описание |
|
login |
string |
Логин и пароль для доступа к методам сервиса. |
|
password |
string |
|
|
itemId |
string |
Уникальный идентификатор товара. |
Результат: объект типа ItemDto, если идентификатору itemId соответствует товар. В противном случае генерируется исключение.
GetRuntimeItem
Операция возвращает оперативную информацию о товаре по его идентификатору.
Доступна только аутентифицированным пользователям.
|
Параметр |
Тип данных |
Описание |
|
login |
string |
Логин и пароль для доступа к методам сервиса. |
|
password |
string |
|
|
itemId |
string |
Уникальный идентификатор товара. |
Результат: объект типа ItemRuntimeDto, если идентификатору itemId соответствует товар. В противном случае генерируется исключение.
GetCategories
Операция получения двухуровневого иерархического списка категорий товарной номенклатуры. Иерархия устанавливается через идентификатор родительской категории группы (ParentId). Для категорий верхнего уровня этот идентификатор не задаётся (null).
Операция доступна только аутентифицированным пользователям.
Входные параметры: логин и пароль пользователя.
Результат: список объектов CategoryDto.
GetCategoryItems
Операция получения списка товаров указанной категории. Если передан идентификатор родительской категории, будет возвращён набор товаров из всех дочерних категорий. Для дочерних категорий возвращается только товары, принадлежащие этим категориям.
Доступна только аутентифицированным пользователям.
|
Параметр |
Тип данных |
Описание |
|
login |
string |
Логин и пароль для доступа к методам сервиса. |
|
password |
string |
|
|
categoryId |
string |
Уникальный идентификатор категории. Если categoryId идентифицирует категорию верхнего уровня, будут возвращены товары из всех дочерних категорий. Если categoryId идентифицирует дочернюю категорию, будут возвращены товары только из этой категории, если она существует. |
Результат: список объектов ItemDto.
GetCategoryRuntimeItems
Операция получения списка оперативных данных по товарам в указанной категории. Если передан идентификатор родительской категории, будет возвращён набор товаров из всех дочерних категорий. Для дочерних категорий возвращается только товары, принадлежащие этим категориям.
Доступна только аутентифицированным пользователям.
|
Параметр |
Тип данных |
Описание |
|
login |
string |
Логин и пароль для доступа к методам сервиса. |
|
password |
string |
|
|
categoryId |
string |
Уникальный идентификатор категории. Если categoryId идентифицирует категорию верхнего уровня, будут возвращены товары из всех дочерних категорий. Если categoryId идентифицирует дочернюю категорию, будут возвращены товары только из этой категории, если она существует. |
Результат: список объектов ItemRuntimeDto.
GetOrders
Операция возвращает заказы текущего пользователя.
Доступна только аутентифицированным пользователям.
Входные параметры: логин и пароль пользователя.
Результат: список объектов OrderDto.
GetOrderStatus
Операция возвращает состояние заказа с переданным идентификатором.
Доступна только аутентифицированным пользователям.
Входные параметры:
|
Параметр |
Тип данных |
Описание |
|
login |
String |
Логин и пароль для доступа к методам сервиса. |
|
password |
String |
|
|
orderId |
String |
Уникальный идентификатор заказа. |
Результат: объект OrderDto.
В случаях, когда заказ с указанным идентификатором не удаётся найти, результатом служит ошибка с кодом BUSINESS_LOGIC_ERROR и соответствующим описанием.
GetOrderWithLines
Операция возвращает полную информацию о заказе и входящих в него товарных позициях.
Доступна только аутентифицированным пользователям.
Входные параметры:
|
Параметр |
Тип данных |
Описание |
|
login |
string |
Логин и пароль для доступа к методам сервиса. |
|
password |
string |
|
|
orderId |
string |
Уникальный идентификатор заказа. |
Результат: объект типа OrderFullDto.
В случаях, когда заказ с указанным идентификатором не удаётся найти, результатом служит ошибка с кодом BUSINESS_LOGIC_ERROR и соответствующим описанием.
CreateOrder
Операция размещения нового заказа в учётной системе ВТТ.
Доступна только аутентифицированным пользователям.
Входные параметры:
|
Параметр |
Тип данных |
Описание |
|
login |
string |
Логин и пароль для доступа к методам сервиса. |
|
password |
string |
|
|
lines |
Массив объектов с описанием позиций создаваемого заказа. |
Результат: строковый идентификатор созданного заказа.
AddItem
Операция добавления товарной позиции в указанный заказ, имеющий статус «Резервирование» (см. список статусов заказов).
Доступна только аутентифицированным пользователям, имеющим право на редактирование заказов.
Входные параметры:
|
Параметр |
Тип данных |
Описание |
|
login |
string |
Логин и пароль для доступа к методам сервиса. |
|
password |
string |
|
|
orderId |
String |
Идентификатор заказа, в который добавляются товары. |
|
lines |
Массив объектов с описанием товаров для заказа. |
Результат: структура данных типа OrderLineStatusDto, описывающая результат добавления товара в заказ.
RemoveItem
Операция удаления товара из состава указанного заказа, имеющего статус «Резервирование» (см. список статусов заказов).
Доступна только аутентифицированным пользователям, имеющим право на редактирование заказов.
Входные параметры:
|
Параметр |
Тип данных |
Описание |
|
login |
string |
Логин и пароль для доступа к методам сервиса. |
|
password |
string |
|
|
orderId |
string |
Идентификатор заказа, в который добавляются товары. |
|
itemId |
string |
Артикул товара для удаления из заказа. |
|
сount |
string |
В случае передачи нуля, весь указанный товар удаляется из заказа. |
Результат: операция не возвращает результат.
GetGoodsCompatibilityInformation
Операция получения списка совместимых устройств, к которым подходят товары.
Доступна только аутентифицированным пользователям, имеющим право на редактирование заказов.
Входные параметры:
|
Параметр |
Тип данных |
Описание |
|
login |
string |
Логин и пароль для доступа к методам сервиса. |
|
password |
string |
Результат: список объектов типа ArrayOfCompatibilityDto.
GetUsdRubRate
Операция получения текущего курса доллара.
Доступна только аутентифицированным пользователям.
Входные параметры: логин и пароль пользователя.
Результат: текущий курс и дата его установки.
SetOrderNote
Операция заполнения в заказе примечания (поле note в структурах OrderDto и OrderFullDto).
Доступна только аутентифицированным пользователям, имеющим право на редактирование заказов.
Входные параметры:
|
Параметр |
Тип данных |
Описание |
|
login |
string |
Логин и пароль для доступа к методам сервиса. |
|
password |
string |
|
|
orderId |
string |
Идентификатор заказа, в который добавляются товары. |
|
note |
string |
Текст заметки. |
Результат: код ошибки (Error) и флаг обновления (NoteUpdated).
Структуры данных, участвующие в обмене
Все нижеперечисленные типы данных указаны применительно к языку XML, используемого для кодирования передаваемых сообщений. Так, например, тип “string” соответствует типу “string” из схемы http://www.w3.org/2001/XMLSchema. Подробное описание типов данных можно найти на сайте w3.
ItemDto
Структура данных с информацией о товаре, доступном для заказа в ВТТ (соответствует позиции прайс-листа).
|
Поле |
Тип данных |
Описание |
|
Id |
string |
Артикул товара. |
|
Name |
string |
Наименование товара. |
|
Brand |
string |
Название фирмы-производителя. |
|
Description |
string |
Краткое описание товара. |
|
Group |
string |
Название номенклатурной группы товара. |
|
RootGroup |
string |
Корневая категория товара, родительская для Group. |
|
AvailableQuantity |
decimal |
Количество единиц товара, доступное для заказа (обновляется раз в час). |
|
TransitQuantity |
decimal |
Количество единиц товара в пути. |
|
Price |
decimal |
Цена единицы товара. |
|
PriceRetail |
decimal |
Розничная цена товара. |
|
Width |
decimal |
Длина упаковки товара. |
|
Height |
decimal |
Высота упаковки товара. |
|
Depth |
decimal |
Глубина упаковки товара. |
|
Weight |
decimal |
Масса товара в килограммах. |
|
PhotoUrl |
string |
URL изображения для товара. |
|
OriginalNumber |
string |
Оригинальный номер товара. |
|
Vendor |
string |
Вендор. |
|
Compatibility |
string |
Информация о товаре, в том числе о совместимых моделях. |
|
Barcode |
string |
Штрих-код товара. |
|
MainOfficeQuantity |
decimal |
Количество единиц товара в наличии в головном офисе компании. |
|
NumberInPackage |
decimal |
Количество товара в упаковке. |
|
ColorName |
string |
Цвет. |
|
TransitDate |
date |
Дата ожидаемого прихода товара. |
|
ItemLifeTime |
string |
Ресурс. |
|
NameAlias |
string |
Краткое наименование товара. |
|
GrossDepth |
decimal |
Глубина единицы товара. |
|
GrossWidth |
decimal |
Ширина единицы товара. |
|
GrossHeight |
decimal |
Высота единицы товара. |
|
GrossVolume |
decimal |
Объем единицы товара. |
|
GrossWeight |
decimal |
Брутто. |
|
NetWeight |
decimal |
Нетто. |
|
ColorId |
decimal |
Цвет единицы товара. |
|
ItemLifeTime |
string |
Ресурс единицы товара. |
|
BarCode |
string |
Штрих-код. |
|
TnvedCode |
string |
Код ТНВЭД. |
ItemRuntimeDto
Структура данных с оперативной информацией о товаре в ВТТ (соответствует позиции прайс-листа).
|
Поле |
Тип данных |
Описание |
|
Id |
string |
Артикул товара. |
|
AvailableQuantity |
decimal |
Количество единиц товара, доступное для заказа (обновляется раз в час). |
|
TransitQuantity |
decimal |
Количество единиц товара в пути. |
|
Price |
decimal |
Цена единицы товара. |
|
MainOfficeQuantity |
decimal |
Количество единиц товара в наличии в головном офисе компании. |
ItemPortionDto
Структура данных, описывающая порцию товаров. Содержит список товаров запрошенного размера и общее количество товаров.
|
Поле |
Тип данных |
Обязательность |
Описание |
|
Items |
Список ItemDto |
Да |
Список товаров заданного размера. |
|
TotalCount |
int |
Да |
Общее количество товаров. |
ItemRuntimePortionDto
Структура данных, описывающая порцию оперативных данных о товарах. Содержит список запрошенного размера и общее количество товаров.
|
Поле |
Тип данных |
Обязательность |
Описание |
|
Items |
Список ItemRuntimeDto |
Да |
Список товаров заданного размера. |
|
TotalCount |
int |
Да |
Общее количество товаров. |
CategoryDto
Структура данных, описывающая категорию товара в иерархической структуре товарной номенклатуры.
|
Поле |
Тип данных |
Обязательность |
Описание |
|
Id |
string |
Да |
Идентификатор категории. |
|
ParentId |
string |
Нет |
Идентификатор родительской категории. Не задаётся для категорий верхнего уровня. |
|
Name |
string |
Да |
Название категории. |
OrderDto
Структура данных, содержащая информацию только о самом заказе (не включая его позиции).
|
Поле |
Тип данных |
Обязательность |
Описание |
|
Id |
string |
Да |
Уникальный идентификатор заказа. |
|
CreationDate |
dateTime |
Да |
Дата и время создания заказа. |
|
Status |
string |
Да |
Статус заказа. Допустимые статусы заказов перечислены в секции справочников. |
|
Currency |
string |
Да |
Трёхбуквенный код валюты заказа. Коды используемых валют перечислены в секции справочников. |
|
Type |
int |
Да |
Тип заказа. |
|
LineCount |
Int |
Да |
Количество позиций в заказе. Может отличаться от количества позиций в отгрузочных документах, так как в них один товар может быть разбит на несколько строк с различными ГТД. |
|
GoodsCount |
Int |
Да |
Количество товаров в заказе. |
|
Sum |
decimal |
Да |
Общая стоимость всего заказа. |
|
InvoiceId |
string |
Нет |
Номер накладной ТОРГ-12. |
|
InvoiceDate |
dateTime |
Нет |
Дата накладной ТОРГ-12 |
|
PaymentInvoiceId |
String |
Нет |
Номер счёта на оплату |
|
PaymentInvoiceDate |
dateTime |
Нет |
Дата счёта на оплату |
|
UtdUrl |
string |
Нет |
Cсылки на УПД (для заказов) или УКД (для возвратов) |
|
Note |
string |
Нет |
Примечание к заказу |
OrderFullDto
Структура данных, содержащая информацию о заказе и включённых в него товарных позициях.
|
Поле |
Тип данных |
Обязательность |
Описание |
|
Id |
string |
Да |
Уникальный идентификатор заказа. |
|
CreationDate |
dateTime |
Да |
Дата и время создания заказа. |
|
Status |
string |
Да |
Статус заказа. Допустимые статусы заказов перечислены в справочнике статусов заказа. |
|
Currency |
string |
Да |
Трёхбуквенный код валюты заказа. Коды используемых валют перечислены в справочнике валют. |
|
Type |
int |
Да |
Параметр |
|
LineCount |
Int |
Да |
Количество позиций в заказе. Может отличаться от количества позиций в отгрузочных документах, так как в них один товар может быть разбит на несколько строк с различными ГТД. |
|
GoodsCount |
Int |
Да |
Количество товаров в заказе. |
|
Sum |
decimal |
Да |
Общая стоимость всего заказа. |
|
InvoiceId |
String |
Нет |
Номер накладной ТОРГ-12 |
|
InvoiceDate |
dateTime |
Нет |
Дата накладной ТОРГ-12 |
|
PaymentInvoiceId |
String |
Нет |
Номер счёта на оплату |
|
PaymentInvoiceDate |
dateTime |
Нет |
Дата счёта на оплату |
|
Note |
string |
Нет |
Примечание к заказу |
|
Lines |
OrderLineDto |
Да |
Массив товарных позиций, составляющих заказ. |
OrderLineDto
Структура данных, содержащая информацию об одной товарной позиции в заказе. GtdNumber и GtdCountry заполняются и возвращаются в виде (Gtd1,Gtd2) через запятую.
|
Поле |
Тип данных |
Обязательность |
Описание |
|
ItemId |
string |
Да |
Уникальный идентификатор товара, представлющего данную позицию. |
|
Name |
string |
Да |
Наименование товара. |
|
Quantity |
decimal |
Да |
Количество товара. |
|
ReservedQuantity |
decimal |
Да |
Количество зарезервированного товара. |
|
UnitPrice |
decimal |
Да |
Стоимость единицы товара. |
|
TotalPrice |
decimal |
Да |
Общая стоимость товарной позиции. |
|
GtdNumber |
string |
Да |
Номер ГТД товара. |
|
GtdCountry |
string |
Да |
Страна происхождения товара по ГТД. |
OrderLineCreationDto
Структура данных с информацией для создания или обновления товарной позиции в заказе.
|
Поле |
Тип данных |
Обязательность |
Описание |
|
ItemId |
string |
Да |
Артикул товара. |
|
Quantity |
decimal |
Да |
Количество товара для добавления в заказ. |
OrderLineStatusDto
Структура данных с информацией о добавленной товарной позиции.
|
Поле |
Тип данных |
Обязательность |
Описание |
|
OrderedQuantity |
decimal |
Нет |
Количество заказанного товара. |
|
ReservedQuantity |
decimal |
Нет |
Количество зарезервированного товара. |
|
LinesDeleted |
decimal |
Нет |
Количество удалённых позиций. |
|
GoodsDeleted |
decimal |
Нет |
Количество удалённых товаров. |
ArrayOfCompatibilityDto
Структура данных с информацией о совместимости товаров и устройств.
|
Поле |
Тип данных |
Описание |
|
ItemId |
string |
Артикул товара |
|
ModelBrand |
string |
Торговая марка подходящего устройства |
|
ModelCategoryName |
string |
Категория подходящего устройства |
|
ModelName |
string |
Название подходящего устройства |
Словарные значения
Статуса заказов
|
Статус |
Описание |
|
Резервирование |
Заказ находится в процессе наполнения товаром. |
|
Сборка |
Заказ передан складу для сборки и обработки документов. |
|
Отменён |
Заказ отменён в какой-либо момент времени; товар, находящийся в нём, не резервируется. |
|
Отгружен |
Товар собран складом, документы напечатаны. Не учитывается то, отдан ли товар представителю клиента/транспортной компании или ещё ожидает вывоза. |
|
Неизвестный статус |
Загадочный заказ, взявшийся из неоткуда. |
Коды валют
|
Код |
Описание |
|
USD |
Американский доллар. |
|
RUB |
Православный рубль. |
|
KZN |
Казахстанский тенге. |
Ошибки сервиса
Все ошибки выполнения методов передаются вызывающей стороне в виде Soap-Fault. В поле faultcode ответа содержится код возникшей ошибки, в поле faultstring – описание ошибки или причина её возникновения. Коды ошибок перечислены в следующей таблице:
|
Код ошибки |
Описание |
|
ACCESS_DENIED |
Пользователь с указанной парой login\password не найден. |
|
NON_AUTHORIZED |
У пользователя недостаточно прав для выполнения запрошенной операции. |
|
BUSINESS_LOGIC_ERRROR |
Ошибка выполнения бизнес-операции. Причина ошибки передаётся в поле faultstring ответа. |
|
CONTRACT_ERROR |
Один или несколько параметров вызова метода имеют некорректные значения. Описание содержится в поле faultstring ответа. |
|
TECHNICAL_ERROR |
Запрос не может быть выполнен по техническим причинам. |