Документация. API


Общая информация, принцип интеграции

Чтобы подключить «Online-склад» к поисковой системе Teta.online компания поставщик должна реализовать несложный API.

Для получения информации о товарах система Teta.online отправляет на сервера компаний поставщиков GET-запросы по протоколу HTTP или HTTPS. В этих запросах всегда содержится строка поиска.

В ответ сервера поставщиков должны вернуть результат поиска по своей базе данных товаров в формате XML или JSON. Разумеется, ответ должен строго соответствовать параметрам запроса.

Поиск позиций должен осуществляться по партномерам электронных компонентов и не зависеть от регистра.

Партномер — это каталожный номер электронного компонента, который был присвоен производителем или уникальное общепринятое название товара, используемое на рынке.

В ответе на поисковый запрос не должно быть больше 7 строк с информацией о товарах. Дубликаты строк недопустимы.

Кодировка ответа — UTF-8.

Скорость обработки запроса и передача ответа

Суммарное время обработки запроса, поступившего от системы Teta.online и передачи ответа не должно быть больше 2-x секунд. Если в течение 2 секунд ответ от сервера поставщика не будет получен, то информация о товарах не попадёт в результаты поиска.

Как это работает

Формат GET-запроса

Рассмотрим пример. Предположим на сервер компании поставщика от системы Teta.online поступил GET-запрос, переданный по протоколу HTTPS:

GET https://your-company.ru/?search=B25834&onlyInStock=1&withPrice=1&exactMatch=0

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

Описание параметров запроса. Правила поиска
Параметр Описание Тип, допустимые значения Обязательное?
search Поисковый запрос. Строка поиска.

Максимальная длина — 64 символа.
Поиск позиций должен осуществляться по партномерам электронных компонентов.
Правила поиска определяются параметром exactMatch.
Да
onlyInStock Наличие на складе. Целое число.

Допустимые значения — 0 и 1.
0 — Необходимы все позиции c ценами и без цен.
1 — Требуются только те позиции, которые имеют цены.
Нет
withPrice Наличие информации о цене товара. Целое число.

Допустимые значения — 0 и 1.
0 — Необходимы все позиции c ценами и без цен.
1 — Требуются только те позиции, которые имеют цены.
Нет
exactMatch Указывает на правила поиска — по вхождению подстроки в партномер или точное соответствие. Целое число.

Допустимые значения — 0 и 1.

0 — поиск производится по вхождению значения указанного в search. Например, если необходимо найти товар по запросу ABCD, то компоненты с партнерами 100ABCD8990, XYZABCD и ABCD100 должны удовлетворять запросу.

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

1 — Точное соответствие значению, которое указано в search.
Нет

GET-параметры onlyInStock, withPrice и exactMatch являются необязательными. Если какой-либо из этих параметров отсутствует в запросе, то система должна считать, что его значение равняется 0.



Форматы ответа

В ответ на GET-запрос сервера компаний поставщиков должны вернуть информацию о найденых товарах в формате XML или JSON в кодировке UTF-8.

Формат XML приближен к спецификации «eFind». Отличия заключаются в более строгих требованиях к качеству данных.

Если данные возвращаются в формате XML, то заголовок Content-Type должен быть одним из перечисленных ниже:

Content-Type: text/xml
Content-Type: application/xml
Content-Type: text/xml; charset=utf-8
Content-Type: application/xml; charset=utf-8

Формат JSON позволяет передавать больше информации по сравнению с XML. В ряде случаев передача данных в JSON будет более компактной и эффективной.

Если данные возвращаются в формате JSON, то допустимые заголовоки Content-Type следующие:

Content-Type: application/json
Content-Type: application/json; charset=utf-8

Не забывайте передавать корректный заголовок. Именно он указывает системе какой формат ответа используется.



Ответ в формате XML

Предположим на сервер компании поставщика от системы Teta.online поступил запрос:

GET https://your-company.ru/?search=IRLU9343P&onlyInStock=1

В ответ, сервер может вернуть, например, такой XML-документ (тело ответа):

