TU.Market API

краткое обобщение

Общая информация

На платформе реализован API для импорта данных, который позволяет синхронизировать данные платформы с системами учета на базе 1С, Excel и т.п. посредством HTTP запросов на указанные адреса.
Доступен также готовый клиент для API, который можно настроить для синхронизации товаров по расписанию.

Термины:

JSON - формат обмена данными
YML - стандарт обмена данными от Яндекс
CommerceML - формат выгрузки данных из 1с
XML - язык разметки, на котором основаны YML и CommerceML. В данной статье под XML обычно понимается формат YML с поддержкой дополнительных расширений для ТуМаркета.
POST-запрос - тип HTTP запроса, используемый для загрузки данных на сервер

Варианты импорта

импорт JSON запросом по адресу tu.market/api/import, данные в формате json Пример: см.ниже
импорт из файла FORM-DATA запросом по адресу tu.market/api/importFile, данные в формате json, xml, yml, commerceML, xlsx Пример: см.ниже
Поддерживает одновременную загрузку фото, в т.ч. в архиве
импорт файлов картинок FORM-DATA запросом по адресу tu.market/api/uploadImportPhotos, в случае их указания для товара|услуги в namePhoto (json, xlsx). Пример: см.ниже
При указании картинок к товару|услуге ссылками (в linkPhoto) - поддерживается их скачивание (json, xml, yml, commerceML, xlsx).
программа Клиент API - eще один способ автоматизировать загрузку ваших файлов в tu.market
импорт из файла по ссылке. Ссылка на данные и периодичность обновления - указывается на странице «Прайс организации» Интерфейс см.Автоматическое обновление
Данные в формате: json, xml, yml, commerceML, xlsx.
Для commerceML поддерживается несколько ссылок или ссылка на архив.

Протестируйте ваши данные перед, или в процессе настройки API

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

Обязательное поле при использовании API — идентификатор: «Артикул» (в формате json или excel поле называется «crmID»)

Для блокировки товаров от покупателей — используются значения полей Статус, или Количество, Наличие, Цена. Подробнее об этом — в инструкции к соответсвующему формату фала (xml, yml, commerceML, json)

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

Если у вас возникают трудности с настройкой обмена по API — обратитесь к своим специалистам, или к нашим менеджерам.

Технический специалист сможет настроить выгрузку из вашей 1с или другой программы в наиболее подходящем для вас формате (yml, xml, xls, json, commerceML), и ее автозагрузку одним из предлагаемых и наиболее подходящим для вас способов.

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

Авторизация

Для авторизации используется Basic Access Authentication
HTTP заголовок: Authorization

Значение: Basic {credentials}
где {credentials} - логин:пароль через двоеточие, закодированные в base64.

Логин – телефон или почта, как и при входе на сайт.

Пример:
Логин: user123@tu.market Пароль: user123pass
Заголовок для авторизации:
Authorization: Basic dXNlcjEyM0B0dS5tYXJrZXQ6dXNlcjEyM3Bhc3M=

Аккаунт должен обладать правом "доступ к API": развернуть

— Его назначает «Главный представитель» вашей организации в своем Личном Кабинете.

— Либо менеджер tu.market, по разрешению руководителя вашей организации.

Для тестирования при настройке — используйте «режим проверки» (переключатель или параметр), см. «Тестирование обновлений»

развернуть

Импорт

URL для запроса: https://tu.market/api/import
Тип запроса: POST
Content-Type: application/json

Пример запроса (JSON)

{
"firmID": "16763",
"testMode": true,
"offers": [
{
"ctuID": "473",
"crmCtuID": "10",
"crmCtuName": "Мебель",
"crmID": "t0002",
"idTU": "17110",
"nameTU": "Офисный стул",
"annotationShort": "Офисный стул, цвет серый",
"annotation": "Офисный стул, цвет серый",
"prefPrice": "от",
"priceBase": "500",
"price2": "400",
"si": "шт",
"priceDesc": "примечание к цене",
"dopSiUse": "после примечания",
"dopPrice": "50",
"dopSi": "шт",
"quantity": "1",
"wait": "0",
"status": "(-) заблокировать [КА]",
"ordInCTU": "11",
"characteristics": [
{
"name": "Высота",
"unit": "m",
"values": [
"1"
]
}
],
"namePhoto": [
"photo1.jpg",
"photo2.png"
],
"linkPhoto": [
"https://company.com/photo1.jpg",
"https://company.com/photo2.png"
]
}
]
}

Поля запроса

firmID
тип: int
id фирмы
strFromKA
тип: string
произвольный текст с дополнительной информацией. Будет сохранен в отчете об операции.
testMode
тип: bool
режим проверки. При значении true данные не будут обновлены.
offers
список товаров

См. Детали полей запроса

Пример ответа

{
"reportID": 2962,
"responseStatus": {
"code": 200,
"description": "Успешно, обновлено 1, без предупреждений. Детали в Отчете: tu.market/client/importReports/2962"
}
}

reportID - id отчета.
code – код результата.
description – описание результата.

Коды ответов при импорте

"сode": 200, "description": "Успешно, обновлено 6500, без предупреждений. Детали в Отчете: tu.market/client/importReports/2 "
"сode": 201, "description": "Частично успешно. Из 6500 обновлено 5900, не обновлено 600. Детали в Отчете: tu.market/client/importReports/2"
"сode": 400, "description": "Неуспешно. Данные не обновлены. Детали в Отчете: tu.market/client/importReports/2"
"сode": 500, "description": "Неуспешно. Нет прав доступа или ошибка данных. Детали в Отчете: tu.market/client/importReports/2"

