Тестовые ключи¶

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

Что такое тестовый ключ¶

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

Без тарифа и без денег. Тестовая примерка бесплатна. Она не расходует квоту тарифа, не учитывается в дневных потолках и не тарифицируется.
Результат всегда имитированный. Через несколько секунд задача завершается как completed с заглушкой: либо загруженным вами фото, либо фиксированной картинкой-образцом. Ничего не генерируется, провайдер не вызывается.
Это никогда не путь к боевой задаче. Тестовый ключ не читает боевые задачи, а боевой ключ не читает тестовые (см. раздел «Что видит тестовый ключ» ниже).

Виджет магазина показывает значок TEST в шапке окна, когда его ключ — тестовый, чтобы никто не принял тестовую страницу за настоящую.

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

Тестовые ключи выпускаете вы сами, в клиентском портале на https://app.ziex-tryon.com:

Войдите своим боевым секретным ключом. (Тестовым ключом в портал войти нельзя: см. ниже.)
Откройте страницу API-ключей и создайте тестовый ключ. Дайте ему имя и, если нужно, укажите разрешённые хосты (см. раздел «Где работает тестовый ключ» ниже).
Скопируйте секрет. Он показывается один раз, в диалоге создания ключа. Publishable-ключ (pk_test_…) остаётся виден в списке.

Правила:

До 3 тестовых ключей на аккаунт. Создание четвёртого даёт 409 TEST_KEY_LIMIT. Удалите один, чтобы освободить место.
При создании нового аккаунта вместе с ним автоматически может быть выпущен один тестовый ключ; его секрет показывается один раз, вместе с новым аккаунтом.
Тестовый ключ не ротируется. Чтобы заменить его, удалите ключ и создайте другой.
Тестовым ключом нельзя войти в портал: вход отвечает 401 TEST_KEY_NOT_ALLOWED. Так сделано намеренно: тестовый ключ не должен открывать боевые фото магазина. Владелец магазина входит боевым ключом, создаёт тестовые ключи и передаёт один разработчику, которому портал не нужен.

Где работает тестовый ключ¶

Боевой publishable-ключ работает только с собственного домена магазина. Тестовый ключ создан для разработки, поэтому он принимается ещё и:

С хостов разработки: localhost и *.localhost, loopback-адреса (127.0.0.0/8, ::1), частные сети (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) и имена *.test, *.local и *.internal.
Со страницы без origin: Origin: null — так отправляет страница с file:// или iframe в песочнице.
С любого домена вашего аккаунта, с www. и поддоменами.
С собственных разрешённых хостов ключа — списка, который вы задаёте при создании или правке ключа, до 20 хостов, с www. и поддоменами. Укажите там тестовый хост вроде staging.shop.example. Хост пишите только именем; схема, путь и порт убираются. Интернационализованное имя вроде магазин.рф хранится в ASCII-форме.

Боевой ключ с хоста разработки отклоняется. Берите там тестовый ключ. Пошаговая настройка — на странице Локальная разработка.

GET /api/v1/tryon/integration принимает и тестовый ключ. Он отвечает с key.mode, равным "test", и пустым тарифом, а site.allowed следует тем же правилам хостов, так что модуль CMS может проверить тестовый ключ на локальном сайте. GET /api/v1/tryon/domain-check возвращает mode (live или test), который может прочитать publishable-ключ.

Отправьте тестовую примерку¶

Используйте API как с боевым ключом. Три отличия.

1. Фото — только загрузкой. Оба вида тестового ключа требуют, чтобы model_image был data URI. Ссылка даёт 422 PHOTO_UPLOAD_REQUIRED. Изображение одежды может остаться ссылкой. В тестовом режиме ссылки никто не загружает.

2. Вы выбираете, чем закончится задача. Добавьте в тело test_outcome:

`test_outcome`	Результат
`completed` (по умолчанию)	Задача завершается как `completed`.
`failed`	Задача завершается как `failed` с `error_code` `GENERATION_FAILED` и сообщением `TEST: simulated failure`.

Любое другое значение считается completed и никогда не отклоняет запрос. Боевой ключ это поле игнорирует: бесплатно провалить настоящую задачу так нельзя.

3. Вебхуки. webhook_url работает с тестовым секретным ключом и подписывается так же, как для боевой задачи (см. раздел «Вебхук для одного запроса» на странице Вебхуки); ключ pk_test_…, который его отправит, получит 403 WEBHOOK_NOT_ALLOWED, как любой publishable-ключ.

curl -X POST https://api.ziex-tryon.com/api/v1/tryon \
  -H "X-API-Key: tryon_test_YOUR_TEST_KEY" \
  -H "Idempotency-Key: 8d1f0a52c7e94b6f9a3e5c21d4b70f88" \
  -H "User-Agent: MyShop/1.0" \
  -H "Content-Type: application/json" \
  -d '{
        "model_image": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
        "garment_image": "https://shop.example/images/linen-shirt.jpg",
        "category": "tops",
        "test_outcome": "completed"
      }'

Дальше следите за задачей как обычно через GET /api/v1/tryon/status/{job_id}; она завершится за несколько секунд.

Что видит тестовый ключ¶

Два режима никогда не смешиваются, ни в одну сторону.

Тестовый ключ — секретный или publishable — видит только тестовые задачи своего ключа: GET /api/v1/tryon/status/{job_id}, GET /api/v1/tryon/result/{job_id} и GET /api/v1/tryon/attempts/{key}. Список задач секретного тестового ключа (GET /api/v1/tryon/jobs) содержит только его собственные тестовые задачи.
Боевой ключ тестовых задач не видит. Запрос id тестовой задачи боевым ключом даёт 404 NOT_FOUND, а не 403.

В теле вебхука тестовая задача несёт test: true. У эндпоинтов вебхуков тоже есть режим: эндпоинт, созданный в режиме test, получает только события тестовых задач, а эндпоинт в режиме live не получает их вовсе. Для разработки зарегистрируйте отдельный эндпоинт test. См. Вебхуки.

Файлы¶

Фото тестовой задачи хранятся 72 часа, затем удаляются. Боевые фото хранятся 180 дней; тестовые файлы — никогда так долго. Ссылка на результат тестовой задачи после этого может перестать работать, поэтому не сохраняйте её.

Лимиты¶

У тестового ключа свои лимиты, поэтому тестовый трафик из вашего офиса никогда не расходует боевой бюджет этого офиса.

Лимит	Значение
Отправки на адрес клиента, все тестовые ключи	30 в минуту (счётчик отдельный от боевого)
`pk_test_…` на пару (ключ, адрес клиента)	60 созданных задач за 10 минут (боевой: 10)
Почасовой лимит ключа	Собственный у ключа, по умолчанию 100 в час
Квота тарифа, дневные потолки	Нет

Отказ несёт Retry-After, как на странице Лимиты.

Переход на боевые ключи¶

В коде не меняется ничего, кроме ключей: замените тестовые ключи боевыми, а для виджета возьмите боевой pk_…, привязанный к домену магазина. Страница, на которой остался тестовый ключ, показывает значок TEST — это простой способ заметить забытый ключ.