API за данни само за четене и deep-link за активиране от партньора за интегриране на AI агентите на Host Logic във Вашата PMS или платформа за управление на имоти. Тази страница документира само това, което е налично днес — ясно обозначен раздел Roadmap описва какво предстои.
Вземете Вашия API ключ → прочетете използването на места и ценовите сигнали → вградете линка за активиране на хоста във Вашия UI. Това е пълният интеграционен цикъл, наличен днес.
Вземете Вашия API ключ
Станете партньор. След одобрение Host Logic създава Вашия партньорски акаунт и Ви изпраща еднократен линк за разкриване, съдържащ Вашия hlk_ API ключ. Съхранявайте го сигурно — след разкриването той не може да бъде показан отново.
Прочетете използването и ценовите сигнали
Извикайте GET /partner-api/v1/usage, за да следите потреблението на места, и GET /partner-api/v1/properties/{id}/pricing-signals, за да визуализирате данните за ценообразуване на Marcus във Вашата платформа.
Вградете линка за активиране
Добавете бутон във Вашия UI, който отваря HMAC-подписания deep-link https://hostlogic.io/partner/{slug}/activate?token=…. Хостът избира продукти, неговият акаунт в Host Logic се създава и Laura е готова.
curl https://api.hostlogic.io/partner-api/v1/usage \
-H "Authorization: Bearer hlk_your_key_here" \
-H "Accept: application/json"
# 200 OK — ключът е валиден, отговорът съдържа използването на Вашите места
# 401 Unauthorized — липсващ или невалиден ключ
# 403 Forbidden — ключът е валиден, но липсва изискван scope
# 429 Too Many Requests — ограничение на заявките (120 заявки/мин)Всички API заявки изискват Bearer token в заглавката Authorization. Получавате Вашия API ключ след одобрение за партньор чрез еднократен линк за разкриване — обикновеният ключ никога не се съхранява на сървъра и не може да бъде показан повторно.
API ключовете започват с hlk_, обвързани са с Вашия партньорски акаунт и могат да бъдат ротиранe без прекъсване на услугата. Всеки ключ има набор от scopes, които определят кои крайни точки може да извиква. Първите 12 знака на всеки ключ (префиксът на ключа) се съхраняват в открит текст за идентификация в логовете — останалата част е хеширана.
https://api.hostlogic.io/partner-api/v1
Sandbox / DEV:https://api-dev.hostlogic.io/partner-api/v1
120 заявки/минута на API ключ. При превишаване се връща 429 Too Many Requests.
metrics:read — винаги предоставен; обхваща крайната точка за използване.marcus:read — предоставя се, когато Вашето партньорско споразумение включва данни на Marcus (Revenue Manager); обхваща крайните точки properties и pricing-signals.
| Код | Значение |
|---|---|
401 | Липсващ или невалиден API ключ |
403 | Ключът е валиден, но липсва необходимият scope за тази крайна точка |
404 | Ресурсът не е намерен или не е собственост на Вашия партньорски акаунт |
429 | Превишен е лимитът на заявките — 120 заявки/мин |
curl https://api.hostlogic.io/partner-api/v1/usage \
-H "Authorization: Bearer hlk_a8f3c2e1b4d5..." \
-H "Accept: application/json"curl https://api.hostlogic.io/partner-api/v1/usage \
-H "X-Enterprise-Key: hlk_a8f3c2e1b4d5..." \
-H "Accept: application/json"Следните крайни точки и интеграционни модели са в продукционна среда днес. Всичко, изброено тук, е реално и може да бъде извикано с валиден API ключ.
/usage
Използване на места за Вашия партньорски акаунт. Обхват: metrics:read (винаги е предоставен). Вижте пълната справка по-долу.
/properties
Списък с имоти, принадлежащи на Вашите спонсорирани домакини. Обхват: marcus:read. Вижте пълната справка по-долу.
/properties/{propertyId}/pricing-signals
Ценови сигнали на Marcus и предстояща заетост за спонсориран имот. Обхват: marcus:read. Вижте пълната справка по-долу.
Дълбока връзка за активиране на партньор
URL с HMAC подпис, който създава акаунт на спонсориран домакин. Вгражда се във Вашия интерфейс като бутон. Вижте пълната справка по-долу.
Връща броя на активните места на удостоверения партньор с разбивка по домакин. Полезно е за съпоставяне на фактуриране или за изграждане на табло за използване във Вашата платформа.
metrics:read — винаги се предоставя на всички партньорски ключове.
Тази крайна точка връща данни само за удостоверения партньор. Тя никога не приема параметър partner_id в заявката — идентичността идва изцяло от Вашия API ключ.
Разбивката използва непрозрачни потребителски ID на домакини и брой места. Имейл адресите на домакините умишлено са изключени.
curl https://api.hostlogic.io/partner-api/v1/usage \
-H "Authorization: Bearer hlk_a8f3c2e1b4d5..." \
-H "Accept: application/json"{
"partner_id": 1,
"generated_at": "2026-06-01T10:30:00Z",
"active_seats": 7,
"hosts": [
{ "host_user_id": 42, "active_seats": 4 },
{ "host_user_id": 67, "active_seats": 3 }
]
}Връща всички имоти, принадлежащи на домакините, които Вашият партньорски акаунт спонсорира. Използвайте това, за да откриете за кои имоти можете да заявявате ценови сигнали.
marcus:read — предоставя се, когато партньорското Ви споразумение включва data plane на Marcus Revenue Manager.
Всеки запис съдържа вътрешния id на имота (необходим за крайната точка за ценови сигнали) и name на имота. Лични данни на домакина извън името на имота са изключени.
curl https://api.hostlogic.io/partner-api/v1/properties \
-H "Authorization: Bearer hlk_a8f3c2e1b4d5..." \
-H "Accept: application/json"{
"partner_id": 1,
"generated_at": "2026-06-01T10:30:00Z",
"properties": [
{ "id": 12, "name": "Harbour View Apartment" },
{ "id": 17, "name": "Old Town Studio" }
]
}Връща ценови сигнали на Marcus и предстояща заетост за един спонсориран имот. Използвайте стойностите на id на имота, върнати от GET /properties. Връща се 404, ако имотът не е намерен или не е собственост на Вашия партньорски акаунт.
marcus:read
lookback_days (цяло число, по подразбиране 90) — прозорец от историята на резервациите, използван за изчисляване на сигналите.
Обектът signals съдържа ценови индикатори и статистика за резервациите. Точният набор от полета може да се развива, когато Marcus добавя нови източници на данни. Представителният пример по-долу показва полетата, налични при старта — третирайте всички непознати полета като допълващи.
curl "https://api.hostlogic.io/partner-api/v1/properties/12/pricing-signals?lookback_days=90" \
-H "Authorization: Bearer hlk_a8f3c2e1b4d5..." \
-H "Accept: application/json"{
"property_id": 12,
"signals": {
"occupancy_today": 0.75,
"avg_lead_time_days": 18.4,
"avg_stay_nights": 3.2,
"source_mix": {
"booking.com": 0.62,
"direct": 0.38
},
"total_reservations": 87
},
"occupancy_30d": {
"2026-06-01": 0.75,
"2026-06-02": 0.80
}
}Вместо REST заявка, хостовете, спонсорирани от партньор, се въвеждат чрез подписана дълбока връзка. Хостът я отваря, попада на marketplace без цени, където избира продукти, и акаунтът му в Host Logic се създава — спонсориран и без необходимост от отделно плащане.
https://hostlogic.io/partner/{slug}/activate?token=<hmac-signed-token>
Където {slug} е уникалният идентификатор на партньорския Ви акаунт (предоставен при onboarding), а token е HMAC-подписан, краткотраен payload, съдържащ твърдения за идентичността на хоста.
Токените се подписват с HMAC-SHA256, като се използва signing_secret на Вашия партньор (отделен от API ключа Ви). Форматът е:
<base64url-payload>.<sha256-hmac>
Payload-ът съдържа твърдения за идентичността на хоста, timestamp за изтичане от страна на сървъра (exp) и случаен nonce за предотвратяване на повторно използване на токена.
По подразбиране: 1 час. Изтеклите токени се отхвърлят с ясно съобщение за грешка — хостовете трябва да поискат нова връзка. Host Logic препоръчва връзките да се генерират при поискване (напр. когато хостът натисне бутон във Вашия интерфейс), вместо да се съхраняват.
Днес activation токените се генерират чрез административен инструмент от Host Logic при поискване. Самообслужващо генериране на токени от партньора (генериране на токени програмно от Вашия собствен backend) е в Roadmap-а — вижте по-долу.
https://hostlogic.io/partner/previo/activate
?token=eyJjb250YWN0X2VtYWlsIjoiaG9zdEBleGFtcGxlLmNvbSIsImV4cCI6MTc1MDAwMDAwMCwibm9uY2UiOiJhYjEyY2QzNCJ9.a1b2c3d4e5f6...<!-- Simple button — opens in a new tab -->
<a href="{{ $activationUrl }}" target="_blank" class="btn">
Set up AI Receptionist →
</a>{
"contact_email": "[email protected]",
"contact_name": "Hotel Adriatic",
"previo_hotel_id": "779307",
"requested_product_ids": ["laura-receptionist"],
"exp": 1750000000,
"nonce": "ab12cd34"
}| Стъпка | Какво се случва |
|---|---|
| 1. Токенът е потвърден | Host Logic валидира HMAC подписа и проверява срока на валидност. Невалидните или изтеклите токени показват ясна страница с грешка. |
| 2. Marketplace | Хостът попада на marketplace за продукти без цени, обхванат от Вашето партньорско споразумение. Той избира кои продукти да активира. |
| 3. Акаунтът е създаден | Създава се спонсориран хост акаунт в Host Logic (или се свързва, ако имейлът вече съществува). Продуктите се активират без стъпка за плащане. |
| 4. Onboarding | Хостът се насочва през wizard-а на Laura за knowledge base (инструкции за настаняване, често задавани въпроси, предложения за upsell). Laura започва да отговаря на гостите, след като wizard-ът бъде изпратен. |
Следните възможности са планирани или в разработка. Те са изброени тук за прозрачност, за да можете да планирате интеграционния си roadmap. Нито една от тях не може да се извиква към момента — ако разработвате спрямо тях сега, ще получите грешки.
Самообслужващо генериране на токени от партньора
API endpoint или изтегляем SDK фрагмент, който позволява на Вашия backend да генерира подписани activation токени без участието на Host Logic. Днес токените се генерират при поискване чрез административен инструмент.
Write scopes & mutating endpoints
Scopes като marcus:write и pierre:write и REST endpoints за регистриране на имоти (POST /properties), активиране или деактивиране на отделни единици и актуализиране на партньорски настройки.
Webhooks / събития в реално време
Push известия за завършен onboarding, активирана/деактивирана единица и прагове на използване. Регистрирайте webhook URL и получавайте подписани payload-и.
Партньорски self-service портал
Self-service портал с флагове за управление на API ключове, преглед на използването на seat-ове и конфигуриране на разрешени embed origins. В момента е в private beta.
Крайната точка за поддръжка на Pierre
GET /properties/{propertyId}/operational-state — състояние на поддръжка и оперативно състояние за спонсорирано място за настаняване. Изградена е, но е деактивирана чрез feature flag; изисква pierre:read scope. Достъпна е за избрани партньори при поискване.
Вграждане на onboarding iframe
Вградете съветника за конфигуриране на Laura като iframe във Вашия PMS интерфейс, с postMessage събития за напредъка по стъпките и завършването. Зависи от старта на self-service портала за партньори.
Хостван MCP сървър за enterprise
Хоствана MCP крайна точка на mcp.hostlogic.io, която осигурява достъп от Claude Desktop / Cursor до данни, обхванати от партньорския обхват. Архитектурата е планирана; все още не е активна за enterprise партньори.
Enterprise партньорите имат отделен Slack канал с екипа на Host Logic. Свържете се с нас на [email protected], за да обсъдим Вашите изисквания за интеграция и времеви график.
Разкажете ни за Вашия PMS, channel manager или софтуерен продукт за хотелиерството. Преглеждаме партньорските заявки в рамките на 2 работни дни и предоставяме Вашия API ключ и отделен канал за поддръжка.