Aggiungi firmatario

Nome del parametro

Tipo

Obbligatorio

Descrizione

envelopeId

string

true

ID del plico

signerInfos

array

true

Collezione delle informazioni del firmatario

businessId

string

false

Numero di business personalizzato dallo sviluppatore, lunghezza massima 500

roleTypes

array

false

Modalità di operazione del firmatario, valore predefinito ["sign", "fill"]

fill-compilazione

sign-firma

string

false

userEmail

string

false

Indirizzo email del firmatario

documentVisibility

object

false

Configurazione della visibilità dei file, impostata di default su visibile per tutti.

documentViewType

string

false

Strategia di visibilità, default all; all indica che è possibile visualizzare tutti i documenti firmati all'interno del plico, limited indica che è possibile visualizzare solo i propri documenti firmati e i documenti aggiuntivi resi visibili.

viewableFileKeys

array

false

Elenco dei fileKey aggiuntivi consentiti alla parte firmataria per la visualizzazione; può essere inviato ed è efficace solo quando documentViewType=limited.

phoneNumber

object

false

Obbligatorio quando è necessaria una notifica via SMS; devono essere forniti sia il codice paese (countryCode) che il numero, il valore di default è vuoto.

countryCode

string

false

Codice internazionale del paese/regione, non è necessario includere il simbolo “+”.

number

string

false

Nessuna validazione del formato, lunghezza massima di 13 caratteri.

customizeSettings

object

false

Configurazione personalizzata.

notificationSettings

object

false

Configurazione personalizzata per le notifiche.

customizeMessage

string

false

Notifica messaggio dedicato, limite di 200 caratteri.

notificationLanguage

string

false

Lingua della notifica, di default utilizza la configurazione “lingua di notifica predefinita”.

en-US Inglese

zh-CN Cinese semplificato

zh-Hant Cinese tradizionale

ja-JP Giapponese

es-MX spagnolo

pt-PT portoghese
th-TH thailandese
id-ID indonesiano
vi-VN vietnamita
ms-MY malese
fil-PH filippino
de-DE tedesco
fr-FR francese
ru-RU russo
it-IT italiano
ko-KR coreano

userName

string

true

Nome del firmatario, utilizzato per visualizzare il nome del firmatario nella pagina e nel flusso di firma.

[Nota] Non deve contenere i seguenti 9 caratteri speciali: / \ : * " < > | ? nonché tutte le emoji

signOrder

int

true

Ordine di firma del firmatario, minimo 1. Per la firma non ordinata è possibile specificare lo stesso valore di ordine.

signTaskSuspend

boolean

false

Se impostare un nodo di blocco del flusso prima di questa posizione di firma, il valore predefinito è false. true: imposta il nodo di blocco; false: non imposta il nodo di blocco. La configurazione di blocco all'interno dello stesso gruppo di firme OR con lo stesso signOrder deve essere coerente.

suspensionKey

string

false

Identificatore del nodo di blocco, massimo 500 caratteri, unico all'interno dello stesso plico. Obbligatorio quando signTaskSuspend=true; non deve essere fornito quando signTaskSuspend=false o non viene passato.

suspendReason

string

false

Motivo del blocco, non può essere vuoto se fornito, massimo 50 caratteri. Può essere fornito solo quando signTaskSuspend=true; se non fornito, il valore predefinito indica che è necessario attendere l'elaborazione da parte di un sistema esterno. Non deve essere fornito quando signTaskSuspend=false o non viene passato.

anySigner

boolean

false

Se supportare la firma da parte di chiunque, il valore predefinito è false

true: per lo stesso signOrder è sufficiente la firma di una sola persona

false: per lo stesso signOrder è necessaria la firma di tutte le persone

authModes

string

false

Metodo di verifica dell'identità, il valore predefinito è noAuth

Tipo enumerato:

authConfig

object

false

Impostazioni del metodo di verifica

accessCode

object

false

Impostazioni della password di firma, obbligatoria quando authModes=accessCode

accessCode

string

false

Contenuto della password, non distingue tra maiuscole e minuscole, può contenere lettere e numeri, lunghezza massima 45

promptInfo

