Идентификация¶

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

Метка интеграции¶

Метка сообщает, какой плагин, модуль или скрипт отправил примерку. Её вид — name/version:

Пример	Кто отправляет
`woocommerce/1.4.0`	Плагин WooCommerce.
`bitrix/0.1.4`	Модуль 1С-Битрикс.
`widget/1.2.0`	Виджет, если вы ничего не задали (`widget/<TryOn.version>`).
`custom/acme-shop`	Ваша собственная интеграция.

Правила для значения:

Имя — от 1 до 32 символов: первым идёт строчная латинская буква или цифра, дальше строчные буквы, цифры, _, . и -.
Знак /.
Версия — от 1 до 32 символов из 0-9, A-Z, a-z, ., + и -.
Всё значение — не длиннее 64 символов. Пробелы по краям отбрасываются.

Регулярное выражение: ^[a-z0-9][a-z0-9_.-]{0,31}/[0-9A-Za-z.+-]{1,32}$.

Неподходящая метка — не ошибка

Значение, которое не подходит (неверный вид, слишком длинное, не строка), молча отбрасывается, и запрос выполняется так, будто вы ничего не передавали. Метка никогда не превратит примерку в 422. В наших логах остаётся пометка, что значение отброшено и почему, но не само значение.

Как её отправить¶

Метка передаётся в одном из трёх мест: в JSON-теле POST /api/v1/tryon, в заголовке X-Ziex-Integration или в параметре запроса ?integration=. Выберите то, что подходит месту вызова.

Откуда	Как	Примечания
Браузер, через виджет	Опция `integration` в `TryOn.init()`; виджет кладёт её в тело `POST /api/v1/tryon`	Без опции виджет отправляет `widget/<TryOn.version>`. См. Справочник виджета.
Браузер, ваш код	Поле `integration` в JSON-теле `POST /api/v1/tryon`	Полю тела не нужен дополнительный заголовок запроса.
Ваш сервер	Заголовок запроса `X-Ziex-Integration` в любом вызове	Только между серверами. См. ниже.
`GET` без preflight	Параметр запроса `?integration=`	Для вызова из браузера, который должен остаться простым запросом.

{
  "model_image": "data:image/jpeg;base64,...",
  "garment_image": "https://shop.example/images/linen-shirt.jpg",
  "category": "tops",
  "integration": "acme-shop/2.4.1"
}

curl https://api.ziex-tryon.com/api/v1/tryon/jobs \
  -H 'X-API-Key: tryon_YOUR_SECRET_KEY' \
  -H 'User-Agent: acme-shop/2.4.1' \
  -H 'X-Ziex-Integration: acme-shop/2.4.1'

Не отправляйте X-Ziex-Integration из браузера

Этого заголовка нет в списке заголовков, которые наш API разрешает в предварительном запросе (preflight) браузера. Страница, которая его добавит, получит отказ ещё до отправки запроса. В браузере используйте поле тела или опцию виджета.

Какое значение берётся, если их несколько:

В POST /api/v1/tryon: сначала поле тела, затем заголовок. ?integration= в POST игнорируется.
В GET: сначала заголовок, затем ?integration=.

Всё, что пришло в допустимом виде, запоминается, поэтому слать метку в каждом вызове не обязательно.

Где видна метка¶

В задаче: метка запроса, создавшего задачу, сохраняется вместе с ней. GET /api/v1/tryon/jobs возвращает её как integration для каждой задачи (null, если метку не прислали или отбросили). Публичный статус одной задачи её не содержит.
В ключе: личный кабинет клиента на странице API Keys показывает последнюю метку, с которой использовался ключ («Last seen»), и время. GET /api/v1/tryon/integration возвращает то же значение как key.last_integration.
В наших логах и административных инструментах — именно их мы читаем, когда вы нам пишете.

Изменившаяся метка (например, после обновления плагина) записывается в ключ один раз, в момент изменения.

Назовите запрос, когда просите о помощи¶

В каждом ответе API есть заголовок X-Request-ID. Назовите его, когда пишете нам (см. Контакты), вместе с меткой, идентификатором задачи (X-Job-Id или job_id из тела) и временем. По идентификатору запроса мы находим именно этот запрос, не гадая.

Страница в браузере может прочитать X-Request-ID на эндпоинтах примерки. Ответы краевого слоя перед API (413, 429, 502, 503, 504) формирует не приложение, и идентификатора запроса в них нет; для них назовите время и идентификатор задачи. См. Ошибки.

Свой `User-Agent`¶

С сервера всегда отправляйте собственный User-Agent, в котором названы ваш магазин и версия. Значение Python по умолчанию (Python-urllib/3.x) краевой слой отклоняет HTML-ответом 403 с ошибкой 1010. См. Краткое руководство B.