Хабаровск
ТУ.Маркет
по товарам и услугам
0 0
ТУ.Маркет
по товарам и услугам
0 0

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 поддерживается несколько ссылок или ссылка на архив.
  6. импорт из 1с на сайт. В вашей 1с прописываете выгрузку на адрес https://tu.market/api/exchange
    Подробнее  здесь
Протестируйте ваши данные перед, или в процессе настройки 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.

В качестве логина и пароля можно использовать два варианта:
1) Те же логин (телефон или почта) и пароль, что используются при входе на сайт.
2) Ключ api, полученный на странице прайса (рекомендуем использовать этот вариант!):  пример
Ключ - используется в качестве пароля, а вместо логина - всегда используется слово "tumarket".
  • Пример:
  • Логин: 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"
     ]
   }
 ]
}
Поля запроса
  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 данные не будут обновлены, формируется Отчет (лог) о результатх, без их фактического применения.
  5. partialImport
    тип: bool
    Режим частичной выгрузки данных. Если установлено значение false, считается, что база товаров импортируется полностью, поэтому товары, которые уже есть на маркете, но отсутствуют в данных импорта, снимаются с публикации. При значении 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, поэтому часть функций сайта будут недоступны или будут работать некорректно.