Импорт из файла

URL для запроса: https://tu.market/api/importFile
Тип запроса: POST
Content-Type: multipart/form-data

Максимальный размер запроса к api — 2гб.

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

Рекомендуем вам, при возможности, настроить автообновление «только изменений», если у вас большой объем данных и фото. Это существенно сократит ваш интернет-трафик, и нагрузку на вашу сеть.

Поля запроса

importFile
тип: файл
Прикрепленный файл для импорта (либо несколько файлов, при этом название поля importFile может повторяться). Поддерживаемые форматы:
- JSON (*.json)
- Excel (*.xlsx, *.xls)
- YML (*.yml, *.xml)
- CommerceML - выгрузка из 1с (*.xml). В случае с CommerceML файлов может быть несколько
- Файлы изображений (*.jpg, *.jpeg, *.png). Можно использовать при использовании поля namePhoto в JSON и Excel или при импорте CommerceML. Файлов может быть много.
- Архив (*.zip, *.7z, *.rar)
  Архив можно использовать, чтобы загрузить несколько файлов за раз, в т.ч. включая фото к товарам.
  ● Т.е. при использовании формата commerceML - положите в ваш архив все xml-файлы этой выгрузки, и при необходимости - все файлы фото, указанные для товаров в этой выгрузке, которые нужно загрузить или обновить.
  ● Аналогично и для выгрузок в формате Excel или JSON — положите в ваш архив сам файл выгрузки, и файлы фото для их загрузки или обновления, которые указаны для товаров в этом файле выгрузки в поле namePhoto (имя.расширение; если их несколько для товара - ч\з разделитель или массивом, см.описание этих форматов).
  ● Примечание для выгрузки в формате yml(яндекс-xml): фото для товаров в таком формате можно указать только в виде ссылок на картинки в интернет (см.описание формата), т.е. файлы фото при этом могут загружаться в tu.market только по указанным ссылкам.
  При остальных форматах - также можно указать ссылки на ваши фото в интернет (в поле linkPhoto для json или excel).
Поля и их значение, описание и ограничения для указанных форматов файлов - см.по ссылкам внизу.
firmID
тип: int
id фирмы
strFromKA
тип: string
произвольный текст с дополнительной информацией. Будет сохранен в Отчете о результатах.
testMode
тип: bool
режим проверки. При значении true данные не будут обновлены, формируется Отчет (лог) о результатх, без их фактического применения.

Пример ответа

reportID - id отчета по импорту.
code – код результата.
description – описание результата.

Загрузка фото (json, xlsx)

Дополнительный POST-запрос, используется в случае передачи файлов фото не в одном архиве с файлом загрузки (/api/importFile - см.выше).
Этот запрос выполняется после передачи файла (файлов) загрузки (Excel, JSON, commerceML) первым запросом (/api/importFile - см.выше).

Этот дополнительный запрос делать не нужно, если вы загружаете файлы одним архивом, который уже содержит фото (см.выше - запросе к /api/importFile).

Для форматов Excel, JSON - Названия фото должны быть указаны в файле загрузки в поле namePhoto.

При формате файла загрузки yml(яндекс-xml) - фото для товаров можно указать только в виде ссылок на картинки в интернет (в поле linkPhoto, см.описание формата).

URL для запроса: https://tu.market/api/uploadImportPhotos
Тип запроса: POST
Content-Type: multipart/form-data

Поля запроса

firmID
тип: int
id фирмы, для которой делается импорт
reportID
тип: int
id отчета сессии импорта, для которой загружаются фото. Будут использованы только те имена файлов, которые были указаны при импорте товаров
произвольное количество прикрепленных файлов с изображениями формата jpg или png
или один zip файл с изображениями. Файлы неподдерживаемых форматов внутри архива будут проигнорированы, названия полей, содержащих файлы, не имеют значения

Пример ответа

{ "result": { "сode": 200, "description": "Success" } }

При неуспешной загрузке фото (файл не обнаружен, неверное расширение, и т.д.) - код 503 и сводка с причинами.

Ссылки на описание для форматов и доп.информацию

Описание формата JSON и Excel
Описание формата XML и YML
Описание формата CommerceML
Программа Клиент API
Инструкция Для Excel
Кратко - Содержание блока импорт|экспорт: Принудительное обновление (файлом и по ссылке), Указание ссылки, Автоматическое обновление по ссылке, Отчет о последнем обновлении
Сопоставление категорий (Категорий организации с Категориями маркета)

Возможные проблемы

API возвращает ответ вида
{"reportID":0,"responseStatus":{"code":50x,"description":"Неуспешно. Нет прав доступа или ошибка данных. Детали в Отчете: tu.market/client/importReports/nullReportID"}}
В этом случае первое, что нужно проверить - не заблокирован ли импорт из-за неверно указанной авторизации или прав доступа у используемого аккаунта, или наличие ограничений по тарифу, или каких-то других причин. Информация об этом указана на странице прайса фирмы - в режиме редактирования.
Импорт завершился, но указанные фото не появились в товарах
Самая распространенная причина - имена файлов фото не соответствуют указанным в файле загрузки. Например, в имени файла указан лишний пробел или иное расширения (jpg вместо jpeg итп).
В Отчете (логе) о результатах - указан список таких файлов фото (которые были указаны, но фактически не обнаружены).

TU.Market API

Оглавление:

Общая информация

Варианты импорта

Авторизация

Импорт

Коды ответов при импорте

Импорт из файла

Загрузка фото (json, xlsx)

Ссылки на описание для форматов и доп.информацию

Возможные проблемы