string

false

Messaggio di提示 per la password di accesso, non deve contenere la password di accesso, lunghezza massima 30, obbligatoria quando authModes=accessCode.

sms

object

false

Verifica OTP via SMS, obbligatoria quando authModes=sms

countryCode

string

false

Codice internazionale del paese/regione, senza il simbolo '+'

number

string

false

Nessuna convalida del formato, lunghezza massima 13 caratteri

idVerification

object

false

Impostazioni di verifica dell'identità tramite documento, obbligatoria quando authModes=idVerification

name

string

false

Nome completo sul documento d'identità del firmatario, lunghezza massima 100 caratteri

emailAuth

object

false

Verifica OTP via email, obbligatoria quando authModes=emailAuth

authEmail

string

false

Indirizzo e-mail per la verifica dell'identità del firmatario

digitalId

array

false

Verifica dell'identità digitale, obbligatoria quando authModes=digitalId

authApp

string

false

App utilizzata per la verifica dell'identità digitale

singpass- Utilizzo di Singpass per l'autenticazione dell'identità

iamsmart- Utilizzo di MyInfo per l'autenticazione dell'identità

idNumber

string

false

Numero del documento d'identità del firmatario da verificare

Quando authApp=singpass, le regole di inserimento sono: una lettera maiuscola seguita da 7 o 8 cifre numeriche e poi da una lettera maiuscola

Quando authApp=iamsmart, le regole di inserimento sono:

1. Una lettera maiuscola (A-Z) o due lettere maiuscole (AA-ZZ) come inizio della sequenza;

2. Seguite da 6 cifre numeriche;

3. Infine un codice di controllo, che può essere una cifra (0-9) o una lettera (A-Z). Esempio: A888888(A)

whatsappAuth

object

false

Verifica OTP tramite WhatsApp, obbligatoria quando authModes=whatsappAuth

countryCode

string

false

Codice internazionale del paese/regione, senza inserire il simbolo '+'

number

string

false

Non eseguire la convalida del formato, limitare solo la lunghezza massima a 13 caratteri

digitalSignature

boolean

false

Se abilitare la firma digitale, valore predefinito false

true-Abilitato

false-Disabilitato

tsp

string

false

Selezionare il TSP utilizzato dal firmatario, valore predefinito false.

Se non impostato, il firmatario sceglie autonomamente il TSP da utilizzare. L'elenco include:

vinotek、eSignPersonal、localCertificates、iAmSmart、vnptSmartCa、adacomOneShot、audkenni

belgianIdCard、certEuropeUsbToken、certSignWebSign、chaveMovel、croatianIdCard、czechIdCard、dTrustSignMe、diia

estonianIdCard、estonianMobileId、evrotrust、finnishIdCard、frejaEid、frejaEidSign、gseGestionDeSeguridadElectronica、halcom

harica、idAustriaATrustSignatur、infoCert、ltId、latvianIdCard、latvianEParakstsMobile、lithuanianIdCard、lithuanianMobileId

mscTrustGate、mitId、norwegianBankId、oneId、pscWorldWallet、spid、serproId、simplySign

smartId、swedenBankId、swissId、swisscom、transSped、trustAsia、zealidApp、certMe

certSignUsbToken、eCertChile、eMudhra、itsme、mojeId、emdha

freeFormSign

boolean

false

Se il firmatario può applicare liberamente il timbro/firma, valore predefinito false

Note aggiuntive:

Quando freeFormSign è impostato su true, non è necessario trasmettere altri parametri sotto sealInfos. Se vengono trasmessi contemporaneamente, freeFormSign ha priorità su sealInfos e i parametri sotto sealInfos non avranno effetto.

[Nota] La firma libera non limita né il numero né la posizione dei timbri/firme che il firmatario può trascinare.

sealInfos

array

false

Informazioni sull'attività di firma

fileKey

string

true

fileKey del documento firmato

signConfigs

array

false

Informazioni sulla posizione del controllo: è necessario specificare le informazioni sulla posizione del controllo per procedere con la firma elettronica.

fieldType

string

false

Tipo di controllo, parametri di input possibili:

signature-Controllo di firma

