Aggiungi firmatario

POST/esignglobal/v1/envelope/recipients/addSigners

Descrizione dell'interfaccia

Aggiunge un firmatario alla busta, che rappresenta un'attività di firma. Include l'aggiunta di controlli, metodi di autenticazione e altre informazioni per il firmatario.

Nota:

Supporta l'aggiunta di nuovi firmatari dopo l'apertura della busta. L'ordine di firma dei nuovi firmatari aggiunti non può essere inferiore o uguale al valore dell'ordine di firma di qualsiasi firmatario che sta firmando.
Non è consentito aggiungere ripetutamente lo stesso firmatario (utilizzando l'indirizzo email come identificatore univoco dell'utente). Se è necessario aggiornare le informazioni sull'attività di firma, si prega di aggiungere nuovamente il firmatario corrispondente.
Una busta può contenere al massimo 10 firmatari.

Parametri di richiesta

Nome parametro					Tipo	Obbligatorio	Descrizione
envelopeId					string	true	ID busta
signerInfos					array	true	Raccolta di informazioni sui firmatari
	businessId				string	false	Numero aziendale personalizzato dallo sviluppatore, lunghezza 500
	userEmail				string	true	Indirizzo email del firmatario
	phoneNumber				object	false	Obbligatorio se è necessario inviare una notifica via SMS, sia countryCode che number devono essere inclusi come parametri, predefinito vuoto
		countryCode			string	false	Prefisso internazionale del paese/regione, non è necessario inserire il segno “+”
		number			string	false	Nessun controllo del formato, la lunghezza massima è di 13 cifre
	customizeSettings				object	false	Configurazione personalizzata
		notificationSettings			object	false	Configurazione personalizzata per le notifiche
			customizeMessage		string	false	Notifiche di messaggi esclusivi, limite di 200 caratteri
			notificationLanguage		string	false	Lingua di notifica, predefinita è l'inglese en-US Inglese zh-CN Cinese semplificato zh-Hant Cinese tradizionale ja-JP Giapponese ES-MX Spagnolo
	userName				string	true	Nome del firmatario, utilizzato per visualizzare il nome del firmatario nella pagina e nel processo di firma. 【Attenzione】Non può contenere i seguenti 9 caratteri speciali: / \ : * " < > \| ？e tutte le emoji
	signOrder				int	true	Ordine di firma del firmatario, il valore minimo è 1. Per la firma non ordinata, è possibile specificare lo stesso valore di ordine.
	anySigner				boolean	false	Indica se è supportata la firma di una sola persona, il valore predefinito è false true - È richiesta la firma di una sola persona con lo stesso signOrder false - È richiesta la firma di tutte le persone con lo stesso signOrder
	authModes				string	false	Metodo di autenticazione, il valore predefinito è noAuth Tipo di enumerazione: noAuth- Nessuna verifica accessCode- Verifica tramite password di firma sms- Verifica tramite SMS OTP idVerification- Verifica tramite documento d'identità emailAuth- Verifica OTP via email digitalId- Autenticazione elettronica dell'identità
	authConfig				object	false	Impostazioni del metodo di verifica
		accessCode			object	false	Impostazione della password di firma, obbligatoria quando authModes=accessCodeè impostato
			accessCode		string	false	Contenuto della password, non fa distinzione tra maiuscole e minuscole, può contenere lettere e numeri, lunghezza 45
			promptInfo		string	false	Messaggio di suggerimento per la password di accesso, non può contenere la password di accesso, lunghezza massima 30, obbligatorio quando authModes=accessCode。
		sms			object	false	Verifica OTP SMS, obbligatorio quando authModes=sms。
			countryCode		string	false	Prefisso internazionale del paese/regione, non è necessario includere il segno “+”
			number		string	false	Nessuna verifica del formato, lunghezza massima di 13 cifre
		idVerification			object	false	Impostazioni di verifica del documento d'identità, obbligatorie quando authModes=idVerificationè impostato
			name		string	false	Nome completo presente sul documento d'identità del firmatario, lunghezza massima di 100 caratteri
		emailAuth			object	false	Verifica OTP via email, obbligatoria quando authModes=emailAuthè impostato
			authEmail		string	false	Indirizzo email di verifica dell'identità del firmatario
		digitalId			array	false	Autenticazione elettronica dell'identità, obbligatoria quando authModes=digitalId
			authApp		string	false	APP utilizzata per l'autenticazione elettronica dell'identità singpass - Utilizza Singpass per l'autenticazione
			idNumber		string	false	Numero del documento d'identità del firmatario da verificare
	digitalSignature				boolean	false	Indica se la firma digitale è abilitata, predefinito false true- Abilitata false- Non abilitato
	freeFormSign				boolean	false	Indica se il firmatario può apporre liberamente la firma; il valore predefinito è false Note aggiuntive: Quando si seleziona freeFormSign come true, non è necessario passare altri parametri in sealInfos. Se vengono passati contemporaneamente, freeFormSign ha la priorità su sealInfos e i parametri in sealInfos non avranno effetto. [Attenzione] La firma libera non limita il numero e la posizione dei timbri/firme che il firmatario può trascinare.
	sealInfos				array	false	Informazioni sull'attività di firma
		fileKey			string	true	fileKey del documento da firmare
		signConfigs			array	false	Informazioni sulla posizione del controllo; è necessario specificare le informazioni sulla posizione del controllo per poter apporre la firma elettronica.
			fieldType		string	false	Tipo di controllo, parametri accettati: signature- Controllo firma stamp- Controllo timbro approval- Controllo approvazione Predefinito è signature
			sizeRule		string	false	Modalità di visualizzazione delle dimensioni dell'area di firma originalSize- Applica il timbro in base alle dimensioni effettive della firma/timbro targetSize- Definisci larghezza e altezza personalizzate dell'area firma/timbro Quando sizeRule, height e width sono tutti vuoti, il timbro viene applicato in base alle dimensioni effettive della firma/timbro; Quando sizeRule è vuoto e height e width non sono vuoti, il timbro viene posizionato in base alle dimensioni specificate; Quando sizeRule non è vuoto, il timbro viene posizionato in base al metodo di visualizzazione specificato.
			height		int	false	Altezza del controllo di firma, applicabile quando fieldType è signature/stamp, l'unità è px, supporta solo numeri interi positivi, predefinito auto (ovvero, dimensione automatica del sistema); Quando fieldType=signature, l'intervallo impostabile è 20-250px; Quando fieldType=stamp, l'intervallo impostabile è 30-280px
			width		int	false	Larghezza del controllo di firma, applicabile quando fieldType è signature/stamp, l'unità è px, supporta solo numeri interi positivi, predefinito auto (ovvero, dimensione automatica del sistema); Quando fieldType=signature, l'intervallo impostabile è 20-250px; Quando fieldType=stamp, l'intervallo impostabile è 30-280px
			signatureOptions		string	false	Opzioni del controllo firma. Applicabile solo quando fieldType è signature. Parametri accettabili: template handDrawn upload Possibilità di selezione multipla, separati da ",", per impostazione predefinita sono tutti selezionati
			movable		boolean	false	Consenti lo spostamento della posizione durante la firma, predefinito false false- Non consentire al firmatario di regolare la posizione del proprio controllo di firma true- Consenti al firmatario di regolare la posizione del proprio controllo di firma
			allowedOptions		array	false	Opzioni per cui il firmatario può approvare, applicabile quando fieldType è approval. Il valore predefinito è ["approve", "decline"] approve- Approva decline- Rifiuta
			pageNo		string	false	Pagine da firmare; le pagine consecutive sono collegate con "-", le pagine singole sono collegate con ",", ad esempio: 1-3, 6-10
			posX		string	false	Coordinata sull'asse X Note aggiuntive: Se fieldType è signature, la posizione delle coordinate si riferisce all'area della firmaAngolo inferiore sinistro； Se fieldType è stamp, la posizione delle coordinate si riferisce all'area del timbroPunto centralePosizione Dal 3 febbraio 2026, se fieldType è signature o stamp, la posizione delle coordinate si riferisce alla posizione del punto centrale dell'area del timbro.
			posY		string	false	Coordinata dell'asse Y Note aggiuntive: Se fieldType è signature, la posizione delle coordinate si riferisce all'area della firmaAngolo inferiore sinistro； Se fieldType è stamp, la posizione delle coordinate si riferisce all'area del timbroPunto centralePosizione Dal 3 febbraio 2026, se fieldType è signature o stamp, la posizione delle coordinate si riferisce alla posizione del punto centrale dell'area del timbro.
		fillConfigs			array	false	Compila le informazioni del controllo
			fieldName		string	false	Nome del controllo, limite di 128 caratteri
			required		boolean	false	Se è obbligatorio, obbligatorio per impostazione predefinita true-Obbligatorio false-Non obbligatorio
			fieldType		string	false	Tipo di controllo: 1-Testo a riga singola 15-Casella di controllo
			textField		object	false	Proprietà del controllo testo
				overflowType	int	false	Valido solo per il testo, predefinito 1 1-Ridimensionamento automatico del carattere 2-Limitazione dell'input
				minFontSize	float	false	Valido solo per il testo, valido solo per overflowType=1, 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, predefinita 160px
				font	int	false	Funziona solo con il testo, carattere, 宋体 predefinito. 1-宋体 2-新宋体 4-黑体 5-楷体 6-Arial 7-Helvetica 9-Times New Roman 10-仿宋 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 esadecimale, predefinito nero #000
				bold	boolean	false	Si applica solo al testo, se il carattere è in grassetto, predefinito false true-Grassetto false-Non in grassetto
				italic	boolean	false	Si applica solo al testo, indica se il testo è in corsivo, predefinito false true-corsivo false-non corsivo
				underline	boolean	false	Si applica solo al testo, indica se il testo è sottolineato, predefinito false true-aggiungi sottolineatura false-non aggiungere sottolineatura
				lineThrough	boolean	false	Si applica solo al testo, indica se aggiungere una linea barrata, predefinito false true-Aggiungi linea barrata false-Non aggiungere linea barrata
				horizontalAlignment	string	false	Si applica solo al testo, formato di centraggio orizzontale, predefinito left LEFT-Allineato a sinistra CENTER-Centrato RIGHT-Allineato a destra
			tickBoxField		object	false	Proprietà della casella di controllo
				tickOptions	array	false	Valido solo per Check, predefinito 1 1-Spunta 2-Croce
			posX		float	false	Coordinata X orizzontale della posizione del controllo
			posY		float	false	Coordinata Y verticale 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	Consenti lo spostamento della posizione durante la firma, predefinito false false- Non consentire al firmatario di modificare la posizione del proprio controllo di firma true- Consenti al firmatario di regolare la posizione dei propri controlli di firma
			pageNo		string	false	Pagine da firmare; pagine consecutive sono collegate con "-", pagine singole sono collegate con ",", ad esempio: 1-3, 6-10 Se non consecutive, separare con ","
			posX		float	false	Offset sull'asse x, l'angolo inferiore sinistro della pagina è l'origine delle coordinate
			posY		float	false	Offset sull'asse y, l'angolo inferiore sinistro della pagina è l'origine delle coordinate
			signDateFormat		string	false	Formato della data di firma, il formato predefinito è aaaa-MM-gg Supporta il formato specificato: aaaa年MM月gg日 aaaa-MM-gg aaaa/MM/gg gg.MM.aaaa MM gg aaaa gg MM aaaa