<data version="2.0">
        <item>
            <mfg>Infineon</mfg>
            <part>IRLU9343PBF</part>
            <note>Полевой транзистор MOSFET</note>
            <img>http://your-company.ru/IRLU9343PBF/img.jpg</img>
            <pdf>http://your-company.ru/IRLU9343PBF/documrnt.pdf</pdf>
            <url>http://your-company.ru/IRLU9343PBF/</url>
            <cr></cr>
            <sku>100002322</sku>
            <cur>RUB</cur>
            <pb qty="1">87.0</pb>
            <pb qty="100">74.0</pb>
            <pb qty="800">60</pb>
            <moq>10</moq>
            <mpq>5</mpq>
            <dc>2019</dc>
            <pkg>TO251-3</pkg>
            <pack>FR-1230</pack>
            <stock>163</stock>
            <instock>1</instock>
            <dlv>10 дней</dlv>
        </item>
        <item>
            <mfg>Infineon</mfg>
            <part>IRLU9343PBF-GN</part>
            <note>Полевой транзистор MOSFET</note>
            <img>http://your-company.ru/IRLU9343PBF-GN/img.jpg</img>
            <pdf>http://your-company.ru/IRLU9343PBF-GN/documrnt.pdf</pdf>
            <url>http://your-company.ru/IRLU9343PBF-GN/</url>
            <cr>IRLU9343PBF-GX10</cr>
            <cr>IRLU9343PBF-GM80</cr>
            <sku>100005445</sku>
            <cur>RUB</cur>
            <pb qty="1">90</pb>
            <pb qty="100">80</pb>
            <pb qty="800">75.45</pb>
            <moq>25</moq>
            <mpq>10</mpq>
            <dc>2018</dc>
            <pkg>TO251-6</pkg>
            <pack>FR-1230</pack>
            <stock>500+</stock>
            <instock>1</instock>
            <dlv></dlv>
        </item>
</data>

Ответ содержит данные о 2-х товарах, в названии которых (в теге <part>) содержится подстрока IRLU9343P.

Если товаров соответствующих поисковому запросу нет, то сервер должен вернуть следующий ответ:

<data version="2.0"></data>
Описание тегов ответа в формате XML
Тег Описание Тип, значения Обязательный?
<mfg> Наименование производителя электронного компонента.
<mfg>Heraeus Sensor</mfg>
String

Максимум 64 символа.
Да
<part> Партномер электронного компонента. По этому параметру должен производится поиск.
<part>ACPL-332J-500E</part>
Не указывайте дополнительную информацию в этом теге. Только партномер.
String

Максимум 64 символа.
Да
<note> Описание электронного компонента.
<note>Корпус из алюминия.</note>
В этом теге следует указать полезную для покупателей информацию — технические характеристики товара или его особенности.
String
Максимум 255 символов.
Нет
<img> Ссылка на изображение с фотографией электронного компонента. String
Максимум 255 символов.
Нет
<pdf> Ссылка на документ в формате pdf c техническим описанием электронного компонента. String
Максимум 255 символов.
Нет
<url> Ссылка на страницу сайта поставщика с подробной информацией о товаре. String
Максимум 255 символов.
Нет
<cr> Партномер аналога электронного компонента. Можно указать несколько аналогов.

<cr>IRLU9343PBF-GX10</cr>
<cr>IRLU9343PBF-GM80</cr>

Следует избегать дубликатов.

Если аналогов нет, то можно не указывать этот тег или передать 1 пустой тег:
<cr></cr>
String
Максимум 32 символа.
Нет
<sku> Особый артикул компонента учётной системы поставщика или технический номер электронного компонента. String
Максимум 64 символа.
Нет
<cur> Буквенный код валюты. Значение этого тега определяет валюту, в которое указаны цены на товар.

Допустимые значения:

RUB — Рубль.
USD — Доллар США.
EUR — Евро.
<cur>RUB</cur>
Примечание. Код валюты RUR является устаревшим, он был исключён из Общероссийского классификатора валют 1 марта 2004 года.
String

3 символа.

Только допустимые значения.
Да

Если есть цена.
<pb qty=""> Информация о стоимости. Зависимость цены от количества электронных компонентов.

