Che cosa offre l’API
L’API di Finikos è REST, con risposte JSON. Legge il gestionale per intero, proprietà, prenotazioni, ospiti, check-in e check-out, pulizie, finanza e conversazioni, e scrive in due punti soli: un messaggio all’ospite sulla sua prenotazione e una domanda all’assistente di supporto. È inclusa nel piano Enterprise ed è la stessa API con cui FIRM, il concierge AI, legge la prenotazione e risponde all’ospite.
Serve a chi scrive codice e a chi costruisce flussi con Zapier, Make e n8n. Qualche esempio: un foglio che si aggiorna con le prenotazioni, un avviso quando una tassa di soggiorno resta da pagare, il rendiconto mensile per proprietà, un messaggio di benvenuto che parte dal tuo sistema il giorno dell’arrivo.
Per usare il gestionale da un assistente come Claude o ChatGPT, senza scrivere codice, c’è il server MCP, che legge e basta, senza ospiti né chat: vedi la pagina Server MCP.
Che cosa legge
Nove aree in lettura:
- Proprietà: elenco e scheda, con indirizzo, orari di check-in e check-out, canali collegati e il contatto del proprietario.
- Prenotazioni: filtro per proprietà, stato (confermata, cancellata, in attesa, completata) e date; dettaglio con notti, importi, guadagno netto, tassa di soggiorno, la lingua che Airbnb dichiara per chi prenota e il riepilogo degli ospiti verificati. Per Airbnb e Booking.com, il dettaglio dei costi: pulizie, commissioni, tasse.
- Ospiti di una prenotazione: scheda singola e per prenotazione, con documento e stato del check-in. È l’area del concierge.
- Check-in e check-out: gli arrivi e le partenze di oggi, di una data o di un intervallo.
- Pulizie: quelle di oggi o di una data, per addetta, per proprietà, per prenotazione; completate e in sospeso.
- Riepilogo del giorno: arrivi, partenze, pulizie e i totali, in una chiamata sola.
- Finanza: i conti di una proprietà in un periodo, mese per mese, e il riepilogo di tutte le proprietà, anche per città.
- Utenti e addette alle pulizie: gli elenchi e il programma del giorno di ogni addetta.
- Chat: la conversazione con l’ospite di una prenotazione, testi e immagini, con la data di ogni messaggio.
Che cosa scrive
Due operazioni, nessun’altra. La prima: un messaggio all’ospite sulla conversazione della sua prenotazione, testo oppure immagine, che l’ospite riceve nella chat di Airbnb. Vale per le prenotazioni Airbnb; per le altre l’API risponde che la messaggistica non è disponibile.
A ogni invio puoi allegare una chiave di idempotenza: se la stessa chiave arriva due volte, per un timeout o una ripetizione del flusso, il messaggio parte una volta sola e la seconda chiamata riceve l’esito della prima. Se l’esito del primo invio è incerto, l’API lo dice con un codice suo e non rimanda: meglio un messaggio perso che lo stesso messaggio due volte nella chat dell’ospite.
La seconda: una domanda all’assistente di supporto, che risponde dalla knowledge base. L’API non crea né modifica prenotazioni, non cambia prezzi, non programma pulizie: quello si fa nel gestionale, e le prenotazioni continuano ad arrivare dai canali e dal sito di prenotazione diretta.
Chiave e permessi
La chiave la crei tu, come amministratore, dalle impostazioni del gestionale: le dai un nome, la vedi una volta sola al momento della creazione e la conservi come una password. Dalle stesse impostazioni la rigeneri o la disattivi quando vuoi.
Si invia in un header a ogni chiamata, X-API-Key oppure Authorization: Bearer, e fa due cose insieme: autentica la chiamata e sceglie l’account. Una chiave vede solo i dati del suo account, nessuna sessione e nessun cookie.
La chiave eredita il ruolo di chi la crea. Una chiave da amministratore legge tutte le proprietà e le schede di dettaglio, con utente, proprietà, prenotazione e ospite in un oggetto solo; una chiave creata da un utente senza quel ruolo vede solo le proprietà con FIRM attivo.
Sincronizzazione e formati
Sincronizzazione incrementale: ogni elenco restituisce un syncTimestamp; alla chiamata successiva lo passi come updatedAfter e ricevi solo ciò che è cambiato. Gli elenchi arrivano interi, senza paginazione.
Date nel formato anno-mese-giorno, lette nel fuso di Roma; orari ISO 8601; importi in euro con due decimali. Le risposte sono JSON con un campo success e, in caso di errore, un codice esplicito: parametro non valido, chiave mancante o non valida, proprietà non autorizzata per quella chiave, risorsa non trovata.
Su un errore del server si riprova con attese crescenti; su un parametro non valido si corregge la chiamata e non si riprova uguale. Non c’è un limite globale di chiamate per chiave; le schede di dettaglio portano header informativi sul ritmo consigliato.
Automazioni senza codice
Zapier, Make e n8n chiamano l’API di Finikos come qualsiasi altra fonte REST: una richiesta HTTP con la chiave nell’header, e la risposta JSON da usare nei passi successivi del flusso. Si parte dal modulo HTTP generico di ciascuno strumento, con gli indirizzi che trovi nella documentazione.
In n8n è il nodo HTTP Request, che la documentazione descrive come il modo per interrogare qualsiasi app o servizio con un’API REST, con la credenziale di tipo Header auth per la chiave (pagina di n8n, in inglese). In Zapier, Webhooks by Zapier, dai piani Professional in su, manda richieste a un indirizzo che gli dai, con gli header che servono (pagina di Zapier, in inglese).
Con la sincronizzazione incrementale un flusso che gira ogni ora chiede solo le prenotazioni cambiate dall’ultima esecuzione; con l’invio dei messaggi lo stesso flusso può scrivere all’ospite, con la chiave di idempotenza per non scrivergli due volte.
FIRM con un altro gestionale
FIRM lavora attraverso questa API: legge proprietà, prenotazioni, ospiti e tassa di soggiorno, e risponde all’ospite sulla sua conversazione. Per questo risponde con i dati della prenotazione vera, non con un copione.
Se usi un altro PMS, FIRM lavora lo stesso. Il piano FIRM Enterprise include l’integrazione su misura con il tuo gestionale, se prendi FIRM senza Finikos: il collegamento che legge le tue prenotazioni dal sistema che hai già lo costruiamo noi.
FIRM Enterprise costa € 8,90 per proprietà al mese (€ 7,42 con pagamento annuale), proprietà illimitate, con 250 risposte AI al mese condivise su tutto l’account.
Sicurezza e limiti
- Scritture limitate. L’API manda messaggi agli ospiti e domande all’assistente di supporto; non crea né modifica prenotazioni, prezzi o pulizie.
- Una chiave per account, con il ruolo di chi la crea. Si vede una volta sola, si conserva come una password, si rigenera o si disattiva dalle impostazioni.
- Dati degli ospiti. Le schede portano documento e stato del check-in: le legge solo la chiave dell’account, per il concierge, e una chiave senza ruolo di amministratore solo per le proprietà con FIRM attivo.
- Messaggi una volta sola. Con la chiave di idempotenza lo stesso invio non parte due volte, nemmeno se la tua chiamata va in timeout.
- Nessun indirizzo pubblicato. Gli indirizzi dell’API non sono su questa pagina: arrivano con la documentazione, all’attivazione.
- Nessuna paginazione: un elenco arriva intero. Con la sincronizzazione incrementale leggi solo le novità e tieni leggere le chiamate.