Поисковый API
Ограниченные токены для поиска
Как создать краткосрочный токен доступа для поиска определённых товаров — только товары в наличии, только доступная цена, только для одного пользователя.
Ограниченные токены для поиска
Ограниченные токены позволяют предоставить клиентам (браузерам, виджетам, третьим сторонам) доступ к поиску только определённых товаров. Например:
- "Покажи товары, которые дешевле $100" (но не дороже)
- "Покажи товары, только в наличии" (но не распроданные)
- "Покажи товары только этого пользователя"
Токены — это краткосрочные и криптографически подписанные. Вы можете создать их на лету для каждого пользователя.
Когда использовать ограниченные токены?
| Ситуация | Использовать? |
|---|---|
| Простой сайт товаров (все видят одно и то же) | Нет, используйте обычный ключ |
| Каждый пользователь видит только свои товары | Да |
| Выдать доступ к поиску третьей стороне, но только для определённых товаров | Да |
| Встроить виджет поиска, и он должен работать только несколько часов | Да |
| Показать клиентам только товары, которые они могут себе позволить | Да |
Как это работает
- На вашем сервере — создайте ограниченный токен для пользователя/клиента
- Отправьте в браузер — передайте токен вместе с HTML (например, в data-атрибут)
- В браузере — используйте этот токен вместо обычного ключа для поиска
- AACsearch проверит — что токен подлинный и не просрочен, применит ограничения
Создание ограниченного токена
На сервере (Node.js, Python, PHP и т.д.)
Создайте ограниченный токен для вашего пользователя/клиента. Этот токен имеет встроенные ограничения — пользователь не может их переопределить.
// Node.js / TypeScript
const token = await createScopedToken({
organizationId: session.organizationId,
indexSlug: "products",
scopedFilter: "price:<100", // Пользователь видит только товары дешевле $100
expiresInSeconds: 3600, // Токен работает 1 час, потом истекает
});
// token = "ss_scoped_abc...123"
// Передайте этот токен в браузер# Python
token = create_scoped_token(
organization_id=session.organization_id,
index_slug="products",
scoped_filter="price:<100", # Только товары дешевле $100
expires_in_seconds=3600, # Токен действует 1 час
)Несколько примеров фильтров
// Только товары в наличии
scopedFilter: "availability:=in_stock"
// Только товары конкретного пользователя
scopedFilter: "seller_id:=user_123"
// Товары в диапазоне цены
scopedFilter: "price:[50..500]"
// Комбинация условий
scopedFilter: "availability:=in_stock && price:<200"Для тестирования — через панель управления
- Search → API Keys → Scoped Tokens
- Create scoped token
- Введите фильтр, срок действия, скопируйте токен
Это хорошо для тестирования, но в продакшене генерируйте токены программно на сервере.
В браузере
Используйте ограниченный токен как обычный ключ поиска:
// JavaScript / TypeScript в браузере
const client = new SearchClient({
baseUrl: "https://app.aacsearch.com",
apiKey: scopedToken, // Токен от сервера
indexSlug: "products",
});
const results = await client.search({
q: "shoes",
filterBy: "brand:=Nike" // Пользователь может добавить свои фильтры
// Финальный фильтр: "brand:=Nike && price:<100" (из ограниченного токена)
});Как работают ограничения
Фильтр из токена всегда применяется вместе с фильтрами браузера. Пользователь не может его переопределить.
Фильтр токена (на сервере): "price:<100"
Фильтр браузера (от пользователя): "brand:=Nike"
Итоговый фильтр: "brand:=Nike && price:<100"Пользователь не может попросить товары дороже $100 — ограничение жёсткое.
Время жизни токена (когда он истекает)
Установите срок действия — после этого токен перестанет работать:
expiresInSeconds: 3600 // Токен работает 1 час
expiresInSeconds: 86400 // Токен работает 1 день| Сценарий | Срок действия |
|---|---|
| Сессия пользователя в приложении | 1–4 часа |
| Одна загрузка страницы | 15–30 минут |
| Встроенный виджет на чужом сайте | 24 часа |
| Тестирование | Не устанавливайте (вечный токен) |
После истечения срока браузер получит ошибку 401 — нужно создать новый токен.
Примеры использования
Пример 1: Каждый пользователь видит только свои товары
// На сервере: когда пользователь логинится
const token = await createScopedToken({
organizationId: session.organizationId,
indexSlug: "products",
scopedFilter: `seller_id:=${session.userId}`, // Только его товары
expiresInSeconds: 4 * 60 * 60, // На 4 часа
});
// Отправьте этот токен в HTML страницы// В браузере: используйте этот токен
const results = await client.search({ q: "laptop" });
// Результаты только товаров этого пользователяПример 2: Встроить виджет с ограничениями
// На сервере: выдаёте ключ для встраивания виджета
const token = await createScopedToken({
organizationId: "partner_org_123",
indexSlug: "products",
scopedFilter: "price:<500 && brand:=MyBrand", // Только товары MyBrand дешевле $500
expiresInSeconds: 30 * 24 * 60 * 60, // На месяц
});
// HTML для встраивания:
// <script src="https://app.aacsearch.com/widget.js"
// data-key="ss_scoped_abc123"
// data-index="products"></script>Безопасность
- Токены подписаны криптографически — подделать их невозможно
- Никогда не помещайте в фильтр конфиденциальные данные (коды скидок, внутренние поля)
- Для очень чувствительных случаев делайте поиск на сервере, не в браузере
- Регулярно обновляйте токены (например, каждый раз при входе пользователя)