Например, компания поставщик продаёт транзисторы IRLU9343PBF. Цена зависит от количества, которое будет заказано:

От 1 штук до 10087 руб. за штуку.
От 100 штук до 80074 руб. за штуку.
От 800 штук — 60 руб. за штуку.

Передать эти условия можно так:
<pb qty="1">87.0</pb>
<pb qty="100">74.0</pb>
<pb qty="800">60</pb>
Если цена не зависит от количества то будет достаточно одной строки:
<pb qty="1">630.50</pb>
Если стоимость неизвестна, то теги <pb qty=""> следует не передавать.
Содержимое тега <pb>:

Тип данных — Float (число в дробной частью).

Число должно быть больше нуля. Разделитель дробной части точка или запятая.
Максимум 2 цифры в дробной части.

Атрибут qty:

Тип — Integer.
Максимальное значение: 4 294 967 295.
Нет
<moq> Минимальное количество товара, которое может быть заказано.

Если тег не указан или пустой, то система будет считать, что минимальное количество доступное для заказа равняется 1.
<moq>20</moq>
Integer

Больше нуля. Максимальное значение: 4 294 967 295.
Да
<mpq> Количество электронных компонентов в упаковке.

Если данной информации нет, то оставьте данные тег пустым или не указываете.
<mpq>10</mpq>
Integer

Больше нуля. Максимальное значение: 4 294 967 295.
Нет
<dc> Год производства товара.
<dc>2017</dc>
Или
<dc>10 ноября 2018</dc>
Рекомендует передавать только год, как целое число.
String
Максимум 20 символов.
Нет
<pkg> Тип корпуса электронного компонета.
<pkg>TO251-3</pkg>
String
Максимум 20 символов.
Нет
<pack> Описание упаковки, в которой продаются электронные компоненты. String
Максимум 20 символов.
Нет
<instock> Флаг, определяющий наличие на складе.

1 — есть на складе.
0 — нет в наличии.

Если указано значение 1, то в теге <stock> следует указать количество товара, которое имеется в наличии на складе.

Если указано значение 0, то содержимое в тега <stock> будет проигнорировано.

Integer

Только допустимые значения.
Да
<stock> Количество товара, которое имеется в наличии на складе и доступно для заказа.

Существует 2 способа передать информацию о количестве товара.

Первый — указать точное количество:
<stock>245</stock>
Это означает, что на складе в наличии 245 штук.

Второй — указать нижнюю границу количества товара, которое есть в наличии:
<stock>500+</stock>
Такой вариант говорит о том, что на данный момент на складе более чем 500 штук. Если товара нет в наличии то данный тег следует оставить пустым:
<stock></stock>
Допустимо 2 варианта:

ПервыйInteger.
Число больше нуля.

ВторойString.
Длина не более 30 символов. Значение должно удовлетворять регулярному выражению: ^[1-9][0-9]*[+]{0,1}$.
Да

В случае наличия товара на складе.
<dlv> Информация о сроке поставки товара на склад поставщика, в случае если его нет в наличии на складе.

Если товара нет на складе, то необходимо указать данные в этом теге.
<dlv>20</dlv>
String

Максимум 64 символа.
Да

Да, если товара нет на складе.
Зарезервированные символы XML

Стандарт XML требует передавать 5 символов ", ', <, > и & особым способом, если они указаны в значениях атрибутов или тегах. Эти символы в соответствии со спецификацией формата XML являются зарезервированными.

<node attribute="Значение атрибута">Содержимое тега</node>

Чтобы передать эти 5 особых символов в значениях атрибутов или тегах их следует заменить на именованную сущность.

Символ Именованная сущность
< &lt;
> &gt;
" &quot;
' &apos;
& &amp;

Например, если вам нужно передать ссылку http://your-company.ru/?item=4223&type=76, в которой присутствует амперсант &, то следует сделать так:

<url>http://your-company.ru/?item=4223&amp;type=76</url>

Рекомендуем проверять корректность XML документа при помощи online-валидатора https://codebeautify.org/xmlvalidator.



Ответ в формате JSON

