API e widget

Incorpori la ricerca AI di LiKE nelle Sue applicazioni, nel Suo sito web o nei sistemi interni. Tre metodi di integrazione: REST API, widget JS, iframe.

#REST API

Disponibilità per piano. L'API pubblica e il widget pubblico funzionano solo sui piani che li includono (vedi Piani e fatturazione). Sugli altri piani non è possibile creare una chiave o un widget pubblico, e quelli già emessi smettono di rispondere: una richiesta con la chiave riceve 403, il pulsante del widget sul sito non compare. Il widget aziendale non dipende da questa opzione.

#Passo 1 — Creare una chiave API

1. Integrazioni → API pubblica → "Crea chiave"
2. Inserisca un nome (ad esempio, "App mobile")
3. Copi la chiave — viene mostrata una sola volta

#Passo 2 — Usare l'API

Tutte le richieste sono autorizzate tramite l'header:

X-API-Key: your-key

#Endpoint principali

#Esempio: ricerca AI

curl -X POST https://your-account.lynkora.pro/api/public/search \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "Как оформить отпуск?"}'

Risposta:

{
  "answer": "Для оформления отпуска...",
  "sources": [
    {"title": "Политика отпусков", "url": "..."}
  ]
}

#Limiti di frequenza

Le richieste API sono limitate per chiave; quando il limite viene superato, viene restituito HTTP 429 con un header Retry-After.

#Sicurezza

1. Conservi le chiavi in variabili d'ambiente, non nel codice
2. Crei una chiave separata per ogni applicazione
3. Elimini le chiavi inutilizzate
4. Limiti i domini nelle impostazioni della chiave

#Widget JS

Un pulsante di ricerca AI fluttuante da incorporare in qualsiasi sito web.

#Passo 1 — Ottenere il codice

1. Integrazioni → Canali → scheda «JS Widget» → «Gestisci widget» → «Crea widget». Indichi «Indirizzo del sito dove sarà il widget»
2. Configuri i parametri (consulti la tabella seguente)
3. Copi il codice

#Passo 2 — Aggiungerlo al Suo sito

Inserisca lo <script> copiato prima del tag di chiusura </body>:

#Dove incollare il codice nei costruttori di siti

Il codice è lo stesso per tutti i siti e non va modificato: il widget si individua da solo sulla pagina, ovunque il costruttore inserisca la riga. L'unica differenza è dove incollarlo.

Qualsiasi sito (HTML). Incolli il codice prima del tag di chiusura </body> in ogni pagina in cui serve la ricerca — oppure nel modello comune del sito.

WordPress. Installi il plugin WPCode (Insert Headers and Footers) → Code Snippets → Header & Footer → incolli il codice in Footer → Save Changes. Su WordPress.com i plugin non sono disponibili in tutti i piani.

Tilda. Per l'intero sito: Site Settings → More → HTML code for the HEAD section → incolli il codice → Save → ripubblichi tutte le pagine. Per una sola pagina: aggiunga il blocco Other → T123 (HTML code) e vi incolli il codice.

