API de date doar-citire și deep-link de activare pentru parteneri, pentru a integra agenții Host Logic în PMS-ul sau platforma dumneavoastră de administrare a proprietăților. Această pagină documentează doar ceea ce este activ astăzi — o secțiune Roadmap etichetată clar acoperă ce urmează.
Obțineți cheia API → citiți utilizarea locurilor și semnalele de tarifare → încorporați link-ul de activare a gazdei în interfața dumneavoastră. Acesta este întregul ciclu de integrare disponibil astăzi.
Obțineți cheia API
Deveniți partener. După aprobare, Host Logic vă creează contul de partener și vă trimite un link de dezvăluire unică ce conține cheia API hlk_. Stocați-o în siguranță — nu mai poate fi afișată din nou după dezvăluire.
Citiți utilizarea și semnalele de tarifare
Apelați GET /partner-api/v1/usage pentru a monitoriza consumul de locuri și GET /partner-api/v1/properties/{id}/pricing-signals pentru a afișa datele de tarifare Marcus în platforma dumneavoastră.
Încorporați link-ul de activare
Adăugați un buton în interfața dumneavoastră care deschide deep-link-ul semnat HMAC https://hostlogic.io/partner/{slug}/activate?token=…. Gazda alege produsele, contul ei Host Logic este provizionat, iar Laura este gata.
curl https://api.hostlogic.io/partner-api/v1/usage \
-H "Authorization: Bearer hlk_your_key_here" \
-H "Accept: application/json"
# 200 OK — cheia este validă, răspunsul conține utilizarea locurilor dumneavoastră
# 401 Unauthorized — cheia lipsește sau este invalidă
# 403 Forbidden — cheia este validă, dar îi lipsește scope-ul necesar
# 429 Too Many Requests — limită de rată depășită (120 req/min)Toate solicitările API necesită un token Bearer în header-ul Authorization. Primiți cheia API după aprobarea ca partener, printr-un link de dezvăluire unică — cheia în text simplu nu este niciodată stocată pe server și nu poate fi afișată din nou.
Cheile API au prefixul hlk_, sunt asociate contului dumneavoastră de partener și pot fi rotite fără întreruperi. Fiecare cheie poartă un set de scope-uri care guvernează ce endpoint-uri poate apela. Primele 12 caractere ale fiecărei chei (prefixul cheii) sunt stocate în text simplu pentru identificare în jurnale — restul este hashuit.
https://api.hostlogic.io/partner-api/v1
Sandbox / DEV:https://api-dev.hostlogic.io/partner-api/v1
120 solicitări/minut per cheie API. Depășirea returnează 429 Too Many Requests.
metrics:read — acordat întotdeauna; acoperă endpoint-ul de utilizare.marcus:read — acordat atunci când acordul dumneavoastră de partener include datele Marcus (Revenue Manager); acoperă endpoint-urile de proprietăți și semnale de tarifare.
| Cod | Semnificație |
|---|---|
401 | Cheie API lipsă sau invalidă |
403 | Cheie validă, dar îi lipsește scope-ul necesar pentru acest endpoint |
404 | Resursă negăsită, sau care nu aparține contului dumneavoastră de partener |
429 | Limită de rată depășită — 120 req/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"Următoarele endpoint-uri și modele de integrare sunt astăzi în producție. Tot ce este listat aici este real și poate fi apelat cu o cheie API validă.
/usage
Utilizarea locurilor pentru contul dumneavoastră de partener. Scope: metrics:read (acordat întotdeauna). Vedeți referința completă mai jos.
/properties
Listează proprietățile care aparțin gazdelor sponsorizate de dumneavoastră. Scope: marcus:read. Vedeți referința completă mai jos.
/properties/{propertyId}/pricing-signals
Semnale de tarifare Marcus și ocuparea viitoare pentru o proprietate sponsorizată. Scope: marcus:read. Vedeți referința completă mai jos.
Deep-link de activare pentru parteneri
URL semnat HMAC care provizionează un cont de gazdă sponsorizată. Încorporat în interfața dumneavoastră ca buton. Vedeți referința completă mai jos.
Returnează numărul de locuri active ale partenerului autentificat, cu o defalcare per gazdă. Util pentru reconcilierea facturării sau construirea unui panou de utilizare în propria platformă.
metrics:read — acordat întotdeauna tuturor cheilor de partener.
Acest endpoint returnează date doar pentru partenerul autentificat. Nu acceptă niciodată un parametru de interogare partner_id — identitatea provine în întregime din cheia dumneavoastră API.
Defalcarea folosește ID-uri opace de utilizator gazdă și numere de locuri. E-mailurile gazdelor sunt excluse intenționat.
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 }
]
}Returnează toate proprietățile care aparțin gazdelor sponsorizate de contul dumneavoastră de partener. Folosiți acest lucru pentru a descoperi ce proprietăți puteți interoga pentru semnale de tarifare.
marcus:read — acordat atunci când acordul dumneavoastră de partener include planul de date Marcus Revenue Manager.
Fiecare intrare conține id-ul intern al proprietății (necesar pentru endpoint-ul de semnale de tarifare) și name-ul proprietății. Datele personale ale gazdei, dincolo de numele proprietății, sunt excluse.
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" }
]
}Returnează semnalele de tarifare Marcus și ocuparea viitoare pentru o singură proprietate sponsorizată. Folosiți valorile id ale proprietății returnate de GET /properties. Se returnează un 404 dacă proprietatea nu este găsită sau nu aparține contului dumneavoastră de partener.
marcus:read
lookback_days (întreg, implicit 90) — fereastra istoricului de rezervări folosită pentru calcularea semnalelor.
Obiectul signals conține indicatori de tarifare și statistici de rezervare. Setul exact de câmpuri poate evolua pe măsură ce Marcus adaugă noi surse de date. Exemplul reprezentativ de mai jos arată câmpurile disponibile la lansare — tratați orice câmp nerecunoscut ca fiind aditiv.
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 loc de un apel REST, gazdele sponsorizate de parteneri sunt integrate printr-un deep-link semnat. Gazda dă clic pe el, ajunge pe un marketplace fără prețuri unde alege produsele, iar contul ei Host Logic este provizionat — sponsorizat și fără a fi necesară o plată separată.
https://hostlogic.io/partner/{slug}/activate?token=<hmac-signed-token>
Unde {slug} este identificatorul unic al contului dumneavoastră de partener (furnizat la integrare), iar token este un payload semnat HMAC, de scurtă durată, care poartă afirmații de identitate a gazdei.
Token-urile sunt semnate cu HMAC-SHA256 folosind signing_secret-ul partenerului dumneavoastră (separat de cheia API). Formatul este:
<base64url-payload>.<sha256-hmac>
Payload-ul poartă afirmații de identitate a gazdei, o marcă temporală de expirare setată server-side (exp) și un nonce aleatoriu pentru a preveni reutilizarea token-ului.
Implicit: 1 oră. Token-urile expirate sunt respinse cu o eroare clară — gazdele trebuie să solicite un link nou. Host Logic recomandă generarea link-urilor la cerere (de ex. când o gazdă dă clic pe un buton în interfața dumneavoastră), nu stocarea lor.
Astăzi, token-urile de activare sunt generate printr-un instrument administrativ de către Host Logic, la cerere. Generarea token-urilor de sine stătător de către partener (generarea programatică a token-urilor din propriul dumneavoastră backend) se află pe Roadmap — vedeți mai jos.
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"
}| Pas | Ce se întâmplă |
|---|---|
| 1. Token verificat | Host Logic validează semnătura HMAC și verifică expirarea. Token-urile invalide sau expirate afișează o pagină de eroare clară. |
| 2. Marketplace | Gazda ajunge pe un marketplace de produse fără prețuri, limitat la acordul dumneavoastră de partener. Alege ce produse să activeze. |
| 3. Cont provizionat | Este creat un cont de gazdă Host Logic sponsorizată (sau asociat, dacă e-mailul există deja). Produsele sunt activate fără niciun pas de plată. |
| 4. Onboarding | Gazda este ghidată prin expertul de bază de cunoștințe al Laurei (instrucțiuni de check-in, întrebări frecvente, oferte de vânzare suplimentară). Laura începe să răspundă oaspeților odată ce expertul este trimis. |
Următoarele funcționalități sunt planificate sau în dezvoltare. Sunt listate aici pentru transparență, ca să vă puteți planifica propriul roadmap de integrare. Niciuna dintre acestea nu poate fi apelată astăzi — construirea unei integrări bazate pe ele acum va genera erori.
Generarea de sine stătător a token-urilor de către parteneri
Un endpoint API sau un fragment de SDK descărcabil care permite backend-ului dumneavoastră să genereze token-uri de activare semnate fără implicarea Host Logic. Astăzi token-urile sunt generate la cerere printr-un instrument administrativ.
Scope-uri de scriere & endpoint-uri de modificare
Scope-uri precum marcus:write și pierre:write, și endpoint-uri REST pentru înregistrarea proprietăților (POST /properties), activarea sau dezactivarea unităților individuale și actualizarea setărilor de partener.
Webhook-uri / evenimente în timp real
Notificări push pentru onboarding finalizat, unitate activată/dezactivată și praguri de utilizare. Înregistrați un URL de webhook și primiți payload-uri semnate.
Portal de sine stătător pentru parteneri
Un portal de sine stătător, controlat printr-un flag, pentru gestionarea cheilor API, vizualizarea utilizării locurilor și configurarea originilor de încorporare permise. Momentan în beta privată.
Endpoint-ul de întreținere Pierre
GET /properties/{propertyId}/operational-state — starea de întreținere și operațională pentru o proprietate sponsorizată. Construit, dar dezactivat printr-un feature flag; necesită scope-ul pierre:read. Disponibil unor parteneri selectați, la cerere.
Încorporare iframe pentru onboarding
Încorporați expertul de configurare al Laurei ca iframe în interfața PMS-ului dumneavoastră, cu evenimente postMessage pentru progresul și finalizarea pașilor. Depinde de lansarea portalului de sine stătător pentru parteneri.
Server MCP găzduit pentru enterprise
Un endpoint MCP găzduit la mcp.hostlogic.io, oferind acces prin unelte Claude Desktop / Cursor la date limitate la partener. Arhitectură planificată; încă nu este activ pentru partenerii enterprise.
Partenerii enterprise au un canal Slack dedicat cu echipa Host Logic. Contactați-ne la [email protected] pentru a discuta cerințele și calendarul integrării dumneavoastră.
Spuneți-ne despre PMS-ul, channel manager-ul sau produsul software de ospitalitate al dumneavoastră. Analizăm cererile de parteneriat în 2 zile lucrătoare și vă oferim cheia API și un canal de suport dedicat.