Локальная разработка¶

Собирайте и проверяйте интеграцию на своём компьютере, на тестовом хосте или на стенде, не тратя деньги и генерации тарифа: используйте тестовые ключи. Тестовая задача проходит через настоящий API — та же валидация, проверка изображений, идемпотентность и ответы — и заканчивается имитированным результатом.

Получите тестовый ключ¶

Тестовые ключи вы выпускаете сами, в клиентском портале:

Войдите на https://app.ziex-tryon.com своим боевым секретным ключом (tryon_…).
Откройте страницу API Keys и найдите блок тестовых ключей. Создайте ключ; его секрет (tryon_test_…) показывается один раз — скопируйте его сразу. В списке потом остаётся только публичная половина (pk_test_…).
На аккаунт можно завести до 3 тестовых ключей (четвёртый — 409 TEST_KEY_LIMIT). Чтобы заменить ключ, удалите его и создайте другой.

Тестовым ключом нельзя войти в портал (401 TEST_KEY_NOT_ALLOWED). Поэтому вы выпускаете его из сессии боевого ключа и передаёте разработчику, которому портал не нужен.

	Тестовый секретный ключ	Тестовый publishable-ключ
Выглядит как	`tryon_test_` + 32 символа	`pk_test_` + 32 символа
Где использовать	Ваш сервер или локальный скрипт	Страница в браузере
Нужен `Origin` / `Referer`	Нет	Да (но привязанный домен не нужен)

Если тестовые ключи для вашего аккаунта недоступны, ключ отклоняется как неизвестный (401 INVALID_API_KEY), а блок в портале скрыт.

Что делает тестовая примерка¶

Используйте API точно так же, как в Quickstart B, только с тестовым ключом. Отличия:

