Благовещенск
Аэропорт, Белогорье, Верхнеблаговещенское...

TU.Market API

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

Оглавление:

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

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

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

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

  1. импорт JSON запросом по адресу tu.market/api/import, данные в формате json Пример: см.ниже
  2. импорт из файла FORM-DATA запросом по адресу tu.market/api/importFile, данные в формате json, xml, yml, commerceML, xlsx Пример: см.ниже
    Поддерживает одновременную загрузку фото, в т.ч. в архиве
  3. импорт файлов картинок FORM-DATA запросом по адресу tu.market/api/uploadImportPhotos, в случае их указания для товара|услуги в namePhoto (json, xlsx). Пример: см.ниже
    При указании картинок к товару|услуге ссылками (в linkPhoto) - поддерживается их скачивание (json, xml, yml, commerceML, xlsx).
  4. программа Клиент API - eще один способ автоматизировать загрузку ваших файлов в tu.market
  5. импорт из файла по ссылке. Ссылка на данные и периодичность обновления - указывается на странице «Прайс организации» Интерфейс  см.Автоматическое обновление
    Данные в формате:  json, xml, yml, commerceML, xlsx.
    Для commerceML поддерживается несколько ссылок или ссылка на архив.
Протестируйте ваши данные перед, или в процессе настройки API
Для этого - загрузите ваши данные вручную на странице Прайс организации со включенным переключателем Только проверка (см. Принудительное обновление).
- поддерживается принудительное обновление «из файла» или «по ссылке»
- поддерживаются те же форматы данных (xml, yml, commerceML, xlsx, 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, по разрешению руководителя вашей организации.
 Для тестирования при настройке — используйте «режим проверки» (переключатель или параметр), см. «Тестирование обновлений»
 развернуть
 Обязательное поле при использовании API — идентификатор: «Артикул» (в формате json или excel поле называется «crmID»)

Импорт

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" ]
    }
  ]
}
Поля запроса
  1. firmID
    тип: int
    id фирмы
  2. strFromKA
    тип: string
    произвольный текст с дополнительной информацией. Будет сохранен в отчете об операции.
  3. testMode
    тип: bool
    режим проверки. При значении true данные не будут обновлены.
  4. 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гб — вы можете сделать вручную, на странице Прайса организации (см. Принудительное обновление)
Рекомендуем вам, при возможности, настроить автообновление «только изменений», если у вас большой объем данных и фото. Это существенно сократит ваш интернет-трафик, и нагрузку на вашу сеть.
Поля запроса
  1. 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).

    Поля и их значение, описание и ограничения для указанных форматов файлов - см.по ссылкам внизу.
  2. firmID
    тип: int
    id фирмы
  3. strFromKA
    тип: string
    произвольный текст с дополнительной информацией. Будет сохранен в Отчете о результатах.
  4. testMode
    тип: bool
    режим проверки. При значении true данные не будут обновлены, формируется Отчет (лог) о результатх, без их фактического применения.
Пример ответа
{ "reportID": 2962, "responseStatus": { "code": 200, "description": "Успешно, обновлено 1, без предупреждений. Детали в Отчете: tu.market/client/importReports/2962" } }
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
Поля запроса
  1. firmID
    тип: int
    id фирмы, для которой делается импорт
  2. reportID
    тип: int
    id отчета сессии импорта, для которой загружаются фото. Будут использованы только те имена файлов, которые были указаны при импорте товаров
  3. произвольное количество прикрепленных файлов с изображениями формата jpg или png
    или один zip файл с изображениями. Файлы неподдерживаемых форматов внутри архива будут проигнорированы, названия полей, содержащих файлы, не имеют значения
Пример ответа
{ "result": { "сode": 200, "description": "Success" } }
При неуспешной загрузке фото (файл не обнаружен, неверное расширение, и т.д.) - код 503 и сводка с причинами.

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

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

Продолжая использовать наш сайт, вы даете согласие на обработку файлов cookie, которые обеспечивают правильную работу сайта...

Подробнее

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

Наличие и Цену - пожалуйста, уточните у Продавца

False

У Вашего браузера отключены Cookies, поэтому часть функций сайта будут недоступны или будут работать некорректно.