S Scanderm Product API
Документация актуальна

Клиентский Product API

Общий integration guide для Product-проектов Scanderm: только запросы клиентского приложения и основные операции каталога, импорта и магазинов.

Открыть Swagger ↗ Быстрый старт ↓ OpenAPI JSON
Начало работы

Первый авторизованный запрос за три шага

Ключ проекта идентифицирует внешнюю интеграцию, пользовательский JWT — конкретную сессию или пользователя.

1
Получите URL и доступы

URL проекта и необходимые ключи предоставляются отдельно.

2
Получите JWT

Для демо-сессии вызовите POST /auth/guest.

3
Вызовите защищённый метод

Добавьте Authorization: Bearer <access_token>.

bash · guest session 
# 1. Keep the key outside source control
export URL="<URL>"
export API_KEY="<API_KEY>"

# 2. Create a guest session
TOKENS=$(curl -sS -X POST "$URL/auth/guest" \
  -H "X-API-Key: $API_KEY")

ACCESS_TOKEN=$(echo "$TOKENS" | jq -r .access_token)

# 3. Update the profile
curl -sS -X PUT "$URL/me" \
  -H "X-API-Key: $API_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"preferences":{"locale":"ru"}}'
Клиентский контур

Основные сценарии Product-приложения

Документация охватывает клиентские сценарии Product-сервисов и рабочий контур управления ассортиментом.

◎

Пользователи и профили

Гостевые и постоянные сессии, регистрация, login, refresh и профиль.

◉

Анализ кожи

Загрузка фото, face/skin-анализ, SSE-прогресс, история и результаты.

✦

Модули анализа

Лицо, волосы, подбор цвета волос и макияж — набор доступных модулей определяется проектом.

↗

Рекомендации

Персональная выдача товаров по результатам анализа и пользовательским фильтрам.

▦

Каталог и импорт

CRUD товаров, Excel/CSV-импорт, очередь модерации и загрузка изображений.

⌖

Магазины и остатки

Магазины, ближайшая точка, цены, остатки и обновление stock-интеграции.

Авторизация

Три уровня доступа

ProjectApiKey

X-API-Key

Обязателен для всех бизнес-методов. В Swagger вставляется как обычное значение без префикса.

BearerAuth

Authorization: Bearer JWT

Дополнительно требуется для пользовательских данных и анализа.

AdminApiKey

X-Internal-Key

Серверный ключ для CRUD каталога и очереди импорта. Никогда не передавайте его во frontend.

URL, набор модулей и доступы выдаются для каждого проекта отдельно. Серверные ключи нельзя помещать во frontend-код или публичный репозиторий.
Референсный сценарий

Стандартный путь анализа в Product Demo

Полный пользовательский контур: гостевая сессия, анализ с прогрессом, рекомендации и сохраняемый результат. Для интеграции только «фото → JSON» используйте сокращённый прямой нейроанализ ниже.

1

Создать гостя

Получите access_token и refresh_token. Зарегистрированный пользователь может войти через /auth/login.

POST /auth/guest
2

Загрузить фото

Отправьте JPEG, PNG или WebP с Bearer JWT. Ответ сразу вернёт session_id, пока обработка продолжается в фоне.

POST /analysis/upload?module=face
3

Показать прогресс

Подключитесь к SSE по session_id. В браузерном EventSource JWT передаётся через query-параметр token.

GET /analysis/stream/{session_id}
4

Получить рекомендации

Как только в SSE готов снимок метрик, можно параллельно запросить товарную выдачу и передать пользовательские фильтры.

POST /recommendations
5

Сохранить результат

После завершения стрима сохраните метрики и рекомендации. В ответ придёт короткий id для постоянной страницы и QR.

POST /face-results
6

Открыть или передать

Получите сохранённый результат по id. При необходимости отдельно прогрейте PDF или запустите подробный LLM-разбор.

GET /face-results/{result_id}
Важно: /analysis/results/{result_id} и /analysis/history относятся к пользовательскому архиву ML-анализов. /face-results/{result_id} — сохраняемый share-результат с рекомендациями, QR и PDF, который использует стандартный Product Demo.
Пример

Запуск анализа изображения

Запрос сразу возвращает session_id. Готовый результат появляется в истории пользователя.

POST /analysis/upload?module=face 
curl -sS -X POST \
  "$URL/analysis/upload?module=face" \
  -H "X-API-Key: $API_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "file=@selfie.jpg;type=image/jpeg"

# Response
{
  "session_id": "8da5e5c8-...",
  "status": "processing"
}
Товары и остатки

Как подключать каталог или фид

Клиентское приложение читает каталог, а изменение ассортимента выполняется только из доверенного server-side контура.

Чтение каталога

Для витрины и фильтров используйте постраничный список и карточку товара. Эти методы не изменяют ассортимент.

GET /products
GET /products/{product_id}

Готовый server-to-server фид

Проверенный JSON, CSV или Excel можно синхронизировать напрямую. Периодический забор удалённого фида настраивается как проектный адаптер: заранее согласуются формат, идентификатор товара, маппинг полей и частота.

POST /products/import
POST /products/import-csv
POST /products/import-excel

Импорт с модерацией

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

POST /import-queue/upload-*
POST /import-queue/sessions/{id}/commit
Цены и остатки можно получать отдельно по магазинам. Универсального публичного метода «передать URL любого фида» нет: подключение внешнего источника делается на стороне проекта, а X-Internal-Key никогда не передаётся во frontend.
Прямой нейроанализ

Просто отправьте фотографию

Без guest/login, JWT, session_id и предварительной загрузки. REST ждёт полный результат, SSE отдаёт показатели по мере готовности.

REST · полный ответ 
curl -sS -X POST \
  "$URL/neural/analyze" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@selfie.jpg;type=image/jpeg"

# One JSON response after completion
{
  "session_id": "...",
  "status": "done",
  "results": { ... }
}
SSE · поток событий 
curl -N -X POST \
  "$URL/neural/analyze/stream" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@selfie.jpg;type=image/jpeg"

event: session
data: {"session_id":"..."}

event: progress
data: {"task_id":"redness","status":"done"}

event: result
data: {"status":"done","results":{...}}

event: done
Прямой REST/SSE-доступ включается по конфигурации проекта. Поддерживаемые модули и лимит файла уточняются вместе с URL.
API Reference

Все группы методов

Клиентские методы Product-сервисов, опциональные модули и операции каталога/импорта. Параметры и тела запросов доступны в Swagger.

Загружаем OpenAPI-схему…
Схемы и Try it out ↗

Готовы проверить интеграцию?

Откройте Swagger, авторизуйтесь через ProjectApiKey и получите гостевой JWT.

Открыть Swagger ↗