Integrare Jev AI via API: un flusso per n8n e software aziendali

Jev AI può essere integrato in n8n attraverso il nodo HTTP Request, chiamando l’endpoint TypeSafe con una richiesta autenticata e un body JSON. La proposta di questa guida usa quel nodo core: non è stato verificato un connettore Jev nativo. Le capacità del nodo sono documentate nella guida HTTP Request di n8n.

Il progetto va però oltre il collegamento. Ricevere un risultato e aggiornare correttamente una pratica sono due lavori diversi. Il flusso deve riconoscere l’evento, preparare i contenuti, controllare la risposta e decidere se proporre un’assegnazione o scrivere nel gestionale. Il confine scelto per il pilota determina anche quali verifiche servono.

Scegliere il primo evento e il risultato atteso

Per partire, conviene scegliere un ingresso ristretto: una casella, un modulo o una coda di richieste già riconoscibile. Il risultato iniziale può essere un reparto suggerito, registrato accanto alla pratica. Non serve costruire subito una catena che risponde al cliente, modifica l’ordine e chiude il ticket.

Prima del nodo HTTP, il flusso dovrebbe avere un’identità stabile dell’evento e il materiale da valutare. Nella proposta, l’identità resta una responsabilità del sistema di origine: permette di riconoscere la stessa richiesta durante nuovi tentativi o ricomparse. Il testo utile viene separato da elementi che non contribuiscono alla scelta.

Il referente operativo definisce quali destinazioni esistano e chi legga i casi dubbi. La guida allo smistamento dei ticket con Jev AI aiuta a costruire questo confine. Per chi deve scegliere prima il ruolo del modello, cos’è Jev AI offre la definizione del componente dentro il processo.

Il contratto HTTP documentato

Il quickstart TypeSafe indica una chiamata POST a https://api.typesafe.ai/v1/systemone, con header Authorization: Bearer e Content-Type: application/json. La chiave si ottiene attraverso il dashboard previsto dal fornitore, con accesso autenticato; questa guida non verifica la disponibilità di un nuovo account. Quickstart ufficiale.

Il body usa state, model e questions. Le domande sono una mappa con identificativi scelti dal chiamante; per una Choice, le alternative stanno in criteria, insieme a type e instructions. La forma è mostrata nel quickstart ufficiale e definita nell’API reference. Il seguente contenuto italiano è un esempio progettuale, non una risposta osservata né una configurazione n8n esportata.

{
  "state": "Il ricambio ricevuto non corrisponde al codice ordinato. Vorrei sapere come sostituirlo.",
  "model": "jev-latest",
  "questions": {
    "reparto": {
      "type": "choice",
      "instructions": "Quale reparto deve prendere in carico la richiesta? Scegli lettura_manuale quando il messaggio non consente una destinazione definita.",
      "criteria": {
        "postvendita": "Problemi su prodotti ricevuti o richieste di sostituzione",
        "amministrazione": "Fatture e documentazione contabile",
        "commerciale": "Richieste su nuovi acquisti o preventivi",
        "lettura_manuale": "Richieste non riconducibili alle destinazioni precedenti"
      }
    }
  }
}

L’esempio non usa un campo messages né una compatibilità presunta con altre API. Il testo, le istruzioni e le categorie sono una proposta per il processo; i nomi dei campi seguono il contratto documentato. Cambiare i criteri richiede un nuovo controllo degli esempi di confine, perché «sostituzione» e «nuovo acquisto» possono sovrapporsi nel linguaggio reale.

Nel pilota il sistema deve registrare ciò che il servizio restituisce e confrontarlo con il risultato atteso dal referente. Il quickstart documenta la raccolta answers, il modello effettivo e il consumo usage; per la Choice mostra scelta, probabilità e confidence. Esempio di risposta TypeSafe.

Configurazione proposta del nodo HTTP Request

Nel nodo si impostano metodo POST, endpoint ufficiale e body JSON. Per l’autenticazione si usa una credenziale generica adatta all’header, e si richiede una risposta JSON. n8n documenta anche configurazione manuale e importazione cURL; in quest’ultima i parametri possono diventare stringhe, quindi la forma finale del body va verificata. Documentazione del nodo.

La tabella descrive un’architettura da costruire, non un’integrazione già provata su un account. Per i meccanismi generali della piattaforma, la guida all’automazione con n8n offre il contesto. Il passaggio verso l’applicazione di lavoro merita invece le verifiche illustrate in integrare il gestionale con n8n.

