OTP Service: firma semplice e FEA

Due percorsi di firma differenti

ISP Billing dispone di due percorsi che non devono essere confusi. La firma OTP incorporata è il flusso storico dell’Area Clienti per contratti e preventivi: invia un codice SMS, registra le accettazioni richieste e cambia lo stato del documento. OTP Service è invece l’integrazione con il provider esterno: prepara e invia dossier di firma semplice o FEA per i contratti, riceve gli stati mediante callback e acquisisce il PDF firmato.

Il percorso incorporato non richiede le credenziali OTP Service, ma richiede un provider SMS funzionante. Il percorso esterno richiede modulo, credenziali, credito provider, callback, anagrafica completa e punti firma correttamente posizionati. Scegliere il flusso previsto dal processo contrattuale senza avviarli entrambi sullo stesso documento.

Credenziali API

In Impostazioni → OTP Service abilitare il modulo e inserire URL API, e-mail API, password API e User ID ricevuti dall’organizzazione OTP Service. Lasciare l’URL ufficiale salvo indicazioni differenti del provider; la password API può essere distinta da quella del pannello web.

Salvare e usare Test connessione. Un test riuscito verifica autenticazione e raggiungibilità, non credito disponibile, validità dei dati cliente o consegna di una futura pratica.

Firma semplice e firma avanzata

La firma elettronica semplice usa il percorso rapido di accettazione e OTP. La firma elettronica avanzata (FEA) richiede dati anagrafici più completi e riconoscimento con foto o documento.

Abilitare soltanto i tipi previsti dal proprio contratto e scegliere il tipo predefinito fra quelli attivi. La scelta predefinita velocizza il flusso, ma l’operatore deve controllare il requisito giuridico e documentale del caso concreto.

Mappatura completa dei dati FEA

La firma avanzata non legge campi casuali dall’anagrafica: ogni dato OTP Service deve essere associato a un campo standard del cliente oppure a un campo personalizzato. Sono obbligatori codice fiscale, sesso, nascita, cittadinanza, residenza, tipo e numero del documento, luogo e date di rilascio e scadenza. La data del riconoscimento di persona è disponibile come dato aggiuntivo.

Creare prima nel CRM gli eventuali campi personalizzati, stabilire chi li aggiorna e con quale fonte, quindi completare ogni selettore contrassegnato come obbligatorio. Comune e provincia devono essere coerenti perché il sistema prova a risolvere il codice catastale; testo ambiguo o valori numerici non riconoscibili possono essere esclusi dal payload. Usare l’anteprima FEA nel contratto per vedere valori risolti e dati mancanti prima di predisporre la pratica.

Preparare una pratica dal contratto

Aprire il contratto definitivo, controllare cliente, contenuto, servizi, allegati e tipo di firma, quindi usare il comando OTP Service. La preparazione genera o rigenera il PDF, calcola l’hash del documento, raccoglie firmatario e recapiti e crea una pratica locale nello stato Da inviare. Se esiste già una pratica collegata, il sistema la aggiorna invece di creare copie incontrollate.

Per l’invio servono un cliente CRM, e-mail e telefono validi, User ID API, callback configurata e stato pratica compatibile. La pratica deve essere ancora ready_to_send oppure in errore correggibile. Prima di riprovare dopo un errore, correggere la causa e usare la stessa pratica.

Impostare i punti firma

Nel modello del contratto, nel contenuto del contratto o nel testo contrattuale dei servizi inserire il segnaposto Punto firma OTP Service nel punto in cui deve comparire la firma. È possibile usarne più di uno; l’ordine dei marcatori diventa l’ordine dei punti assegnati al firmatario.

Durante la preparazione il sistema renderizza il PDF finale e calibra pagina e coordinate in formato A4. Per i documenti HTML usa i marcatori del layout; per il PDF finale può utilizzare pdftotext/Poppler per trovare le coordinate reali. Se il numero dei punti attesi e rilevati non coincide, l’invio viene fermato per evitare firme fuori posizione. Dopo modifiche a modello, servizi o impaginazione rigenerare la pratica e controllare tutte le pagine del PDF.

Dati necessari per la FEA

Prima dell’invio verificare firmatario, data e luogo di nascita, codice fiscale, tipo e numero del documento, data di rilascio e scadenza, Paese, provincia e Comune di rilascio. L’anteprima FEA evidenzia i valori vuoti o non inviati.

Non compilare dati mancanti per supposizione. Correggere l’anagrafica o la fonte prevista, rigenerare l’anteprima e solo dopo creare la pratica.

Opzioni di invio

Nel flusso contratti attuale, l’opzione e-mail decide se OTP Service invia direttamente il documento da firmare. Per il documento concluso si possono configurare la consegna via e-mail e il collegamento via SMS. Se la richiesta iniziale non viene inviata dal provider, l’ISP deve predisporre un proprio canale autorizzato per consegnare il link.