Wix. Nel pannello di controllo del sito apra Settings → Custom Code (a seconda della versione dell'interfaccia — in «Advanced» o «Development & integrations») → Add Custom Code → incolli il codice → All pages → Body — end → Apply. Non usi l'elemento «Embed HTML» in una pagina: si apre in un riquadro su un altro indirizzo e lì il widget non funzionerà. Il codice personalizzato in Wix è disponibile con un piano premium e un dominio collegato.

Webflow. Site settings → Custom code → Footer code → incolli il codice → Save → pubblichi il sito. Il codice personalizzato per l'intero sito è disponibile nei piani del sito a pagamento.

Squarespace. Apra Code Injection (nelle impostazioni del sito; a seconda della versione dell'interfaccia — in Developer tools o Website Tools) → incolli il codice in Footer → Save. L'iniezione di codice non è disponibile in tutti i piani.

Shopify. Online Store → Themes → … → Edit code → il file layout/theme.liquid → incolli il codice prima di </body> → Save.

Framer. Site Settings → General → Custom Code → incolli il codice in End of tag → pubblichi il sito.

Google Tag Manager. Tags → New → Custom HTML → incolli il codice → attivatore All Pages → Save → pubblichi il contenitore con Publish.

Docusaurus. Il codice va in docusaurus.config.js, con la stessa chiave:

scripts: [
  {
    src: 'https://your-account.lynkora.pro/api/public/widget.js',
    'data-key': 'wk_live_YOUR_KEY',
    async: true,
  },
],

Indirizzi del sito. Il widget funziona solo sugli indirizzi presenti in Domini consentiti, e l'indirizzo viene confrontato in modo esatto: example.com e www.example.com sono due indirizzi diversi — li aggiunga entrambi. Se prova il sito sull'indirizzo di anteprima del costruttore (ad esempio *.tilda.ws, *.wixsite.com, *.webflow.io, *.myshopify.com), aggiunga anche quello.

Il pulsante non è comparso? Controlli tre cose: il widget è attivo; l'indirizzo della pagina è in Domini consentiti — esattamente, con o senza www; il codice si trova nelle impostazioni o nel modello del sito, non in un elemento che il costruttore apre in un riquadro.

#Parametri del widget

#Risultato

Un pulsante appare nell'angolo del Suo sito (il colore è quello delle impostazioni del widget). Clicchi → una finestra di chat con il campo della domanda → una risposta AI dalla Sua base di conoscenza.

#Lingua

Il visitatore cambia lingua con il pulsante con il globo nell'intestazione della finestra; la scelta viene memorizzata nel suo browser per questo widget. Senza una scelta, il widget usa la prima lingua adatta tra quelle del browser, poi la lingua delle impostazioni del widget (data-lang), poi l'inglese. La lingua della pagina del Suo sito non viene considerata. In arabo la finestra si apre da destra a sinistra.

#Collegamento al sito

Il widget funziona solo sugli indirizzi indicati alla creazione («Indirizzo del sito dove sarà il widget»); le richieste da altri siti vengono rifiutate. Più indirizzi — separati da virgole. Senza un indirizzo il widget non si può attivare, e l'asterisco «qualsiasi sito» non è accettato. L'indirizzo viene confrontato in modo esatto: example.com e www.example.com sono indirizzi diversi, li indichi entrambi se il sito si apre con tutti e due. Per una verifica in locale indichi l'indirizzo con la porta, per esempio http://127.0.0.1:8899.

#Che cosa vede il visitatore

• Nel testo della risposta non ci sono etichette di fonte del tipo [2.3]; titoli e link sono formattati.
• Sotto la risposta c'è il blocco «Fonti»: il link porta alla pagina originale e, se non c'è, all'articolo.
• Il link «Apri la ricerca completa» è presente solo nel widget aziendale.

#Se il limite di risposte AI è esaurito

Il widget pubblico sul sito viene nascosto del tutto finché il limite non torna disponibile. Il widget aziendale resta al suo posto, ma non accetta domande e mostra quando la ricerca tornerà disponibile.

#iframe

Un'interfaccia di ricerca completa incorporata nella Sua pagina:

#Codice di incorporamento

/embed è l'unico indirizzo del portale che può essere aperto in un frame su un sito di terzi. La radice del portale (https://your-account.lynkora.pro) non può essere incorporata: il browser la rifiuterà. Il frame non richiede alcuna chiave: funziona in modo anonimo e mostra esattamente ciò che vede un visitatore anonimo del portale; l'ambito proviene dalle impostazioni del widget.

#Link diretto

Se un iframe non fa al caso Suo, fornisca agli utenti un link diretto: https://your-account.lynkora.pro

#Modalità demo

Per il test senza una chiave API, è disponibile un endpoint demo con limitazioni:

Endpoint: POST /api/public/demo/search

#Confronto delle modalità di autenticazione

Il widget supporta due modalità di autenticazione.

#Modalità A — Fiducia nella zona URL

Autenticazione lato client: Lei è responsabile di chi raggiunge le pagine con il widget (VPN, SSO, route protette). Lynkora non conosce l'identità dell'utente — solo l'Origin/IP della richiesta. Il widget è visibile a chiunque apra una pagina con il codice di incorporamento.

• Codice backend: 0 righe
• Tempo di onboarding: ~2 minuti
• Adatto per: intranet, portale interno

#Modalità B — Token di sessione (JWT per singolo utente)

Il Suo backend emette un token di sessione a breve durata per ogni utente. Lynkora conosce l'identità, mantiene un audit per singolo utente e supporta la revoca e le DSAR GDPR.

• Codice backend: ~10 righe (tramite SDK)
• Tempo di onboarding: 1–2 ore
• Adatto per: SaaS multi-tenant, settori regolamentati