Предположим на сервер компании поставщика от системы Teta.online поступил запрос:

GET https://your-company.ru/?search=INS-200&onlyInStock=1

В ответ, сервер может вернуть, например, такой JSON документ (тело ответа):

[
   {
      "eid":"3640441",
      "part":"INS-200W-24",
      "manufacturer":"Wenchi & Brothers",
      "category":"DC-AC преобразователи",
      "note":"инвертор напряжения 24В -> 220В 200Вт",
      "img":"http://your-company.ru//INS-200W-24/img",
      "url":"http://your-company.ru/INS-200W-24/info",
      "pdf":"http://your-company.ru//INS-200W-24/pdf",
      "analogues":[],
      "catalogueNumber":"INS001344",
      "currency":"RUB",
      "prices":[
         {
            "price":"2240.00",
            "quantity":1
         },
         {
            "price":"2070.00",
            "quantity":2
         },
         {
            "price":"1900.75",
            "quantity":50
         }
      ],
      "minOrder": 1,
      "quantityPerPack": 1,
      "dateManufacture":"2019, май",
      "typeCase":"Box-120",
      "typePackage":"FR03320-11",
      "inStock":true,
      "stock":"200",
      "delivery":""
   },
   {
      "eid":"3640434",
      "part":"INS-200W-36",
      "manufacturer":"Wenchi & Brothers",
      "category":"DC-AC преобразователи",
      "note":"инвертор напряжения 36В -> 220В 200Вт",
      "img":"http://your-company.ru//INS-200W-36/img",
      "url":"http://your-company.ru/INS-200W-36/info",
      "pdf":"http://your-company.ru//INS-200W-36/pdf",
      "analogues":[
         {
            "part":"INS-200W-36FG",
            "manufacturer":"Wenchi & Brothers",
            "catalogueNumber":"INS001322",
            "eid":"343356643"
         }
      ],
      "catalogueNumber":"INS001344",
      "currency":"RUB",
      "prices":[
         {
            "price":"2540",
            "quantity":1
         },
         {
            "price":"2140.50",
            "quantity":2
         },
         {
            "price":"2020.30",
            "quantity":50
         }
      ],
      "minOrder": 5,
      "quantityPerPack": 1,
      "dateManufacture":"2019, июль",
      "typeCase":"Box-130-12",
      "typePackage":"FR03320-33",
      "inStock":true,
      "stock":"300+",
      "delivery":""
   }
]

Если товаров соответствующих поисковому запросу нет, то сервер должен вернуть пустой массив:

[]

Важно. Обратите внимание на типы данных!
Если тип поля String, то значение должно быть в кавычках.
"manufacturer": "Heraeus Sensor"
Для типа поля Integer, значение следует передавать без кавычек.
"minOrder": 100
В поле "inStock" должно быть значение типа Booleantrue или false. Без кавычек.
"inStock": true
Описание полей JSON-документа
Поле Описание Тип, значения Обязательное?
eid Уникальный идентификатор товара в учётной системе поставщика.
"eid":"3640441"
String
Максимум 64 символа.
Нет
part Партномер электронного компонента. По этому параметру должен производится поиск.
"part": "ACPL-332J-500E"
Не указываете дополнительную информацию в этом поле. Только партномер.
String
Максимум 64 символа.
Да
manufacturer Наименование производителя электронного компонента.
"manufacturer": "Heraeus Sensor"
String
Максимум 64 символов.
Да
category Наименование категории, к которой относится товар.
"category":"Полевые транзисторы"
String
Максимум 128 символов.
Нет
note Описание электронного компонента. В этом поле следует указать полезную для покупателей информацию — технические характеристики товара или его особенности.
"note":"Корпус из алюминия"
String
Максимум 255 символов.
Нет
img Ссылка на изображение с фотографией электронного компонента. String
Максимум 255 символов.
Нет
pdf Ссылка на документ в формате .pdf c техническим описанием электронного компонента. String
Максимум 255 символов.
Нет
url Ссылка на страницу сайта поставщика с подробной информацией о товаре. String
Максимум 255 символов.
Нет
analogues Массив объектов содержащих информацию об аналогах. Максимальное количество элементов в массиве — 10.

