API dati in sola lettura e deep-link di attivazione partner per integrare gli agenti AI di Host Logic nel Suo PMS o nella Sua piattaforma di property management. Questa pagina documenta solo ciò che è attivo oggi — una sezione Roadmap chiaramente etichettata copre ciò che arriverà in seguito.
Ottenga la Sua API key → legga l'utilizzo dei posti e i segnali di pricing → incorpori il link di attivazione dell'host nella Sua UI. Questo è l'intero flusso di integrazione disponibile oggi.
Ottieni la Sua API key
Diventi partner. Una volta approvato, Host Logic crea il Suo account partner e Le invia un link di rivelazione monouso contenente la Sua API key hlk_. La conservi in modo sicuro — non potrà essere visualizzata di nuovo dopo la rivelazione.
Leggi utilizzo & segnali di pricing
Chiama GET /partner-api/v1/usage per monitorare il consumo dei posti e GET /partner-api/v1/properties/{id}/pricing-signals per mostrare i dati di pricing Marcus all'interno della Sua piattaforma.
Incorpora il link di attivazione
Aggiunga un pulsante nella Sua UI che apra il deep-link firmato HMAC https://hostlogic.io/partner/{slug}/activate?token=…. L'host seleziona i prodotti, il suo account Host Logic viene provisionato e Laura è pronta.
curl https://api.hostlogic.io/partner-api/v1/usage \
-H "Authorization: Bearer hlk_your_key_here" \
-H "Accept: application/json"
# 200 OK — la chiave è valida, la risposta contiene l'utilizzo dei Suoi posti
# 401 Unauthorized — chiave mancante o non valida
# 403 Forbidden — chiave valida ma scope richiesto mancante
# 429 Too Many Requests — limite di richieste superato (120 req/min)Tutte le richieste API richiedono un Bearer token nell'header Authorization. Ricevi la Sua API key dopo l'approvazione come partner tramite un link di rivelazione monouso — la chiave in chiaro non viene mai memorizzata lato server e non può essere mostrata di nuovo.
Le API key hanno il prefisso hlk_, sono associate al Suo account partner e possono essere ruotate senza interruzioni. Ogni chiave include un insieme di scope che determina quali endpoint può chiamare. I primi 12 caratteri di ogni chiave (il prefisso della chiave) vengono memorizzati in chiaro per l'identificazione nei log — il resto è sottoposto a hash.
https://api.hostlogic.io/partner-api/v1
Sandbox / DEV:https://api-dev.hostlogic.io/partner-api/v1
120 richieste/minuto per API key. Il superamento restituisce 429 Too Many Requests.
metrics:read — sempre concesso; copre l'endpoint usage.marcus:read — concesso quando il Suo accordo partner include i dati Marcus (Revenue Manager); copre gli endpoint properties e pricing-signals.
| Codice | Significato |
|---|---|
401 | API key mancante o non valida |
403 | Chiave valida, ma scope richiesto per questo endpoint mancante |
404 | Risorsa non trovata, oppure non di proprietà del Suo account partner |
429 | Limite di richieste superato — 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"I seguenti endpoint e pattern di integrazione sono già in produzione. Tutto ciò che è elencato qui è reale e richiamabile con una chiave API valida.
/usage
Utilizzo posti per il Suo account partner. Scope: metrics:read (sempre concesso). Vedi riferimento completo qui sotto.
/properties
Elenca le strutture appartenenti ai Suoi host sponsorizzati. Scope: marcus:read. Vedi riferimento completo qui sotto.
/properties/{propertyId}/pricing-signals
Segnali di pricing di Marcus e occupazione imminente per una struttura sponsorizzata. Scope: marcus:read. Vedi riferimento completo qui sotto.
Deep link di attivazione partner
URL firmato con HMAC che provisiona un account host sponsorizzato. Da incorporare nella Sua UI come pulsante. Vedi riferimento completo qui sotto.
Restituisce il numero di posti attivi del partner autenticato con una ripartizione per host. Utile per riconciliare la fatturazione o creare una dashboard di utilizzo all'interno della Sua piattaforma.
metrics:read — sempre concesso a tutte le chiavi partner.
Questo endpoint restituisce solo i dati del partner autenticato. Non accetta mai un parametro di query partner_id — l'identità deriva interamente dalla Sua chiave API.
La ripartizione utilizza ID utente host opachi e conteggi dei posti. Le email degli host sono volutamente escluse.
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 }
]
}Restituisce tutte le strutture appartenenti agli host sponsorizzati dal Suo account partner. Usalo per scoprire quali strutture può interrogare per i segnali di pricing.
marcus:read — concesso quando il Suo accordo partner include il data plane di Marcus Revenue Manager.
Ogni voce contiene l'id interno della struttura (necessario per l'endpoint pricing-signals) e il name della struttura. Sono esclusi i dati PII dell'host oltre al nome della struttura.
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" }
]
}Restituisce i segnali di pricing di Marcus e l'occupazione imminente per una singola struttura sponsorizzata. Usi i valori id della struttura restituiti da GET /properties. Viene restituito un 404 se la struttura non viene trovata o non è di proprietà del Suo account partner.
marcus:read
lookback_days (intero, predefinito 90) — finestra della cronologia delle prenotazioni usata per calcolare i segnali.
L'oggetto signals contiene indicatori di pricing e statistiche sulle prenotazioni. Il set esatto di campi può evolvere man mano che Marcus aggiunge nuove fonti dati. L'esempio rappresentativo qui sotto mostra i campi disponibili al lancio — considera eventuali campi non riconosciuti come aggiuntivi.
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
}
}Invece di una chiamata REST, gli host sponsorizzati dal partner vengono attivati tramite un deep link firmato. L'host lo clicca, atterra su un marketplace senza prezzi dove seleziona i prodotti e il suo account Host Logic viene provisionato — sponsorizzato e senza alcun pagamento separato richiesto.
https://hostlogic.io/partner/{slug}/activate?token=<hmac-signed-token>
Dove {slug} è l'identificativo univoco del Suo account partner (fornito in fase di onboarding) e token è un payload firmato con HMAC e a breve durata che contiene i claim sull'identità dell'host.
I token sono firmati con HMAC-SHA256 usando il signing_secret del Suo partner (separato dalla Sua API key). Il formato è:
<base64url-payload>.<sha256-hmac>
Il payload contiene i claim sull'identità dell'host, un timestamp di scadenza lato server (exp) e un nonce casuale per impedire il riutilizzo del token.
Predefinita: 1 ora. I token scaduti vengono rifiutati con un messaggio di errore chiaro — gli host devono richiedere un nuovo link. Host Logic consiglia di generare i link su richiesta (ad esempio quando un host clicca un pulsante nella Sua UI) invece di memorizzarli.
Oggi, i token di attivazione vengono generati su richiesta da Host Logic tramite uno strumento amministrativo. La generazione self-service dei token da parte del partner (creazione programmatica dei token dal Suo backend) è nella Roadmap — vedi sotto.
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"
}| Passaggio | Cosa succede |
|---|---|
| 1. Token verificato | Host Logic valida la firma HMAC e controlla la scadenza. I token non validi o scaduti mostrano una pagina di errore chiara. |
| 2. Marketplace | L'host arriva su un marketplace di prodotti senza prezzi, limitato al Suo accordo di partnership. Selezioni quali prodotti attivare. |
| 3. Account provisionato | Viene creato un account host Host Logic sponsorizzato (o collegato se l'email esiste già). I prodotti vengono attivati senza passaggio di pagamento. |
| 4. Onboarding | L'host viene guidato nel wizard della knowledge base di Laura (istruzioni per il check-in, FAQ, offerte di upsell). Laura inizia a rispondere agli ospiti una volta completato il wizard. |
Le funzionalità seguenti sono pianificate o in sviluppo. Sono elencate qui per trasparenza, così può pianificare la Sua roadmap di integrazione. Nessuna di queste è chiamabile oggi — sviluppare ora su queste funzionalità genererà errori.
Generazione self-service dei token da parte del partner
Un endpoint API o uno snippet SDK scaricabile che consente al Suo backend di generare token di attivazione firmati senza coinvolgere Host Logic. Oggi i token vengono generati su richiesta tramite uno strumento amministrativo.
Scope di scrittura & endpoint mutativi
Scope come marcus:write e pierre:write ed endpoint REST per registrare le strutture (POST /properties), attivare o disattivare singole unità e aggiornare le impostazioni del partner.
Webhook / eventi in tempo reale
Notifiche push per onboarding completato, unità attivata/disattivata e soglie di utilizzo. Registra un URL webhook e ricevi payload firmati.
Portale self-service per partner
Un portale self-service protetto da flag per gestire le API key, visualizzare l'utilizzo dei posti e configurare gli origin consentiti per l'embedding. Attualmente in beta privata.
Endpoint di manutenzione di Pierre
GET /properties/{propertyId}/operational-state — stato di manutenzione e operativo per una struttura sponsorizzata. Realizzato ma disabilitato tramite un feature flag; richiede lo scope pierre:read. Disponibile per partner selezionati su richiesta.
Integrazione iframe per l'onboarding
Incorpora il wizard di configurazione di Laura come iframe nella UI del Suo PMS, con eventi postMessage per l'avanzamento dei passaggi e il completamento. Dipende dal lancio del portale self-service per i partner.
Server MCP ospitato per enterprise
Un endpoint MCP ospitato su mcp.hostlogic.io che fornisce accesso agli strumenti di Claude Desktop / Cursor ai dati con scope partner. Architettura pianificata; non ancora attivo per i partner enterprise.
I partner enterprise hanno un canale Slack dedicato con il team di Host Logic. Contattaci all'indirizzo [email protected] per discutere i requisiti di integrazione e le tempistiche.
Raccontaci del Suo PMS, channel manager o prodotto software per l'hospitality. Valutiamo le richieste dei partner entro 2 giorni lavorativi e forniamo la Sua API key e un canale di supporto dedicato.