Credenziali e responsabilità del collegamento

n8n prevede credenziali generiche per HTTP Request, tra cui autenticazione via header. Il gestore di credenziali è il luogo previsto per configurare l’accesso, separandolo dal contenuto operativo. Credenziali HTTP Request.

Nel progetto, il responsabile tecnico decide chi può modificare il flusso e chi può vedere le esecuzioni. Il test condiviso con l’ufficio dovrebbe usare esempi senza informazioni personali non necessarie. Le schermate per descrivere il processo non hanno bisogno della chiave reale o del contenuto completo di una conversazione cliente.

Il valore pubblico da mostrare come segnaposto è TYPESAFE_API_KEY; la credenziale reale rimane nell’ambiente che esegue il collegamento. Prima di collegare una casella operativa, si verifica quali dati siano inviati e quali siano conservati dal proprio sistema. L’approfondimento su privacy e dati aziendali aiuta a preparare queste domande, che non si risolvono con la sola autenticazione.

Controllare prima di aggiornare il gestionale

La risposta deve essere associata alla richiesta giusta e contenere i risultati attesi. La proposta verifica gli identificativi delle domande, il tipo previsto e il valore ammesso prima di usare il risultato. Se manca un campo o arriva una destinazione sconosciuta, il percorso operativo si ferma e genera una lettura tecnica, invece di interpretare il dato per approssimazione.

L’API documenta una risposta per ciascuna domanda sotto il suo identificativo. Le risposte Choice comprendono la scelta e la distribuzione delle probabilità; questo contratto va letto esattamente, senza attribuire a tutti i tipi gli stessi campi. API reference.

Il controllo tecnico non risolve la correttezza semantica. Il responsabile stabilisce quali suggerimenti restino assistiti e quali possano diventare assegnazioni. La guida a confidence e revisione umana affronta il significato dei segnali: non si dovrebbe aggiungere una soglia scelta a intuito e chiamarla garanzia.

La scrittura sul gestionale deve avere poi una protezione propria. Nella proposta, l’identificativo dell’evento viene controllato prima di creare o modificare la pratica. Se il flusso riparte dopo un’interruzione, riconosce il lavoro già eseguito. Questa misura non dipende dalla qualità della classificazione: protegge il processo anche quando la stessa valutazione viene richiesta più volte.

Errori e interruzioni fanno parte del flusso

La documentazione TypeSafe distingue 401 per chiave mancante o non valida, 422 per body non valido, 429 per limite di richieste e 529 per sovraccarico. Per gli ultimi due indica nuovi tentativi con backoff esponenziale. Gestione errori ufficiale.

Nella proposta applicativa, un errore di credenziale richiede intervento tecnico e non una ripetizione indefinita. Un body non valido richiede controllo della costruzione della richiesta. I nuovi tentativi per problemi temporanei hanno invece un numero massimo e un limite di attesa scelti rispetto alla procedura dell’azienda. Sono decisioni progettuali da documentare nel flusso.

Va previsto anche il caso in cui la valutazione riesca ma la scrittura fallisca. Ripetere tutto può produrre un risultato nuovo e una pratica duplicata; il sistema dovrebbe sapere quale fase sia stata completata. Il registro operativo conserva l’esito della valutazione e lo stato dell’aggiornamento con accessi coerenti al contenuto, così che il tecnico possa recuperare il lavoro senza ricostruire una catena di email.

Due scenari ipotetici da collaudare

Imballaggi a Modena: assegnazione assistita in ufficio ordini

Una PMI ipotetica di Modena produce imballaggi e riceve richieste di preventivo, modifiche d’ordine e contestazioni. Il primo flusso n8n propone la destinazione della pratica e la presenta all’operatore. Non aggiorna quantità o date di produzione. Il responsabile ordini approva le categorie e annota i casi che richiedono due reparti.

Nel collaudo, un messaggio ricompare due volte perché l’ingresso viene rieseguito. Il risultato atteso non è avere due classificazioni identiche, ma una sola pratica operativa. Un secondo caso simula un’interruzione dopo la valutazione: alla ripresa si usa lo stato del lavoro per completare l’aggiornamento, senza aprire un duplicato.

L’operatore prova anche una richiesta con informazioni incomplete. Deve poter correggere la destinazione e vedere il messaggio originale. Il pilota considera conclusa una prova soltanto quando la pratica è leggibile e recuperabile, non quando il nodo HTTP mostra un’esecuzione riuscita.

Manutenzione a Cagliari: continuità della presa in carico