Controllare recapiti, consenso, costo SMS e contenuto prima dell’invio. Una pratica non notificabile va corretta, non duplicata senza averne compreso la causa.

Callback di stato

La pagina mostra un URL univoco da registrare nel pannello OTP Service in Organizzazione → URL callback cambio stato. Le callback aggiornano la pratica soltanto quando gli stati callback sono richiesti nel dossier.

L’URL contiene un segreto: non deve comparire in screenshot o documentazione pubblica. Dopo la configurazione verificare con una pratica di prova autorizzata che gli aggiornamenti arrivino una sola volta e siano associati al dossier corretto.

Come vengono associati gli aggiornamenti

OTP Service può inviare eventi riferiti al dossier oppure al destinatario. ISP Billing cerca la pratica tramite identificativo cliente del dossier, hash del contratto o UUID remoto e conserva separatamente stato generale, stato del destinatario, ultimo callback, checksum e URL del documento firmato. Gli eventi del destinatario, come visualizzazione e firma, non sostituiscono lo stato finale del dossier.

La callback aggiorna il contratto soltanto quando riceve uno stato finale coerente. Negli stati che richiedono il documento deve essere presente un URL firmato valido; lo stato completed può chiudere la pratica anche quando il file viene reso disponibile separatamente. Non modificare manualmente il contratto per anticipare una callback in ritardo.

Sincronizzazione manuale

Sincronizza stato rilegge dal provider una pratica già dotata di UUID o identificativo remoto e applica gli stessi criteri usati dalla callback. È utile quando una notifica non è arrivata o quando il pannello remoto mostra uno stato più recente.

La sincronizzazione non crea una nuova richiesta di firma e non reinvia SMS o e-mail. Prima di usarla confrontare codice pratica e contratto; se il provider non trova l’identificativo, verificare ambiente e credenziali invece di predisporre immediatamente un duplicato.

Dashboard e credito

La dashboard riepiloga stato provider, credito residuo, pratiche del periodo, totali, lavorazioni, completate, FEA da verificare, anomalie e origine. Il credito è un prerequisito operativo separato dalla validità delle credenziali.

Le scorciatoie aprono pratiche, impostazioni, pannello remoto e coda FEA. Le statistiche remote compaiono soltanto quando il provider le rende disponibili; l’assenza di un indicatore non va interpretata come zero.

Stati della pratica

Il percorso può attraversare bozza, creata, da inviare, invio, inviata, notificata, visualizzata, accettata, in firma, firmata, generazione PDF, PDF caricato, PDF inviato e completata. Esistono stati di errore per invio, notifica o consegna del documento.

Sincronizza stato interroga il provider per una pratica già remota. Usarlo dopo aver verificato l’identificativo; non ripetere l’invio di una pratica già accettata o in firma.

Documento firmato e checksum

Quando disponibile, il PDF firmato viene salvato nei file del cliente, reso visibile nell’Area Clienti e collegato al contratto e alla pratica. Il nuovo file sostituisce il precedente PDF contrattuale; il contratto passa a Firmato e riceve la data di firma. Il checksum finale permette di riconoscere il file esatto ricevuto.

Prima di considerare concluso il processo, aprire il PDF e controllare firmatario, pagine, punti firma, completezza e contratto origine. Il collegamento remoto non sostituisce la conservazione prevista dall’ISP; accessi e allegati devono rispettare tenant, ruolo e cliente.

Firma OTP incorporata per contratti e preventivi

Nel flusso storico il cliente apre il collegamento pubblico protetto del contratto o preventivo e richiede il codice. ISP Billing usa il cellulare dell’anagrafica, genera un OTP di sei cifre valido per un’ora e impedisce un nuovo invio prima che sia trascorso un minuto. Un documento già firmato non può essere firmato di nuovo.

Nel contratto il cliente deve anche valorizzare tutti i campi di presa visione previsti dal modello; quelli obbligatori non possono essere rifiutati. La conferma registra nome, descrizione e valore delle informative, porta il contratto a Firmato, imposta la data e genera il PDF archiviato nei file cliente. Nel preventivo la conferma porta la proposta ad Accettata. In entrambi i casi viene creata l’attività successiva prevista dal processo.

Checklist

• Attivare il modulo e il contratto provider
• Inserire credenziali API dedicate
• Eseguire il test connessione
• Abilitare i soli tipi di firma necessari
• Scegliere il tipo predefinito coerente
• Completare i dati FEA senza supposizioni
• Configurare canali e recapiti
• Registrare la callback senza esporne il segreto
• Controllare credito e stato provider
• Seguire gli stati senza duplicare invii
• Verificare PDF, checksum e documento origine