stamp-Controllo timbro

Predefinito: signature

Obbligatorio o meno, predefinito obbligatorio

true-Obbligatorio

false-Non obbligatorio

signFieldStyle

string

false

Metodo di applicazione del timbro per il controllo firma, predefinito normalSeal.

normalSeal-Timbro normale

pagingSeal-Timbro a cavallo delle pagine

Solo i controlli firma e timbro supportano la configurazione del timbro a cavallo delle pagine.

pagingSealMode

string

false

Intervallo di pagine per l'applicazione del timbro a cavallo, predefinito all.

all-Tutte le pagine

assignedPages-Pagine specifiche

even-Pagine pari

odd-Pagine dispari

Supporta la specifica solo quando signFieldStyle=pagingSeal.

sizeRule

string

false

Modalità di visualizzazione delle dimensioni dell'area di firma

originalSize- Posizionamento del timbro in base alle dimensioni effettive della firma/timbro

targetSize- Larghezza e altezza personalizzate dell'area di firma/timbro

Quando sizeRule, height e width sono tutti vuoti, il timbro viene posizionato in base alle dimensioni effettive della firma/timbro;

Quando sizeRule è vuoto ma height e width non lo sono, il timbro viene posizionato in base alle dimensioni specificate;

Quando sizeRule non è vuoto, il timbro viene posizionato in base alla modalità di visualizzazione specificata;

Il timbro a cavallo delle pagine non richiede la specifica di questo parametro; il posizionamento avviene esclusivamente in base alle dimensioni effettive.

height

int

false

Altezza del controllo di firma, applicabile quando fieldType è signature/stamp, unità in px, accetta solo numeri interi positivi, valore predefinito auto (dimensioni automatiche del sistema);

Quando fieldType=signature, l'intervallo impostabile è 20-250px;

Quando fieldType=stamp, l'intervallo impostabile è 30-280px;

Il timbro a cavallo delle pagine non richiede la specifica di questo parametro.

width

int

false

Larghezza del controllo di firma, applicabile quando fieldType è signature/stamp, unità in px, accetta solo numeri interi positivi, valore predefinito auto (dimensioni automatiche del sistema);

Quando fieldType=signature, l'intervallo impostabile è 20-250px;

Quando fieldType=stamp, l'intervallo impostabile è 30-280px;

Il timbro di sovrapposizione non richiede la specifica di questo parametro.

signatureOptions

string

false

Opzioni del controllo di firma. Applicabile solo quando fieldType è signature.

Parametri inseribili:

template

handDrawn

upload

aiHandDrawn

Selezione multipla consentita, separata da ","; selezione predefinita di tutte le opzioni

movable

boolean

false

Consente lo spostamento della posizione durante la firma; valore predefinito false

false- Non consente al firmatario di regolare la posizione dei propri controlli di firma

true- Consente al firmatario di regolare la posizione dei propri controlli di firma

allowedOptions

array

false

Opzioni che consentono l'approvazione da parte del firmatario, applicabili quando fieldType è approval. Valore predefinito: ["approve", "decline"]

approve- Approva

decline- Rifiuta

pageNo

string

false

Numeri di pagina della sezione di firma; pagine consecutive unite con "-", pagine singole separate da ","; ad esempio: 1-3, 6-10

Quando pagingSealMode=assignedPages, inserire l'intervallo di pagine in cui posizionare il timbro di sovrapposizione. Il timbro di sovrapposizione può essere utilizzato solo su file con più di una pagina.

posX

string

false

Coordinate sull'asse X

Note aggiuntive:

Se fieldType è signature, le coordinate indicano la posizione dell'area di firmaangolo in basso a sinistra；

Se fieldType è stamp, la posizione delle coordinate indica l'area del timbro.punto centraleposizione

A partire dal 3 febbraio 2026, se fieldType è signature o stamp, la posizione delle coordinate indica il punto centrale dell'area del timbro.

Il valore per il timbro di sovrapposizione può essere 0, ma non null; il controllo è fissato sul bordo destro del documento.

posY

string

false

coordinata Y

Note aggiuntive:

