Veřejné API
Autentizace, oprávnění, limity a přehled endpointů veřejného API Revelor v1 — pro externí integrace, exporty a partnerská řešení.
Všechno, co Revelor odhalí na vašem e-shopu, si můžete vzít i ven. Veřejné API v1 zpřístupňuje provozní stav, metriky vyhledávání, záznamy dotazů, doporučení a data o oblíbených produktech a porovnáních — ve strojově čitelné podobě, kterou zpracuje váš BI nástroj, mailingová platforma nebo interní aplikace.
K čemu API slouží
- Externí integrace — napojení Reveloru na vlastní systémy, dashboardy a reporty.
- Exporty — stažení metrik jako JSON, CSV nebo XLSX pro další zpracování.
- Partnerské integrace — mailingové a personalizační platformy (například Boldem) čtou, kdo si co uložil do oblíbených nebo porovnání, a zpětně do Reveloru zapisují interakce z kampaní.
- Monitoring — automatické hlídání stavu vyhledávače a synchronizace produktů.
Základní adresa
https://<vas-server>/v1
Konkrétní adresu vašeho serveru dostanete při aktivaci.
Autentizace
Všechny endpointy vyžadují Bearer token s prefixem rvlr_:
Authorization: Bearer rvlr_xxxxxxxxxxxxxxxxxxxx
Token je svázaný s konkrétním e-shopem — Revelor z něj sám pozná, o čí data jde.
Klíče vytváří administrátor a plná hodnota tokenu se zobrazí pouze jednou při vytvoření; uložte si ji na bezpečné místo. Klíče lze kdykoli vypsat, přejmenovat, změnit jim oprávnění nebo je deaktivovat.
Oprávnění (scopes)
Každý klíč má přidělený seznam oprávnění. Endpoint mimo rozsah klíče vrací 403 INSUFFICIENT_SCOPE.
| Scope | Co odemyká |
|---|---|
read:health | Stav systému a jeho komponent |
read:metrics | Metriky vyhledávání, výkon a konverze |
read:search | Anonymizované záznamy vyhledávání |
read:recommendations | Doporučení a jejich metriky |
read:favorites | Export oblíbených produktů pro partnery (Boldem) |
read:comparison | Export porovnání produktů pro partnery (Boldem) |
write:favorites | Přidávání a odebírání oblíbených položek |
write:comparison | Přidávání a odebírání položek v porovnání |
Limity a pravidla
Rate limiting. 60 požadavků za minutu na jeden klíč, klouzavé okno. Každá odpověď nese hlavičky X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset (unixový čas resetu okna). Po překročení vrací API 429 Too Many Requests.
Dostupnost dat. Metriky a záznamy vyhledávání jsou dostupné za posledních 30 dní; starší období vrací 422. Výjimkou jsou exporty oblíbených a porovnání — ty vracejí aktuální stav, ne log, a časovým oknem omezené nejsou. Pro pravidelné dotahování používejte parametry since a cursor.
Chybové odpovědi. Všechny chyby mají jednotný tvar:
{
"error": {
"code": "ERROR_CODE",
"message": "Popis chyby",
"request_id": "<request-id>"
}
}
| Kód | HTTP | Význam |
|---|---|---|
UNAUTHORIZED, INVALID_TOKEN | 401 | Chybějící nebo neplatný token |
TOKEN_DISABLED, TOKEN_EXPIRED | 401 | Token deaktivovaný nebo po expiraci |
INSUFFICIENT_SCOPE | 403 | Klíč nemá potřebné oprávnění |
RATE_LIMIT_EXCEEDED | 429 | Překročený limit požadavků |
MISSING_TENANT | 400 | Nelze určit e-shop |
MISSING_PARAM, INVALID_PARAMETER | 400 | Chybějící nebo špatně zadaný parametr |
INVALID_DATE, INVALID_RANGE | 422 | Vadné datum nebo obrácený rozsah |
DATA_RETENTION | 422 | Požadovaná data jsou starší než 30 dní |
INVALID_CURSOR | 422 | Poškozený stránkovací kurzor |
EXPORT_DISABLED | 403 | E-shop nemá export zapnutý |
FEATURE_DISABLED | 404 | Funkce není pro e-shop aktivní |
LIMIT_EXCEEDED | 409 | Dosažen limit položek na zákazníka |
Přehled endpointů
Stav systému
| Endpoint | Co vrací |
|---|---|
GET /v1/health | Celkový stav (ok / degraded / down) a stav jednotlivých komponent — vyhledávač, synchronizace, backend |
GET /v1/health/search-engine | Odezvy vyhledávače (p50/p95/p99), počet zaindexovaných produktů, stav indexů |
GET /v1/health/sync | Poslední úplná a přírůstková synchronizace, plán další, případné chyby |
Metriky a výkon
| Endpoint | Co vrací |
|---|---|
GET /v1/metrics | Souhrn i časová řada — počet vyhledávání, míra dotazů bez výsledku, prokliky, konverze; navíc nejčastější dotazy, dotazy bez výsledku a nejklikanější produkty. Parametry from, to, granularity (hour, day, week, month) |
GET /v1/metrics/export | Stejná data jako soubor ke stažení — format = json, csv nebo xlsx |
GET /v1/search-performance | Průměrná a percentilová doba odezvy vyhledávání, celkový počet dotazů |
GET /v1/conversions | Porovnání konverzí návštěv s vyhledáváním a bez něj, včetně vypočteného přínosu vyhledávání |
Záznamy vyhledávání
GET /v1/search-logs vrací anonymizované záznamy dotazů — text dotazu, čas, počet nalezených výsledků a dobu odezvy. Neobsahují IP adresu ani identifikátor session či uživatele. Parametry from, to, limit (max 1000), offset a zero_results_only pro filtrování dotazů bez výsledku.
Doporučení
| Endpoint | Co vrací |
|---|---|
GET /v1/recommendations | Doporučené produkty pro pozici product_detail, cart nebo homepage. Parametry product_id, cart_product_ids, limit (max 20) a lang |
GET /v1/recommendations/metrics | Počet zobrazených doporučení, míra prokliku, konverze a nejklikanější produkty |
Oblíbené a porovnání — čtení
| Endpoint | Co vrací |
|---|---|
GET /v1/favorites | Přírůstkový export oblíbených produktů zákazníků |
GET /v1/comparisons | Přírůstkový export porovnání — skupiny (zákazník, kategorie) s porovnávanými produkty |
Oba exporty používají since, cursor a limit (max 1000); next_cursor je na poslední stránce null. Zákazník je identifikovaný pouze svým Shoptet GUID, export neobsahuje osobní údaje. Exportují se jen záznamy návštěvníků s plným souhlasem a jen pro e-shopy, které export výslovně zapnuly v nastavení — jinak endpoint vrací 403 EXPORT_DISABLED.
Oblíbené a porovnání — zápis
Zápisové endpointy uzavírají smyčku: zákazník si na e-shopu uloží oblíbené produkty, partnerská platforma je přečte, rozešle kampaň a interakce z kampaně zapíše zpět. Zapsaná data se zároveň promítají do doporučování.
| Endpoint | Co dělá |
|---|---|
POST /v1/favorites | Přidá produkt do oblíbených zákazníka |
DELETE /v1/favorites | Odebere produkt z oblíbených (identifikátory jako query parametry) |
POST /v1/comparisons | Přidá produkt do porovnání; kategorie se dopočítá z produktového feedu |
DELETE /v1/comparisons | Odebere produkt z porovnání |
Zápisy jsou idempotentní — opakované přidání vrátí "status": "exists", odebrání neexistující položky "status": "noop". Limity na zákazníka jsou 500 oblíbených a 200 položek v porovnání; jejich překročení vrací 409 LIMIT_EXCEEDED. Zápis vyžaduje pouze zapnutou funkci oblíbených či porovnání na straně e-shopu (jinak 404 FEATURE_DISABLED), nikoli zapnutý export.
Právní základ: zápisy z e-shopu se řídí souhlasem návštěvníka. Partnerské zápisy pracují s výslovně uvedeným zákazníkem na základě právního titulu partnera (typicky souhlas se zasíláním obchodních sdělení, který partner drží).
Ukázky volání
Metriky za období
curl -H "Authorization: Bearer rvlr_xxxxxxxxxxxxxxxxxxxx" \
"https://<vas-server>/v1/metrics?from=2026-01-08&to=2026-01-15&granularity=day"
{
"summary": {
"searches_total": 12543,
"zero_results_rate": 5.2,
"click_through_rate": 34.1,
"conversion_rate": 2.8,
"search_usage_rate": 45.0,
"search_exit_rate": 18.3
},
"timeseries": [
{ "date": "2026-01-08T00:00:00.000Z", "searches": 1832, "zero_results": 95 }
],
"top_queries": [
{ "query": "<dotaz>", "count": 234 }
],
"zero_result_queries": [
{ "query": "<dotaz-bez-vysledku>", "count": 12 }
],
"top_clicked_products": [
{ "product_id": "<product-id>", "clicks": 89 }
]
}
Přidání produktu do oblíbených
curl -X POST "https://<vas-server>/v1/favorites" \
-H "Authorization: Bearer rvlr_xxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"customer_id": "<customer-guid>", "product_guid": "<product-guid>"}'
{
"status": "added",
"customer_id": "<customer-guid>",
"product_guid": "<product-guid>",
"count": 3
}
Tokeny pro agenty a interní nástroje
Vedle klíčů k veřejnému API umí Revelor vydat dlouhodobé tokeny pro AI agenty a interní nástroje — typicky pro asistenta, který hlídá stav vyhledávání, nebo pro skript, který si sám tahá diagnostiku. Tyto tokeny mají čistě čtecí přístup k diagnostickým datům: stav indexu, počet zaindexovaných produktů a čas posledního zaindexování, přehled zapnutých funkcí vyhledávače, statistika dotazů za posledních 7 dní a vzorek dotazů bez výsledku.
Spravují se v administraci: sekce Systém → API tokeny agentů. Založíte nový token, pojmenujete ho, vyberete oprávnění a volitelně nastavíte expiraci. Hodnota tokenu se zobrazí jen jednou — v systému je uložený pouze jeho otisk (SHA-256), samotný token nikde neleží v čitelné podobě. U každého tokenu vidíte, kdy byl naposledy použit, a kdykoli ho můžete deaktivovat. Společný prefix rvlr_ usnadňuje jejich rozpoznání a hlídání v repozitářích.
JavaScript na e-shopu
Část integrace probíhá přímo v šabloně e-shopu. Kodér má k dispozici dvě globální funkce, které Revelor vystavuje a které stačí zavolat ze stávajícího kódu vyhledávacího widgetu:
| Funkce | Kdy ji zavolat |
|---|---|
revelorSearchDone(dotaz, sessionId) | Po každém vyhledávání, jakmile se návštěvníkovi zobrazí výsledky |
revelorSearchClicked() | Po kliknutí na libovolný výsledek vyhledávání |
Z této dvojice si Revelor odvodí míru odchodů z vyhledávání — tedy kolik lidí po vyhledání odešlo, aniž by na cokoli kliklo. Událost se odesílá až při opuštění stránky, spolehlivě i při zavření panelu, a jen tehdy, když návštěvník opravdu hledal a neklikl. Dokud tyto funkce nejsou napojené, dashboard metriku dopočítává náhradním způsobem.
Obdobně lze při kliknutí na výsledek vyhledávání, na doporučený produkt nebo na produkt z úvodní stránky uložit kontext interakce (onRevelorSearchClick, onRevelorRecommendationClick, onRevelorHomepageClick). Revelor pak u vložení do košíku a u objednávky ví, odkud cesta k produktu začala, a v dashboardu se objeví atribuovaný obrat.
Pro veškerý kód na e-shopu platí jedno pravidlo: Revelor nesmí nikdy rozbít e-shop. Volání proto obalte catch, nastavte časový limit a chyby trackingu ignorujte — když Revelor neodpoví, blok se prostě skryje a e-shop běží dál.
Plná specifikace
Kompletní specifikace veřejného API ve formátu OpenAPI — se všemi parametry, schématy odpovědí a chybovými stavy — je k dispozici na vyžádání.