Descrizione dello Scope delle interfacce per le applicazioni dell'ecosistema ISV

1. Panoramica

Questo documento mira a fornire agli sviluppatori dei partner dell'ecosistema una descrizione degli Scope (domini di autorizzazione) nel sistema di autorizzazione delle applicazioni eSignGlobal. Durante l'integrazione dell'autorizzazione dell'applicazione, gli sviluppatori dovranno richiedere gli Scope pertinenti in base alle effettive esigenze funzionali del proprio business. Ogni Scope include l'elenco delle OpenAPI consentite per le chiamate all'interno di tale dominio di autorizzazione; la piattaforma controllerà rigorosamente i permessi dell'applicazione sulle risorse correlate in base agli Scope concessi.

Interfaccia di autenticazione di base

Prima che le applicazioni dell'ecosistema effettuino chiamate ufficiali alle interfacce, è necessario innanzitutto ottenere le credenziali di chiamata tramite l'endpoint di autorizzazione:

Nome dell'interfaccia	Percorso dell'interfaccia	Descrizione dell'interfaccia
Ottenere AccessToken	`POST /esignglobal/v1/oauth2/accessToken`	Tramite appid e appsecret per ottenere l'access_token di autenticazione, utilizzato per effettuare richieste all'API eSignGlobal in qualità di utente specifico. Il Token è valido per 24 ore.

Attualmente, i domini di autorizzazione Scope aperti nell'ecosistema eSignGlobal includono principalmente:

signature：Servizio principale di firma elettronica
stamp：Servizio di gestione dei sigilli
comparisons：Servizio di confronto contratti

2. Dettagli dello Scope e elenco delle API

2.1 Scope: `signature` (Servizio di firma elettronica)

Questo Scope è il dominio di autorizzazione più basilare e comune, che comprende le interfacce core end-to-end per i servizi di firma elettronica. Dopo averlo autorizzato, l'applicazione potrà gestire e orchestrare moduli, documenti da firmare (inclusi gli allegati), partecipanti e il flusso di lavoro principale delle buste.

Modulo 1: Servizio dei moduli

Nome dell'interfaccia	Descrizione dell'interfaccia
Ottieni i dettagli dei controlli del modulo per il firmatario	Ottieni le informazioni sui controlli del modulo per un firmatario specifico e la relativa configurazione delle proprietà
Ottieni i dettagli del modulo	Ottieni le informazioni complete su un modulo specifico, inclusi i dettagli sui campi e sulla struttura del file
Compila il modulo per generare un file	In base al modulo fornito, compila i dati aziendali e genera automaticamente un file in formato PDF
Consulta l'elenco dei moduli	Consulta l'elenco dei moduli disponibili per l'account corrente, con supporto alla paginazione o filtraggio per condizioni specifiche
Consulta i dettagli del task di composizione del file	Recuperare il risultato finale dell'esecuzione di un'attività di generazione file da modello tramite l'ID dell'attività asincrona

Modulo 2: Gestione dei file

Nome dell'interfaccia	Descrizione dell'interfaccia
Caricamento file	Caricare file locali o file di flusso di lavoro specifici sulla piattaforma per la successiva firma
Recupero delle coordinate in base alla parola chiave	Eseguire una ricerca testuale sui documenti caricati e restituire le coordinate di posizione corrispondenti alla parola chiave
Download del file	Scaricare documenti firmati completati specifici, file sorgente o altri file allegati aziendali
Aggiunta del file di firma	Associare i file caricati con successo in precedenza a una busta di firma o a un flusso di lavoro specifico
Eliminazione del file di firma	Rimuovere dalla busta di lavoro i file caricati per errore o non necessari per la firma al momento
Aggiunta di un allegato	Aggiungi allegati esplicativi supplementari al flusso della busta o della firma
Elimina allegato	Rimuovi i documenti allegati specificati dal flusso della busta o della firma

Modulo 3: Gestione delle parti coinvolte

Nome dell'interfaccia	Descrizione dell'interfaccia
Aggiungi firmatario	Aggiungi un partecipante alla firma che deve eseguire l'azione di firma in un determinato flusso della busta
Elimina firmatario	Rimuovi una parte firmataria obsoleta da un determinato flusso della busta
Aggiungi destinatario in copia	Aggiungi il ruolo di destinatario in copia, che riceve esclusivamente notifiche sullo stato di avanzamento e può visualizzare il documento firmato definitivo
Elimina destinatario in copia	Rimuovi un ruolo specifico di destinatario in copia

