Сервис интеграции реализован с использованием SOAP и предоставляет клиентам API для управления заказами.

Подключение

Адрес подключения

http://api.vtt.ru:8048/Portal.svc?singleWsdl

Аутентификация и авторизация

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

Некоторые методы требуют наличия у пользователя права на редактирование заказов.

Параметры, передаваемые в методы сервиса для аутентификации и авторизации:

Параметр Тип данных Описание
login string Логин и пароль для доступа к методам сервиса. Выдаются клиенту менеджером.
password string  

Операции

GetItems

Операция возвращает список товаров с полной информацией о товарах, доступных для заказа в ВТТ.
Доступна только аутентифицированным пользователям.

Входные параметры: логин и пароль пользователя.
Результат: список объектов ItemDto.

GetRuntimeItems

Операция возвращает оперативную информацию о товарах, доступных для заказа в ВТТ. К оперативным данным относятся идентификатор товара и количества (на складе, в доставке и т.д.) товара для заказа.

Доступна только аутентифицированным пользователям.

Входные параметры: логин и пароль пользователя.
Результат: список объектов ItemRuntimeDto.

GetItemsPortion

Операция возвращает порцию товаров, ограниченную входными параметрами. Может использоваться для получения списка товаров в несколько запросов, так как набор данных, возвращаемый 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

OrderLineCreationDto

Массив объектов с описанием позиций создаваемого заказа.

 

Результат: строковый идентификатор созданного заказа.

AddItem

Операция добавления товарной позиции в указанный заказ, имеющий статус «Резервирование» (см. список статусов заказов).

Доступна только аутентифицированным пользователям, имеющим право на редактирование заказов.

Входные параметры:

Параметр

Тип данных

Описание

login

string

Логин и пароль для доступа к методам сервиса.

password

string

orderId

String

Идентификатор заказа, в который добавляются товары.

lines

OrderLineCreationDto

Массив объектов с описанием товаров для заказа.

 

Результат: структура данных типа OrderLineStatusDto, описывающая результат добавления товара в заказ.

RemoveItem

Операция удаления товара из состава указанного заказа, имеющего статус «Резервирование» (см. список статусов заказов).

Доступна только аутентифицированным пользователям, имеющим право на редактирование заказов.

Входные параметры:

Параметр

Тип данных

Описание

login

string

Логин и пароль для доступа к методам сервиса.

password

string

orderId

string

Идентификатор заказа, в который добавляются товары.

itemId

string

Артикул товара для удаления из заказа.

Результат: операция не возвращает результат.

GetGoodsCompatibilityInformation

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

Доступна только аутентифицированным пользователям, имеющим право на редактирование заказов.

Входные параметры:

Параметр

Тип данных

Описание

login

string

Логин и пароль для доступа к методам сервиса.

password

string

 Результат: список объектов типа ArrayOfCompatibilityDto.

 

Структуры данных, участвующие в обмене

Все нижеперечисленные типы данных указаны применительно к языку 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 изображения для товара.

OriginalNum

string

Оригинальный номер товара.

Vendor

string

Вендор.

Compatibility

string

Информация о товаре, в том числе о совместимых моделях.

Barcode

string

Штрих-код товара.

MainOfficeQuantity

decimal

Количество единиц товара в наличии в головном офисе компании.

NumberInPackage

decimal

Количество товара в упаковке.

ColorName

string

Цвет.

TransitDate

date

Дата ожидаемого прихода товара.

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

 

OrderFullDto

Структура данных, содержащая информацию о заказе и включённых в него товарных позициях.

Поле

Тип данных

Обязательность

Описание

Id

string

Да

Уникальный идентификатор заказа.

CreationDate

dateTime

Да

Дата и время создания заказа.

Status

string

Да

Статус заказа. Допустимые статусы заказов перечислены в справочнике статусов заказа.

Currency

string

Да

Трёхбуквенный код валюты заказа. Коды используемых валют перечислены в справочнике валют.

Type

int

Да

Параметр

LineCount

Int

Да

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

GoodsCount

Int

Да

Количество товаров в заказе.

Sum

decimal

Да

Общая стоимость всего заказа.

InvoiceId

String

Нет

Номер накладной ТОРГ-12

InvoiceDate

dateTime

Нет

Дата накладной ТОРГ-12

Lines

OrderLineDto

Да

Массив товарных позиций, составляющих заказ.

 

OrderLineDto

Структура данных, содержащая информацию об одной товарной позиции в заказе.

Поле

Тип данных

Обязательность

Описание

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

Запрос не может быть выполнен по техническим причинам.