API e të dhënave vetëm për lexim dhe deep-link-u i aktivizimit për partnerin për integrimin e agjentëve AI të Host Logic në PMS-in tuaj ose në platformën tuaj të menaxhimit të pronave. Kjo faqe dokumenton vetëm atë që është live sot — një seksion i qartë Roadmap mbulon atë që vjen më pas.
Merrni çelësin tuaj API → lexoni përdorimin e vendeve dhe sinjalet e çmimeve → integroni lidhjen e aktivizimit të hostit në UI-në tuaj. Ky është cikli i plotë i integrimit i disponueshëm sot.
Merrni çelësin tuaj API
Bëhuni partner. Pasi të miratohet, Host Logic krijon llogarinë tuaj të partnerit dhe ju dërgon një link njëpërdorimësh zbulimi që përmban çelësin tuaj API hlk_. Ruajeni në mënyrë të sigurt — nuk mund të shfaqet sërish pas zbulimit.
Lexoni përdorimin & sinjalet e çmimeve
Thirrni GET /partner-api/v1/usage për të monitoruar konsumimin e vendeve, dhe GET /partner-api/v1/properties/{id}/pricing-signals për të shfaqur të dhënat e çmimeve Marcus brenda platformës suaj.
Integroni lidhjen e aktivizimit
Shtoni një buton në UI-në tuaj që hap deep-link-un e nënshkruar me HMAC https://hostlogic.io/partner/{slug}/activate?token=…. Host-i zgjedh produktet, llogaria e tij Host Logic konfigurohet dhe Laura është gati.
curl https://api.hostlogic.io/partner-api/v1/usage \
-H "Authorization: Bearer hlk_your_key_here" \
-H "Accept: application/json"
# 200 OK — çelësi është i vlefshëm, përgjigjja përmban përdorimin tuaj të vendeve
# 401 Unauthorized — çelësi mungon ose është i pavlefshëm
# 403 Forbidden — çelësi është i vlefshëm, por mungon scope-i i kërkuar
# 429 Too Many Requests — kufiri i kërkesave (120 kërkesa/min)Të gjitha kërkesat API kërkojnë një token Bearer në header-in Authorization. Ju e merrni çelësin tuaj API pas miratimit si partner përmes një linku njëpërdorimësh zbulimi — çelësi i thjeshtë nuk ruhet kurrë në server dhe nuk mund të rishfaqet.
Çelësat API kanë prefiksin hlk_, janë të lidhur me llogarinë tuaj të partnerit dhe mund të rrotullohen pa ndërprerje. Çdo çelës ka një grup scopes që përcaktojnë se cilat endpoint-e mund të thërrasë. 12 karakteret e para të çdo çelësi (prefiksi i çelësit) ruhen në tekst të thjeshtë për identifikim në log-e — pjesa tjetër është e hash-uar.
https://api.hostlogic.io/partner-api/v1
Sandbox / DEV:https://api-dev.hostlogic.io/partner-api/v1
120 kërkesa/minutë për çdo çelës API. Tejkalimi kthen 429 Too Many Requests.
metrics:read — jepet gjithmonë; mbulon endpoint-in e përdorimit.marcus:read — jepet kur marrëveshja juaj e partnerit përfshin të dhëna Marcus (Revenue Manager); mbulon endpoint-et properties dhe pricing-signals.
| Kodi | Kuptimi |
|---|---|
401 | Çelësi API mungon ose është i pavlefshëm |
403 | Çelësi është i vlefshëm, por mungon scope-i i kërkuar për këtë endpoint |
404 | Burimi nuk u gjet, ose nuk është në pronësi të llogarisë suaj të partnerit |
429 | U tejkalua kufiri i kërkesave — 120 kërkesa/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"Endpoint-et dhe modelet e integrimit më poshtë janë tashmë në prodhim. Gjithçka e listuar këtu është reale dhe mund të thirret me një API key të vlefshëm.
/usage
Përdorimi i vendeve për llogarinë tuaj të partnerit. Scope: metrics:read (jepet gjithmonë). Shihni referencën e plotë më poshtë.
/properties
Liston pronat që u përkasin hostëve tuaj të sponsorizuar. Scope: marcus:read. Shihni referencën e plotë më poshtë.
/properties/{propertyId}/pricing-signals
Sinjalet e çmimeve Marcus dhe zënia e ardhshme për një pronë të sponsorizuar. Scope: marcus:read. Shihni referencën e plotë më poshtë.
Deep-link për aktivizimin e partnerit
URL e nënshkruar me HMAC që krijon një llogari hosti të sponsorizuar. E integruar në UI-në tuaj si buton. Shihni referencën e plotë më poshtë.
Kthen numrin aktiv të vendeve të partnerit të autentikuar, me ndarje sipas hostit. E dobishme për pajtimin e faturimit ose për ndërtimin e një paneli përdorimi brenda platformës suaj.
metrics:read — jepet gjithmonë për të gjitha çelësat e partnerit.
Ky endpoint kthen vetëm të dhëna për partnerin e autentikuar. Nuk pranon kurrë një parametër query partner_id — identiteti vjen tërësisht nga API key juaj.
Ndarja përdor ID të paqarta të përdoruesve të hostit dhe numra vendesh. Email-et e hostëve përjashtohen qëllimisht.
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 }
]
}Kthen të gjitha pronat që u përkasin hostëve të sponsorizuar nga llogaria juaj e partnerit. Përdoreni këtë për të zbuluar se për cilat prona mund të kërkoni sinjale çmimesh.
marcus:read — jepet kur marrëveshja juaj e partnerit përfshin data plane-in e Marcus Revenue Manager.
Çdo hyrje përmban id e brendshme të pronës (e nevojshme për endpoint-in pricing-signals) dhe name e pronës. PII e hostit përtej emrit të pronës përjashtohet.
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" }
]
}Kthen sinjalet e çmimeve Marcus dhe zënien e ardhshme për një pronë të vetme të sponsorizuar. Përdorni vlerat e id të pronës të kthyera nga GET /properties. Kthehet një 404 nëse prona nuk gjendet ose nuk është në pronësi të llogarisë suaj të partnerit.
marcus:read
lookback_days (integer, default 90) — dritarja e historikut të rezervimeve e përdorur për të llogaritur sinjalet.
Objekti signals përmban tregues çmimesh dhe statistika rezervimesh. Grupi i saktë i fushave mund të evoluojë ndërsa Marcus shton burime të reja të dhënash. Shembulli përfaqësues më poshtë tregon fushat e disponueshme në lançim — trajtoni çdo fushë të panjohur si shtesë.
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
}
}Në vend të një thirrjeje REST, hostët e sponsorizuar nga partneri onboardohen përmes një deep-link të nënshkruar. Host-i klikon mbi të, hapet në një marketplace pa çmim ku zgjedh produktet, dhe llogaria e tij Host Logic krijohet — e sponsorizuar dhe pa kërkuar pagesë të veçantë.
https://hostlogic.io/partner/{slug}/activate?token=<hmac-signed-token>
Ku {slug} është identifikuesi unik i llogarisë suaj partnere (i dhënë gjatë onboarding-ut) dhe token është një payload i nënshkruar me HMAC, me jetë të shkurtër, që përmban deklarata të identitetit të host-it.
Token-ët nënshkruhen me HMAC-SHA256 duke përdorur signing_secret të partnerit tuaj (i ndarë nga API key juaj). Formati është:
<base64url-payload>.<sha256-hmac>
Payload-i përmban deklarata të identitetit të host-it, një timestamp skadimi në anën e serverit (exp) dhe një nonce të rastësishëm për të parandaluar ripërdorimin e token-it.
Parazgjedhje: 1 orë. Token-ët e skaduar refuzohen me një mesazh të qartë gabimi — host-ët duhet të kërkojnë një link të ri. Host Logic rekomandon gjenerimin e linkeve sipas kërkesës (p.sh., kur një host klikon një buton në UI-në tuaj) në vend që t’i ruani ato.
Sot, token-ët e aktivizimit gjenerohen përmes një mjeti administrativ nga Host Logic me kërkesë. Gjenerimi i token-ëve nga vetë partneri (duke gjeneruar token-ë programatikisht nga backend-i juaj) është në Roadmap — shihni më poshtë.
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"
}| Hapi | Çfarë ndodh |
|---|---|
| 1. Token-i verifikohet | Host Logic validon nënshkrimin HMAC dhe kontrollon skadimin. Token-ët e pavlefshëm ose të skaduar shfaqin një faqe të qartë gabimi. |
| 2. Tregu | Host-i hapet në një marketplace produktesh pa çmim, të kufizuar sipas marrëveshjes suaj si partner. Ai zgjedh cilat produkte të aktivizojë. |
| 3. Llogaria krijohet | Krijohet një llogari host-i e sponsorizuar në Host Logic (ose lidhet nëse email-i ekziston tashmë). Produktet aktivizohen pa hap pagese. |
| 4. Onboarding | Host-i udhëzohet përmes wizard-it të bazës së njohurive të Laura-s (udhëzime për check-in, FAQ, oferta upsell). Laura fillon t’u përgjigjet mysafirëve sapo wizard-i të dërgohet. |
Aftësitë e mëposhtme janë planifikuar ose janë në zhvillim. Ato renditen këtu për transparencë, në mënyrë që të planifikoni roadmap-in e integrimit tuaj. Asnjë prej tyre nuk mund të thirret sot — ndërtimi mbi to tani do të rezultojë në gabime.
Gjenerimi i token-ëve nga vetë partneri
Një endpoint API ose një fragment SDK i shkarkueshëm që i lejon backend-it tuaj të gjenerojë token-ë të nënshkruar aktivizimi pa përfshirë Host Logic. Sot token-ët gjenerohen me kërkesë përmes një mjeti administrativ.
Write scopes & endpoint-e mutating
Scopes si marcus:write dhe pierre:write dhe endpoint-e REST për të regjistruar prona (POST /properties), për të aktivizuar ose çaktivizuar njësi individuale dhe për të përditësuar cilësimet e partnerit.
Webhooks / evente në kohë reale
Njoftime push për onboarding të përfunduar, njësi të aktivizuar/çaktivizuar dhe pragje përdorimi. Regjistroni një URL webhook dhe merrni payload-e të nënshkruara.
Portali self-service i partnerit
Një portal self-service i kontrolluar me flag për menaxhimin e API keys, shikimin e përdorimit të seat-eve dhe konfigurimin e origjinave të lejuara për embed. Aktualisht në beta private.
Endpointi i mirëmbajtjes Pierre
GET /properties/{propertyId}/operational-state — gjendja e mirëmbajtjes dhe e funksionimit për një pronë të sponsorizuar. I ndërtuar, por i çaktivizuar nga një feature flag; kërkon scope pierre:read. I disponueshëm për partnerë të përzgjedhur me kërkesë.
Integrim i onboarding-ut me iframe
Futni wizard-in e konfigurimit të Laura-s si një iframe në UI-në tuaj të PMS-it, me evente postMessage për ecurinë e hapave dhe përfundimin. Varet nga lançimi i portalit self-service për partnerët.
Server MCP i hostuar për enterprise
Një endpoint MCP i hostuar në mcp.hostlogic.io që ofron akses nga Claude Desktop / Cursor te të dhënat e kufizuara sipas partnerit. Arkitektura është planifikuar; ende nuk është live për partnerët enterprise.
Partnerët enterprise kanë një kanal të dedikuar në Slack me ekipin e Host Logic. Na kontaktoni në [email protected] për të diskutuar kërkesat dhe afatin kohor të integrimit tuaj.
Na tregoni për PMS-in tuaj, channel manager-in ose produktin tuaj të softuerit për hospitality. Ne i shqyrtojmë aplikimet e partnerëve brenda 2 ditëve pune dhe ju ofrojmë API key-n tuaj dhe një kanal të dedikuar mbështetjeje.