Modulo 4: Gestione delle buste

Nome dell'interfaccia	Descrizione dell'interfaccia
Avvio rapido del fascicolo	Se la piattaforma integrata utilizza questa interfaccia per creare il fascicolo e, una volta completata la firma, il sistema gestisce automaticamente la chiusura del processo, non è necessario richiamare manualmente "Chiusura del fascicolo".
Creazione del fascicolo	Utilizzato per creare un fascicolo in stato di bozza, supporta la configurazione di parametri come l'oggetto della firma, le impostazioni dei firmatari, ecc.
Attivazione del fascicolo	Dopo aver confermato che tutti i documenti e i firmatari sono corretti, invia ufficialmente il task di firma al downstream.
Chiusura del fascicolo	Chiusura manuale del fascicolo. Prima della chiusura, tutti i firmatari devono completare la firma; una volta terminato il processo, le risorse non possono essere modificate.
Recupero dell'indirizzo di firma	Recupera il link breve dedicato o l'URL della pagina di firma direttamente caricabile per il firmatario specificato.
Consulta i dettagli del fascicolo	Ottieni le informazioni generali del fascicolo, i file associati, i partecipanti e lo stato corrente del flusso.
Revoca del fascicolo	Ritirare manualmente un pacchetto di firme non ancora completato dall'iniziatore
Promemoria per pacchetto di firme	Se il pacchetto di firme non è stato completato, supporta l'invio di un promemoria di sollecito ai firmatari attualmente in attesa, con un intervallo di sollecito di 30 minuti.
Ottieni l'URL della pagina di anteprima della firma	Una volta aperto il pacchetto di firme, è possibile utilizzare questa API per ottenere l'indirizzo della pagina di anteprima della firma. Viene principalmente utilizzato all'interno della piattaforma integrata per consentire ai non partecipanti al pacchetto di visualizzare i documenti di firma e lo stato di avanzamento.
Crea vista di invio del pacchetto di firme	Crea la vista del mittente del pacchetto di firme tramite l'ID del pacchetto. Per i flussi di firma avviati in questa vista, le informazioni dell'iniziatore verranno popolate con i dati utente risolti dal token di accesso OAuth.

2.2 Scope: `stamp` (Servizio di gestione dei timbri)

Questo Scope è dedicato specificamente all'autorizzazione alla gestione per timbri aziendali o nomi personali. Si applica agli ecosistemi di terze parti che necessitano solo di mantenere una libreria centralizzata di timbri aziendali (creazione, modifica, eliminazione e ricerca dei timbri), senza intervenire direttamente nel processo di avvio della firma.

Nome dell'API	Descrizione dell'API
Recupera elenco timbri	Utilizza un AppID con i permessi di query corrispondenti per recuperare i dati dell'elenco delle risorse dei timbri.
Crea timbro	Utilizza un AppID autorizzato per creare un timbro tramite la stringa codificata in Base64 dell'immagine caricata (formato PNG supportato, dimensioni 18mm-100mm).
Modifica timbro	Modifica delle informazioni, quali nome e immagine, del timbro creato
Elimina timbro	Rimuove in modo definitivo le risorse del timbro specificato che non presentano più collegamenti aziendali

2.3 Scope: `comparisons` (Servizio di confronto dei contratti)

Questo Scope è dedicato al dominio funzionale legale dei contratti intelligenti. Consente alle applicazioni dei partner dell'ecosistema di richiamare in modo flessibile le funzionalità di confronto di testi e versioni durante le fasi di revisione contrattuale e valutazione legale, garantendo un rapido controllo delle differenze prima e dopo la modifica del contratto.

Nome dell'interfaccia	Descrizione dell'interfaccia
Ottieni la pagina dei risultati del confronto dei contratti	Ottieni l'indirizzo della pagina visuale che visualizza i risultati delle differenze di confronto
Consulta i dettagli del confronto dei contratti	Ottiene il risultato del confronto del contratto tramite l'ID di business del confronto dei contratti, contenente il numero di differenze (quantità di aggiunte, eliminazioni e modifiche) nonché il contenuto dettagliato delle differenze di confronto (localizzazione nei dettagli).