Esempio di richiesta

{
    "envelopeId": "{{envelope-id}}",
    "signerInfos": [
        {
    	   "userEmail": "sender_user@esignglobal.com",
    	   "userName": "sender_user_name",
    	   "signOrder": 1,
    	   "authModes": "sms",
           "authConfig": {
                "sms": {
                    "countryCode": "86",
                    "number": "158****9242"
                }
            },
            "sealInfos": [
                {
                    "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c",
                    "signConfigs": [
                        {
                           "fieldType": "stamp",
                            "pageNo": "1",
                            "posX": 100.22,
                            "posY": 100
                        }
                    ],
                    "fillConfigs": [
                        {
                            "fieldId": "df0dd777bcc4d108de242d",
                            "fieldKey": "demo",
                            "pageNo": "1",
                            "posX": "88.70021",
                            "posY": 745.409,
                            "fieldType": "1",
                            "required": true,
                            "textField": {
                                "overflowType": "1",
                                "minFontSize": 8,
                                "font": "6",
                                "fontSize": "12",
                                "textColor": "#54ACD2",
                                "bold": false,
                                "italic": true,
                                "lineThrough": false,
                                "horizontalAlignment": "RIGHT"
                            }
                        },
                        {
                            "fieldId": "96e6c7d414f04e98938ea84013b",
                            "fieldKey": "红色加深斜体下划线删除线",
                            "pageNo": "1",
                            "posX": 94.516624,
                            "posY": 284.54953,
                            "fieldType": "1",
                            "required": false,
                            "textField": {
                                "overflowType": "1",
                                "minFontSize": 10.5,
                                "font": "1",
                                "fontSize": 12.0,
                                "textColor": "#E25041",
                                "bold": true,
                                "italic": true,
                                "lineThrough": true,
                                "horizontalAlignment": "LEFT"
                            }
                        },
                        {
                            "fieldId": "888b899853544c49bd819d9f6d1",
                            "fieldKey": "必填勾选控件选中样式不显示边框",
                            "pageNo": "3",
                            "posX": 451.77127,
                            "posY": 429.07626,
                            "fieldType": "15",
                            "required": true,
                            "tickBoxField": {
                                "tickOptions": [1,2],
                                "showBorder": false
                            }
                        }
                    ]
                    "signDateConfigs":[
                          "pageNo":"1",
                          "posX": 100.22,
                          "posY": 100,
                          "signDateFormat": "dd MMM yyyy"
                    ]
                }
            ]
        }
    ]
}

Parametri di risposta

Nome parametro			Tipo	Descrizione
envelopeId			string	ID busta
signFiles			array	Raccolta di documenti firmati
	fileKey		string	fileKey del documento firmato
attachments			array	Raccolta di allegati della busta
	fileKey		string	fileKey del file
signerInfos			array	Raccolta di informazioni sul firmatario
	businessId		string	Numero aziendale personalizzato dallo sviluppatore, lunghezza 500
	userEmail		string	Indirizzo email del firmatario
	userName		string	Nome del firmatario
	signOrder		int	Ordine del nodo del firmatario, il valore minimo è 1
		accessCode	string	Password di accesso alla pagina di firma

Esempio di risposta

{
    "code": "0",
    "data": {
        "signerInfos": [
            {
                "organizationName": "Esign Global CO.",
                "userLastName": "",
                "accessCode": "",
                "userEmail": "sender_user@tsign.cn",
                "userFirstName": "",
                "signOrder": "1"
            }
        ],
        "signFiles": [
            {
                "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c"
            }
        ],
        "attachments": [

        ],
        "envelopeId": "9fbe6c8190824227bde29136b0145c81"
    },
    "message": "success"
}