Без денег и тарифа. Тестовая задача не берёт генерацию, не учитывается в дневных потолках и не занимает ничьих лимитов, а из всей статистики исключена. Возврата нет, потому что ничего не списывалось.
Фото покупателя — только загрузкой, то есть data URI, и для тестового секретного ключа, и для publishable-ключа. Ссылка даёт 422 PHOTO_UPLOAD_REQUIRED. Одежда может быть ссылкой: в тестовом режиме ничего не скачивается.
Результат имитируется. Примерно через 3 секунды задача завершается, а в result_url стоит ваше же загруженное фото или, если это невозможно, фиксированное изображение-заглушка (https://api.ziex-tryon.com/embed/test-result.png). Категория всё равно проверяется: неизвестная даёт 422 CATEGORY_UNSUPPORTED.
Имитация сбоя. Добавьте в тело "test_outcome": "failed"; задача завершится как failed с error_code GENERATION_FAILED. Любое другое значение считается completed. Боевой ключ это поле игнорирует.
Изоляция. Тестовый ключ читает только тестовые задачи своего ключа; боевой ключ тестовых задач не видит, и наоборот. Задача другого режима — 404, а не 403.
Свои лимиты. 30 отправок в минуту на адрес (считаются отдельно от боевого трафика), 60 созданных задач за 10 минут на пару (тестовый publishable-ключ, адрес) и почасовой лимит ключа (по умолчанию 100).
Файлы, загруженные тестовым ключом, удаляются через 72 часа.
Виджет показывает ленту TEST, когда его ключ начинается с pk_test_, а GET /api/v1/tryon/domain-check возвращает "mode": "test".

import base64
import uuid

import requests

API = "https://api.ziex-tryon.com/api/v1/tryon"
HEADERS = {"X-API-Key": "tryon_test_YOUR_TEST_KEY", "User-Agent": "shop-example-dev/1.0"}

with open("shopper.jpg", "rb") as f:
    photo = "data:image/jpeg;base64," + base64.b64encode(f.read()).decode("ascii")

r = requests.post(
    API,
    json={
        "model_image": photo,                       # a test key needs an upload
        "garment_image": "https://shop.example/images/linen-shirt.jpg",
        "category": "tops",
        "test_outcome": "completed",                # or "failed"
    },
    headers={**HEADERS, "Idempotency-Key": uuid.uuid4().hex},
    timeout=60,
)
print(r.status_code, r.json())

Хосты, которые принимает тестовый ключ¶

Запрос из браузера всегда называет свою страницу в заголовке Origin (или Referer). Правило ключа судит именно по этому хосту.

Боевой ключ работает только на своём привязанном домене (сам домен, www. и любой поддомен). Тестовый ключ работает с:

любого хоста разработки, без регистрации:

Хост	Примеры
`localhost` и `*.localhost`	`localhost`, `bitrix.localhost`
`.test`, `.local`, `*.internal`	`shop.test`, `my-shop.local`, `stand.internal`
Loopback и частные IP-адреса	`127.0.0.1`, `[::1]`, `10.0.0.5`, `172.16.4.2`, `192.168.1.10`
Непрозрачный origin `null`	страница, открытая с `file://`, iframe в песочнице

любого домена, зарегистрированного на ваш аккаунт (с www. и поддоменами);
любого хоста из собственного списка ключа allowed_hosts (до 20), который правится в блоке тестовых ключей портала.

Всё остальное — 403 DOMAIN_NOT_ALLOWED. Тестовый publishable-ключ без Origin и Referer вовсе даёт 403 ORIGIN_REQUIRED.

Боевой ключ с хоста разработки отклоняется с 403 DOMAIN_NOT_ALLOWED: на локальной машине берите тестовый ключ.

Как сравниваются хосты¶

Одно и то же правило применяется к Origin, к allowed_hosts и к адресу сайта, который вы передаёте в GET /integration:

Порт игнорируется. http://localhost:3000 и http://localhost:8080 — это один localhost. Не пишите порт в allowed_hosts; если написали, он отбрасывается.
Интернационализованные имена сравниваются так, как их записывает браузер (UTS #46, punycode). магазин.рф хранится и сопоставляется как xn--80aairftm.xn--p1ai, портал показывает оба вида. Верхний регистр, точка в конце и схема убираются; straße.de превращается в xn--strae-oqa.de, как в браузере.
Имя покрывает свой www. и свои поддомены. shop.example допускает и www.shop.example, и staging.shop.example. Подстановки вроде *.shop.example не принимаются: обычное имя их уже покрывает.
IP-адрес совпадает только с самим собой. 203.0.113.5 не допускает 1.203.0.113.5.
В allowed_hosts не больше 20 записей.

Страницы с `file://`¶

Страница, открытая прямо с диска, отправляет Origin: null. Тестовый ключ это принимает, поэтому обычный HTML-файл с ключом pk_test_… работает без веб-сервера. Боевой ключ — нет (403). Раздача той же папки с localhost тоже работает.

Вебхуки на своей машине¶

Вебхук никогда не доставляется на localhost или частный адрес. Доставка отказывается от любого адреса, который не является публичным (loopback, частные диапазоны, link-local и адреса облачных метаданных, а также имена, которые на них разрешаются), и та же проверка идёт при регистрации адреса: непубличный webhook_url — это 422 VALIDATION_ERROR. Отказ не повторяется.

Два способа разрабатывать с вебхуками:

Туннель. Запустите программу-туннель, которая даёт вашему локальному порту публичный HTTPS-адрес, и укажите этот адрес как webhook_url. Так работают приёмники на ноутбуке за роутером.
Опрос. Пока разрабатываете, обойдитесь без вебхука и опрашивайте GET /api/v1/tryon/status/{job_id}. Тестовая задача завершается за несколько секунд, так что это самый быстрый цикл.

Одиночный webhook_url в запросе работает с тестовым секретным ключом и подписывается так же, как боевой. Эндпоинты вебхуков, которые вы регистрируете в портале, имеют режим, live или test, выбираемый при создании: тестовая задача вызывает только эндпоинты test, а боевая — только live. Тестовый publishable-ключ вообще не может отправить webhook_url (403 WEBHOOK_NOT_ALLOWED).

Пример: стенд 1С-Битрикс¶

Разработчик запускает демо 1С-Битрикс на http://bitrix.localhost:8588 и устанавливает модуль Ziex Try-On. Модуль должен проверить, что его ключ можно использовать на этом сайте. Он вызывает GET /api/v1/tryon/integration с тестовым секретным ключом и адресом сайта:

curl -sS 'https://api.ziex-tryon.com/api/v1/tryon/integration?site_url=http://bitrix.localhost:8588' \
  -H 'X-API-Key: tryon_test_YOUR_TEST_KEY' \
  -H 'User-Agent: shop-example-dev/1.0'

{
  "key": { "mode": "test", "publishable_key": "pk_test_…", "domain": null },
  "site": { "url": "http://bitrix.localhost:8588", "host": "bitrix.localhost", "allowed": true, "reason": null },
  "plan": { "name": null, "generations_limit": null, "generations_remaining": null, "generations_used": 0, "resets_at": null }
}

Ответ сокращён: в нём есть ещё имя клиента, адрес виджета и документ с возможностями. Порт игнорируется, а bitrix.localhost — хост разработки, поэтому site.allowed равно true, и модуль может вывести тестовый publishable-ключ в страницу. Виджет затем работает с bitrix.localhost и ключом pk_test_…, показывает ленту TEST, и каждая примерка заканчивается имитированным результатом, не затрагивая тариф.

С тем же адресом сайта и боевым ключом ответ был бы site.allowed: false с site.reason dev_host (для запроса — DOMAIN_NOT_ALLOWED). Когда перейдёте со стенда на настоящий магазин, переключите модуль на боевой секретный ключ и привяжите боевой ключ к домену магазина.

Чек-лист перед запуском¶

Замените pk_test_… на боевой pk_…, а tryon_test_… — на боевой tryon_….
Убедитесь, что боевой ключ привязан к домену магазина: привязка ключа к домену описана в Quickstart A.
Создайте боевые эндпоинты вебхуков или оставьте webhook_url в запросе на публичном адресе.
Уберите секретный ключ из всего, что выполняется в браузере.