Una seconda PMI ipotetica, a Cagliari, gestisce manutenzioni per imprese. Le richieste arrivano da un modulo e devono essere assegnate all’ufficio competente. Il processo deve continuare anche quando il servizio di valutazione è temporaneamente indisponibile: l’ingresso registra comunque la pratica e la coda manuale resta attiva.

Il collaudo simula un problema temporaneo e verifica il percorso di attesa. Dopo il limite stabilito, il lavoro passa alla lettura umana con un motivo comprensibile. Il cliente non deve restare senza presa in carico perché l’automazione aspetta un risultato. Il responsabile controlla che gli operatori sappiano riconoscere e gestire la coda.

Un altro caso contiene una descrizione tecnica e una richiesta commerciale nello stesso testo. La proposta può essere rivista senza perdere l’identificativo dell’evento. Il criterio di successo è una presa in carico coerente, con una persona responsabile e un percorso di recupero, mentre l’eventuale modifica di un contratto resta fuori dal primo progetto.

Consegnare un flusso che gli operatori sappiano leggere

La consegna dovrebbe includere una procedura breve per i tre stati principali: proposta disponibile, pratica in revisione e problema tecnico. L’operatore deve capire chi prende in carico il lavoro e quale informazione guardare. Esporre tutti i dettagli dell’esecuzione nella schermata quotidiana può confondere; nascondere il motivo per cui una pratica è ferma impedisce invece di recuperarla.

Il referente tecnico prepara un registro delle modifiche ai criteri e ai collegamenti. Quando viene aggiunta una categoria, si controlla anche che esista la destinazione corrispondente e che qualcuno legga quella coda. Un risultato nuovo non può diventare una scrittura valida soltanto perché è comparso nella configurazione del modello. Il processo deve conoscere il prossimo passo prima di attivarlo.

Il monitoraggio proposto distingue errore tecnico, revisione semantica e fallimento dell’aggiornamento. Tre code diverse permettono di chiamare la persona adatta: il tecnico per il collegamento, il referente operativo per i criteri, il responsabile del gestionale per una pratica non scritta. Usare un unico stato «non riuscito» renderebbe necessario rileggere ogni esecuzione per capire chi debba intervenire.

Si concorda infine una modalità di ritorno al lavoro manuale. Una modifica del gestionale o una nuova procedura può richiedere di sospendere temporaneamente le assegnazioni automatiche, continuando a registrare gli ingressi. Il collaudo deve verificare anche questa transizione: le pratiche ricevute durante la sospensione restano identificabili e gli operatori non perdono il riferimento al canale originale. È una condizione di continuità, non un dettaglio da aggiungere dopo il primo problema.

Quando valutare un SDK

TypeSafe offre SDK ufficiali Python e JavaScript/TypeScript; la documentazione li presenta con tipi e policy di retry predefinite. L’HTTP diretto resta utilizzabile da altri ambienti. Client SDKs.

La guida JavaScript indica il pacchetto @typesafe-ai/sdk, Node.js 20 o superiore e il metodo client.systemOne. SDK JavaScript. Quella Python documenta TypeSafeClient e AsyncTypeSafeClient. SDK Python. Questi riferimenti aiutano quando il collegamento vive in software sviluppato direttamente. In n8n il collegamento qui proposto resta una richiesta HTTP, con lo stesso contratto di input e output.

La scelta dipende da chi manterrà la soluzione. Un gruppo che già lavora in n8n può preferire il flusso visuale; un’applicazione con controlli e test propri può integrare il client nel codice. Il contratto operativo dovrebbe rimanere lo stesso, con dati in ingresso, giudizio atteso, controllo e azione consentita.

La prova minima prima di collegare il gestionale

• Contenuto semplice con destinazione attesa e categoria ammessa.
• Contenuto ambiguo che deve arrivare a una persona.
• Evento ripetuto che deve produrre una sola pratica.
• Errore temporaneo con limite ai nuovi tentativi.
• Interruzione dopo la valutazione e prima della scrittura.
• Correzione manuale leggibile e associata all’evento originale.

Se lo stesso testo deve alimentare più valutazioni, le domande parallele aiutano a progettare le chiamate. Il budget dell’API e dell’automazione deve includere anche queste prove e il mantenimento del collegamento. Un servizio di automazione dei processi aziendali trasforma la richiesta riuscita in un percorso che gli operatori possono usare.

Progettiamo il collegamento tra Jev AI e i tuoi strumenti, con un pilota che verifichi anche errori, revisioni e recupero.