Documentazione e integrazione API
Questa guida distingue tre ambiti: la conversazione web utilizzata dalle dimostrazioni, le API di quotazione del motore tariffario SmartNCC e il collegamento delle prenotazioni a un gestionale esterno. Hanno scopi, disponibilita' e autorizzazioni differenti.
Conversazione web: il contratto operativo
Gli esempi utilizzano quattro operazioni HTTP POST sullo stesso dominio della pagina. Il browser trasmette JSON e il backend verifica l'origine autorizzata e il riferimento della conversazione.
bootstrap: apertura o riconvalida della sessione pubblica.history: lettura della cronologia autorizzata.turn: invio di un messaggio o di una scelta consentita.handoff: richiesta di passaggio all'assistenza nel percorso predisposto dal backend.
Il riferimento anonimo non e' una credenziale di integrazione aziendale. Queste operazioni non consentono a un gestionale di elencare e acquisire liberamente le prenotazioni. Gli esempi del sito non distribuiscono chiavi per l'accesso ai dati di un'azienda.
Quotazione NCC: API documentate del motore tariffario
Il motore SmartNCC utilizzato dal chatbot dispone di API HTTP con dati JSON, utilizzabili anche da applicazioni esterne autorizzate. Questo contratto e' distinto dalle API della chat e dal contratto di acquisizione ChatNCC descritto sotto.
Il percorso di integrazione documentato usa la base /api/v1/WS_ncc_consumer.asmx/ sull'host assegnato all'azienda. Non e' una rotta esposta su questo sito vetrina.
Per calcolare una quotazione si usa POST quote_trip_JSON. Per confermare il preventivo selezionato e creare il servizio in SmartNCC si usa POST push_trip_JSON, passando smartncc_quote_id. Per cercare le localita' sono documentati POST get_departure_place_list_JSON e POST get_destination_place_list_JSON.
La quotazione distingue transfer (TRANSFER) e disposizione oraria (HOURLY). I dati comprendono localita' o coordinate, data e ora, passeggeri, bagagli e durata quando richiesta. Il listino applicato dipende dal cliente autorizzato e dalle regole predisposte. La risposta comprende le opzioni di veicolo, i dati economici e il riferimento della quotazione; errori e assenza di offerte devono essere gestiti dal software chiamante.
L'interfaccia server accetta token e json_params; formato della richiesta, autenticazione e involucro della risposta vanno allineati alla versione e alla collection di integrazione consegnata. Questa sintesi non sostituisce il contratto eseguibile. Le credenziali rimangono lato server: nessuna chiave aziendale deve essere pubblicata nel browser.
Richiedere una quotazione non equivale a confermare il viaggio. Per cambiare i dati tariffari di un preventivo si richiede una nuova quotazione, anziche' riutilizzare il suo identificativo con importi modificati. L'endpoint di conferma crea il servizio in SmartNCC: non implica automaticamente il trasferimento in un altro gestionale.
Scopri le regole del tariffario NCC e richiedi documentazione e ambiente di integrazione.
Prenotazioni ChatNCC: il contratto di acquisizione da concordare
Per un gestionale esterno il flusso minimo deve prevedere lettura delle nuove prenotazioni, dettaglio del viaggio e conferma di acquisizione con l'identificativo della pratica interna. Aggiornamenti di stato, modifiche e annullamenti richiedono regole esplicite.
Questo contratto di acquisizione e' in definizione e non viene presentato come API pubblica gia' attivabile. La valutazione tecnica stabilisce metodi disponibili, campi, autorizzazioni per azienda e ambiente di prova prima della consegna della documentazione eseguibile.
Criteri per un collegamento affidabile
Una richiesta ritentata non deve creare una seconda pratica. La lettura di piu' pagine di risultati deve permettere di riprendere il lavoro, senza perdere aggiornamenti. La presa in carico da parte del gestionale va distinta dalla conferma commerciale al passeggero.
Notifiche automatiche agli integratori, frequenza delle interrogazioni e gestione degli errori vengono definite in base al contratto attivato. Le credenziali riservate rimangono nei sistemi del fornitore, mai nel codice della pagina web.
Confronta le modalita' di integrazione oppure richiedi un confronto tecnico.