Se fieldType è signature, la posizione delle coordinate indica l'area della firma.angolo in basso a sinistra；

Se fieldType è stamp, la posizione delle coordinate indica l'area del timbro.punto centraleposizione

A partire dal 3 febbraio 2026, se fieldType è signature o stamp, la posizione delle coordinate indica il punto centrale dell'area del timbro.

fillConfigs

array

false

Inserire le informazioni del controllo

fieldName

string

false

Nome del controllo, limite di caratteri 128

required

boolean

false

Obbligatorio o meno, obbligatorio per impostazione predefinita

true-obbligatorio

false-non obbligatorio

fieldType

string

false

Tipo di controllo:

1-testo su una riga

15-casella di controllo

textField

object

false

Proprietà del controllo testo

overflowType

int

false

Valido solo per text, valore predefinito 1

1-riduzione automatica della dimensione del carattere

2-limitazione dell'immissione

minFontSize

float

false

Valido solo per text, valido solo per overflowType=1, valore predefinito 8.

5, 5.5, 6, 6.5, 7, 7.5, 8, 9, 10, 10.5, 11, 12, 14, 15, 16, 18, 20, 22, 24, 26, 28, 36, 42, 48, 56, 72

width

int

false

Larghezza del controllo, valore predefinito 160px

font

int

false

Valido solo per text, font, valore predefinito SimSun.

1-SimSun

2-Font SimSun

4-Font SimHei

5-Font KaiTi

6-Arial

7-Helvetica

9-Times New Roman

10-Font FangSong

11-Georgia

12-Monospace

fontSize

float

false

Si applica solo al testo, dimensione del carattere, predefinito 12

5, 5.5, 6, 6.5, 7, 7.5, 8, 9, 10, 10.5, 11, 12, 14, 15, 16, 18, 20, 22, 24, 26, 28, 36, 42, 48, 56, 72

textColor

string

false

Si applica solo al testo, colore in esadecimale, predefinito nero #000

bold

boolean

false

Si applica solo al testo, se il carattere è in grassetto, predefinito false

true-grassetto

false-non grassetto

italic

boolean

false

Si applica solo al testo, se il carattere è in corsivo, predefinito false

true-corsivo

false-non corsivo

underline

boolean

false

Si applica solo al testo, se il carattere ha la sottolineatura, predefinito false

true-sottolineato

false-non sottolineato

lineThrough

boolean

false

Si applica solo al testo, se aggiungere il testo barrato, valore predefinito false

true - aggiungi testo barrato

false - non aggiungere testo barrato

horizontalAlignment

string

false

Si applica solo al testo, allineamento orizzontale al centro, valore predefinito left

LEFT - allineato a sinistra

CENTER - centrato

RIGHT - allineato a destra

tickBoxField

object

false

Proprietà della casella di controllo

tickOptions

array

false

Si applica solo a Check, valore predefinito 1

1 - segno di spunta

2 - croce

posX

float

false

Coordinate X della posizione del controllo

posY

float

false

Coordinate Y della posizione del controllo

pageNo

string

false

Numero di pagina in cui si trova il controllo

signDateConfigs

array

false

Informazioni sulla posizione della data di firma

movable

boolean

false

Consente di spostare la posizione al momento della firma; valore predefinito false

false- Non è consentito al firmatario regolare la posizione dei propri controlli di firma

true- È consentito al firmatario regolare la posizione dei propri controlli di firma

pageNo

string

false

Numero di pagina della firma; le pagine consecutive sono unite con "-", le pagine singole con ",", ad esempio: 1-3, 6-10

Se non consecutive, utilizzare "," come separatore

posX

float

false

Spostamento sull'asse x, l'origine delle coordinate è nell'angolo in basso a sinistra della pagina

posY

float

false

Spostamento sull'asse y, l'origine delle coordinate è nell'angolo in basso a sinistra della pagina

signDateFormat

string

false

Formato della data di firma; il formato predefinito è yyyy-MM-dd

Supporta i seguenti formati:

anno yyyy mese MM giorno dd

yyyy-MM-dd

yyyy/MM/dd

dd.MM.yyyy

MM dd yyyy

dd MM yyyy