Допустимые элементы массива: part, manufacturer, catalogueNumber, eid.

Следует избегать дубликатов.

Если аналогов нет, то можно не указывать это поле или передать пустой массив.
"analogues": []
Array
Нет
currency Буквенный код валюты. Значение этого тега определяет валюту, в которое указаны цены на товар.

Допустимые значения:

RUB — Рубль.
USD — Доллар США.
EUR — Евро.
"currency": "USD"
Примечание. Код валюты RUR является устаревшим, он был исключён из Общероссийского классификатора валют 1 марта 2004 года.
String

3 символа.

Только допустимые значения.
Да

Если есть цена.
prices Массив содержащий информацию о зависимости цен от количества электронных компонентов.

Например, компания поставщик продаёт транзисторы IRLU9343PBF. Цена зависит от количества, которое будет заказано:

От 1 штук до 10087,35 руб. за штуку.
От 100 штук до 80074 руб. за штуку.
От 800 штук — 60 руб. за штуку.

Передать эти условия можно так:
"prices":[
         {
            "price":"87.35",
            "quantity":1
         },
         {
            "price":"74",
            "quantity": 100
         },
         {
            "price":"60",
            "quantity":800
         }
      ]
Если цена не зависит от количества то будет достаточно одного элемента в массиве:
  "prices":[
         {
            "price":"87",
            "quantity":1
         }
      ]
Если цена неизвестна, то поле prices можно не указывать или передать в нём пустой массив:
  "prices":[]
Array

Каждый элемент массива должен содержать 2 поляprice и quantity.

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

Поле quantity должно иметь тип Integer, значение должно быть больше нуля.

В поле price — следует указывать число, у которого может быть дробная часть. Разделитель дробной части — точка или запятая. Максимум 2 цифры в дробной части.
Нет
minOrder Минимальное количество товара, которое может быть заказано.

Если поле не указано или имеет нулевое значение, то система будет считать, что минимальное количество доступное для заказа равняется 1.
"minOrder": 100
Значение должно быть указано без кавычек!
Integer

Больше нуля. Максимальное значение: 4 294 967 295.
Да
quantityPerPack Количество электронных компонентов в упаковке.

Если данной информации нет, то следует указать 0 или не передавать это поле в JSON-документе.
"quantityPerPack": 10
Значение должно быть указано без кавычек!
Integer

Больше нуля. Максимальное значение: 4 294 967 295.
Нет
dateManufacture Год производства товара.
"dateManufacture": "Ноябрь 2018 г."
Рекомендуем передавать только год.
String
Максимум 20 символов.
Нет
typeCase Тип корпуса электронного компонета.
"typeCase": "TO251-3"
String
Максимум 20 символов.
Нет
typePackage Описание упаковки, в которой продаются электронные компоненты. String
Максимум 20 символов.
Нет
inStock Флаг, определяющий наличие на складе.

true — есть на складе.
false — нет в наличии.

Если указано значение true, то в поле stock необходимо указать количество товара, которое имеется в наличии на складе.

Если указано значение false, то содержимое поля stock будет проигнорировано.
"inStock": true
Обратите внимание булевое значение true или false должно быть указано без кавычек!
Boolean
Да
stock Количество товара, которое имеется в наличии на складе в данный момент, и доступно для заказа.

Существует 2 способа передать информацию о количестве товара на складе.

Первый — указать точное количество:
"stock": "245"
Второй — указать нижнюю границу количества товара, которое есть в наличии:
"stock": "500+"
"500+" означает, что на складе более, 500 единиц товара.

Если товара нет в наличии, то поле stock следует оставить пустым:
"stock": ""
String
Максимум 30 символов.

Значение должно удовлетворять регулярному выражению: ^[1-9][0-9]*[+]{0,1}$
Да

В случае наличия товара на складе.
delivery Информация о сроке поставки товара на склад поставщика, в случае если его нет в наличии на складе.

"delivery": "10 дней"
String
Максимум 64 символа.
Да

Если товара нет на складе.