API za podatke samo za branje in aktivacijska globoka povezava za partnerje za integracijo agentov AI Host Logic v vaš PMS ali platformo za upravljanje nepremičnin. Ta stran dokumentira samo to, kar je danes v živo — jasno označen razdelek Roadmap zajema, kaj prihaja naslednje.
Pridobite svoj API ključ → preberite uporabo sedežev in cenovne signale → v svoj vmesnik vgradite aktivacijsko povezavo za gostitelja. To je celoten integracijski tok, ki je na voljo danes.
Pridobite svoj API ključ
Postanite partner. Ko bo vaša prijava odobrena, Host Logic ustvari vaš partnerski račun in vam pošlje enkratno povezavo za razkritje, ki vsebuje vaš API ključ hlk_. Shranite ga varno — po razkritju ga ni mogoče znova prikazati.
Preberite uporabo & cenovne signale
Pokličite GET /partner-api/v1/usage za spremljanje porabe sedežev in GET /partner-api/v1/properties/{id}/pricing-signals za prikaz podatkov o cenah Marcus v vaši platformi.
Vgradite aktivacijsko povezavo
V svoj vmesnik dodajte gumb, ki odpre z HMAC podpisano globoko povezavo https://hostlogic.io/partner/{slug}/activate?token=…. Gostitelj izbere produkte, njegov račun Host Logic je vzpostavljen, Laura pa je pripravljena.
curl https://api.hostlogic.io/partner-api/v1/usage \
-H "Authorization: Bearer hlk_your_key_here" \
-H "Accept: application/json"
# 200 OK — ključ je veljaven, odgovor vsebuje vašo uporabo sedežev
# 401 Unauthorized — ključ manjka ali je neveljaven
# 403 Forbidden — ključ je veljaven, vendar manjka zahtevani obseg
# 429 Too Many Requests — omejitev hitrosti (120 zahtev/min)Vse zahteve API-ja zahtevajo Bearer žeton v glavi Authorization. API ključ prejmete po odobritvi partnerstva prek enkratne povezave za razkritje — goli ključ ni nikoli shranjen na strežniku in ga ni mogoče ponovno prikazati.
API ključi imajo predpono hlk_, so vezani na vaš partnerski račun in jih je mogoče zamenjati brez izpada. Vsak ključ ima nabor obsegov, ki določajo, katere končne točke lahko kliče. Prvih 12 znakov vsakega ključa (predpona ključa) je shranjenih v navadnem besedilu za identifikacijo v dnevnikih — ostalo je zgoščeno.
https://api.hostlogic.io/partner-api/v1
Sandbox / DEV:https://api-dev.hostlogic.io/partner-api/v1
120 zahtev/minuto na API ključ. Ob preseganju se vrne 429 Too Many Requests.
metrics:read — vedno dodeljen; zajema končno točko za uporabo.marcus:read — dodeljen, ko vaša partnerska pogodba vključuje podatke Marcus (Revenue Manager); zajema končni točki properties in pricing-signals.
| Koda | Pomen |
|---|---|
401 | Manjkajoč ali neveljaven API ključ |
403 | Ključ je veljaven, vendar za to končno točko manjka zahtevani obseg |
404 | Vir ne najden ali pa ni v lasti vašega partnerskega računa |
429 | Presežena omejitev hitrosti — 120 zahtevkov/min |
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"Naslednje končne točke in integracijski vzorci so danes že v produkciji. Vse, kar je navedeno tukaj, je resnično in ga je mogoče poklicati z veljavnim API ključem.
/usage
Poraba sedežev za vaš partnerski račun. Obseg: metrics:read (vedno dodeljeno). Glejte celotno referenco spodaj.
/properties
Seznam nepremičnin, ki pripadajo vašim sponzoriranim gostiteljem. Obseg: marcus:read. Glejte celotno referenco spodaj.
/properties/{propertyId}/pricing-signals
Marcusovi cenovni signali in prihajajoča zasedenost za sponzorirano nepremičnino. Obseg: marcus:read. Glejte celotno referenco spodaj.
Globoka povezava za aktivacijo partnerja
URL, podpisan z HMAC, ki omogoči račun sponzoriranega gostitelja. V vaš uporabniški vmesnik je vdelan kot gumb. Glejte celotno referenco spodaj.
Vrne število aktivnih sedežev overjenega partnerja z razčlenitvijo po posameznih gostiteljih. Uporabno za usklajevanje obračunavanja ali za izdelavo nadzorne plošče porabe v vaši platformi.
metrics:read — vedno dodeljeno vsem partnerskim ključem.
Ta končna točka vrne podatke samo za overjenega partnerja. Nikoli ne sprejme poizvedbenega parametra partner_id — identiteta izhaja izključno iz vašega API ključa.
Razčlenitev uporablja neprosojne ID-je uporabnikov gostiteljev in število sedežev. E-poštni naslovi gostiteljev so namerno izključeni.
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 }
]
}Vrne vse nepremičnine, ki pripadajo gostiteljem, ki jih sponzorira vaš partnerski račun. Uporabite to za ugotavljanje, za katere nepremičnine lahko poizvedujete po cenovnih signalih.
marcus:read — dodeljeno, kadar vaša partnerska pogodba vključuje podatkovno plast Marcus Revenue Managerja.
Vsak vnos vsebuje notranji ID nepremičnine id (potreben za končno točko pricing-signals) in ime nepremičnine name. Osebni podatki gostitelja, ki presegajo ime nepremičnine, so izključeni.
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" }
]
}Vrne Marcusove cenovne signale in prihajajočo zasedenost za eno sponzorirano nepremičnino. Uporabite vrednosti ID-ja nepremičnine id, vrnjene z GET /properties. Če nepremičnina ni najdena ali ni v lasti vašega partnerskega računa, se vrne 404.
marcus:read
lookback_days (celo število, privzeto 90) — časovno okno zgodovine rezervacij, uporabljeno za izračun signalov.
Objekt signals vsebuje cenovne kazalnike in statistiko rezervacij. Natančen nabor polj se lahko razvija, ko Marcus dodaja nove podatkovne vire. Spodnji reprezentativni primer prikazuje polja, ki so na voljo ob zagonu — vsa neprepoznana polja obravnavajte kot dodatna.
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
}
}Namesto REST klica se gostitelji, ki jih sponzorira partner, vključijo prek podpisane globoke povezave. Gostitelj jo klikne, pristane na tržnici brez cen, kjer izbere izdelke, njegov račun Host Logic pa se vzpostavi — sponzorirano in brez ločenega plačila.
https://hostlogic.io/partner/{slug}/activate?token=<hmac-signed-token>
Kjer je {slug} edinstveni identifikator vašega partnerskega računa (posredovan ob vključitvi) in je token s HMAC podpisan, kratkotrajni podatkovni paket z zahtevki o identiteti gostitelja.
Žetoni so podpisani s HMAC-SHA256 z uporabo partnerjevega signing_secret (ločeno od vašega API ključa). Oblika je:
<base64url-payload>.<sha256-hmac>
Podatkovni paket vsebuje zahtevke o identiteti gostitelja, časovni žig poteka na strežniški strani (exp) in naključni nonce za preprečevanje ponovne uporabe žetona.
Privzeto: 1 ura. Potekli žetoni so zavrnjeni z jasnim sporočilom o napaki — gostitelji morajo zahtevati novo povezavo. Host Logic priporoča ustvarjanje povezav po potrebi (npr. ko gostitelj klikne gumb v vašem uporabniškem vmesniku) namesto njihovega shranjevanja.
Danes Host Logic aktivacijske žetone na zahtevo generira prek skrbniškega orodja. Samostojno generiranje žetonov s strani partnerja (programsko generiranje žetonov iz vašega lastnega zaledja) je na načrtu — glejte spodaj.
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"
}| Korak | Kaj se zgodi |
|---|---|
| 1. Žeton preverjen | Host Logic preveri podpis HMAC in veljavnost poteka. Neveljavni ali potekli žetoni prikažejo jasno stran z napako. |
| 2. Tržnica | Gostitelj pristane na tržnici izdelkov brez cen, prilagojeni vašemu partnerskemu dogovoru. Izbere, katere izdelke želi aktivirati. |
| 3. Račun vzpostavljen | Ustvari se sponzoriran račun gostitelja Host Logic (ali se poveže, če e-poštni naslov že obstaja). Izdelki se aktivirajo brez koraka plačila. |
| 4. Uvajanje | Gostitelja vodi Laura skozi čarovnika zbirke znanja (navodila za prijavo, pogosta vprašanja, ponudbe za dodatno prodajo). Laura začne odgovarjati gostom, ko je čarovnik oddan. |
Naslednje zmožnosti so načrtovane ali v razvoju. Tukaj so navedene zaradi preglednosti, da lahko načrtujete svojo integracijsko pot. Nobene od njih danes ni mogoče klicati — razvoj proti njim zdaj bo povzročil napake.
Samostojno generiranje žetonov s strani partnerja
Končna točka API-ja ali prenesljiv izrezek SDK-ja, ki vašemu zaledju omogoča generiranje podpisanih aktivacijskih žetonov brez vključevanja Host Logic. Danes se žetoni generirajo na zahtevo prek skrbniškega orodja.
Obsegi za zapisovanje & končne točke za spreminjanje
Obsegi, kot sta marcus:write in pierre:write, ter REST končne točke za registracijo nepremičnin (POST /properties), aktivacijo ali deaktivacijo posameznih enot in posodobitev partnerskih nastavitev.
Webhooki / dogodki v realnem času
Potisna obvestila za dokončano uvajanje, aktivirano/deaktivirano enoto in pragove uporabe. Registrirajte URL webhooka in prejemajte podpisane podatkovne pakete.
Partnerski portal za samostojno upravljanje
Portal za samostojno upravljanje, zaščiten z zastavico, za upravljanje API ključev, ogled porabe sedežev in konfiguracijo dovoljenih izvorov za vdelavo. Trenutno v zasebni beta različici.
Vzdrževalna končna točka za Pierre
GET /properties/{propertyId}/operational-state — vzdrževalno in operativno stanje za sponzorirano nepremičnino. Funkcionalnost je pripravljena, vendar onemogočena z zastavico funkcije; zahteva obseg pierre:read. Na voljo izbranim partnerjem na zahtevo.
Vdelava onboarding vmesnika prek iframe
Čarovnika za konfiguracijo Laura vdelajte kot iframe v svoj PMS vmesnik, z dogodki postMessage za napredovanje po korakih in dokončanje. Odvisno od zagona partnerskega samopostrežnega portala.
Gostujoči MCP strežnik za podjetja
Gostujoča končna točka MCP na mcp.hostlogic.io, ki omogoča dostop do orodij Claude Desktop / Cursor za podatke, vezane na partnerja. Arhitektura je načrtovana; za podjetniške partnerje še ni v živo.
Podjetniški partnerji imajo namenski Slack kanal s ekipo Host Logic. Pišite nam na [email protected], da se pogovorimo o vaših integracijskih zahtevah in časovnici.
Povejte nam več o svojem PMS, channel managerju ali programski opremi za gostinstvo. Vloge partnerjev pregledamo v 2 delovnih dneh ter vam zagotovimo API ključ in namenski kanal za podporo.