Unterzeichner hinzufügen

POST/esignglobal/v1/envelope/recipients/addSigners

Schnittstellenbeschreibung

Fügt einem Umschlag einen Unterzeichner hinzu, wobei der Unterzeichner die Signaturaufgabe darstellt. Dies beinhaltet das Hinzufügen von Steuerelementen und Authentifizierungsmethoden für den Unterzeichner.

Hinweis:

Es ist möglich, nach dem Öffnen eines Umschlags neue Unterzeichner hinzuzufügen. Die Signaturreihenfolge des neu hinzugefügten Unterzeichners darf nicht kleiner oder gleich dem Signaturreihenfolgewert eines Unterzeichners sein, der gerade signiert.
Derselbe Unterzeichner (mit der E-Mail-Adresse als eindeutige Benutzerkennung) darf nicht wiederholt hinzugefügt werden. Wenn Sie die Informationen zur Signaturaufgabe aktualisieren müssen, fügen Sie den entsprechenden Unterzeichner erneut hinzu.
Ein Umschlag darf maximal 10 Unterzeichner enthalten.

Anfrageparameter

Parametername					Typ	Erforderlich	Beschreibung
envelopeId					string	true	Umschlag-ID
signerInfos					array	true	Sammlung von Unterzeichnerinformationen
	businessId				string	false	Vom Entwickler definierte Geschäftsnummer, Länge 500
	userEmail				string	true	E-Mail-Adresse des Unterzeichners
	phoneNumber				object	false	Obligatorisch, wenn eine SMS-Benachrichtigung erforderlich ist. Sowohl countryCode als auch number müssen als Parameter eingegeben werden. Standardmäßig leer
		countryCode			string	false	Internationale Vorwahl des Landes/der Region, ohne das Präfix „+“
		number			string	false	Keine Formatprüfung, maximale Länge beträgt 13 Stellen
	customizeSettings				object	false	Benutzerdefinierte Konfiguration
		notificationSettings			object	false	Benutzerdefinierte Konfiguration für Benachrichtigungen
			customizeMessage		string	false	Exklusive Nachrichtbenachrichtigung, Zeichenbeschränkung 200
			notificationLanguage		string	false	Benachrichtigungssprache, Standard ist Englisch en-US Englisch zh-CN Vereinfachtes Chinesisch zh-Hant Traditionelles Chinesisch ja-JP Japanisch ES-MX Spanisch
	userName				string	true	Name des Unterzeichners, der auf der Unterzeichnungsseite und im Prozess zur externen Anzeige des Namens des Unterzeichners verwendet wird. 【Achtung】Darf nicht die folgenden 9 Sonderzeichen enthalten: / \ : * " < > \| ？ sowie alle Emoji-表情
	signOrder				int	true	Die Unterschriftsreihenfolge des Unterzeichners, minimal 1. Für ungeordnete Unterschriften kann der gleiche Reihenfolgewert angegeben werden.
	anySigner				boolean	false	Ob die Unterschrift von einer beliebigen Person unterstützt wird, standardmäßig false true - innerhalb derselben signOrder muss nur eine Person unterschreiben false - innerhalb derselben signOrder müssen alle Personen unterschreiben
	authModes				string	false	Art der Identitätsprüfung, standardmäßig noAuth Enumerationstyp: noAuth- Keine Überprüfung accessCode- Überprüfung mit Unterschriftspasswort sms- SMS-OTP-Verifizierung idVerification- Ausweisdokumentenverifizierung emailAuth- E-Mail-OTP-Verifizierung digitalId- Elektronische Identitätsprüfung
	authConfig				object	false	Einstellungen für Verifizierungsmethoden
		accessCode			object	false	Passwort-Einstellungen für die Signatur, erforderlich wenn authModes=accessCodeist
			accessCode		string	false	Passwortinhalt, Groß- und Kleinschreibung wird nicht beachtet, kann alphanumerische Zeichen enthalten, Länge 45
			promptInfo		string	false	Hinweis zur Zugriffspasswort-Information, darf kein Zugriffspasswort enthalten, Längenbeschränkung 30, wenn authModes=accessCodeist, ist dies ein Pflichtfeld.
		sms			object	false	SMS-OTP-Verifizierung, wenn authModes=smsist, ist dies ein Pflichtfeld
			countryCode		string	false	Internationaler Code des Landes/der Region, ohne das „+“-Zeichen
			number		string	false	Keine Formatprüfung, maximale Länge beträgt 13 Stellen
		idVerification			object	false	Einstellungen zur Überprüfung des Personalausweises, erforderlich wenn authModes=idVerificationist
			name		string	false	Vollständiger Name des Unterzeichners auf dem Personalausweis, maximale Länge 100 Zeichen
		emailAuth			object	false	E-Mail-OTP-Verifizierung, erforderlich wenn authModes=emailAuthist
			authEmail		string	false	E-Mail-Adresse zur Identitätsprüfung des Unterzeichners
		digitalId			array	false	Elektronische Identitätsprüfung, erforderlich wenn authModes=digitalId
			authApp		string	false	Für die elektronische Identitätsprüfung verwendete APP singpass - Verwendung von Singpass zur Identitätsprüfung
			idNumber		string	false	Personalausweisnummer des Unterzeichners, der verifiziert werden muss
	digitalSignature				boolean	false	Ob die digitale Signatur aktiviert ist, standardmäßig false true-Aktivieren false- Nicht aktiviert
	freeFormSign				boolean	false	Ist der Unterzeichner frei, das Siegel zu setzen? Standardwert ist false Zusätzliche Hinweise: Wenn freeFormSign auf true gesetzt ist, müssen keine anderen Parameter unter sealInfos übergeben werden. Wenn gleichzeitig Parameter übergeben werden, hat freeFormSign Vorrang vor sealInfos, und die Parameter unter sealInfos sind nicht wirksam. 【Hinweis】Freies Signieren bedeutet, dass die Anzahl und Position der Stempel/Signaturen, die der Unterzeichner einfügen kann, nicht begrenzt sind.
	sealInfos				array	false	Informationen zur Signaturaufgabe
		fileKey			string	true	Signaturdatei fileKey
		signConfigs			array	false	Informationen zur Steuerelementposition. Die Steuerelementposition muss angegeben werden, um eine elektronische Signatur durchführen zu können.
			fieldType		string	false	Steuerungselementtyp, kann als Parameter eingegeben werden: signature- Signatur-Steuerungselement stamp- Stempel-Steuerungselement approval- Genehmigungs-Steuerungselement Standardmäßig ist signature eingestellt
			sizeRule		string	false	Anzeigemodus für die Größe des Signaturbereichs originalSize- Stempelung basierend auf der tatsächlichen Größe der Signatur/des Stempels targetSize- Benutzerdefinierte Breite und Höhe des Signatur-/Stempelbereichs Wenn sizeRule, height und width alle leer sind, erfolgt die Stempelung basierend auf der tatsächlichen Größe der Signatur/des Stempels; Wenn sizeRule leer ist und height, width nicht leer sind, wird der Stempel in der angegebenen Größe platziert; Wenn sizeRule nicht leer ist, wird der Stempel gemäß der angegebenen Anzeigemethode platziert.
			height		int	false	Höhe des Signaturfelds, gilt für fieldType=signature/stamp, Einheit ist px, nur positive Ganzzahlen werden unterstützt, Standard ist auto (d. h. automatische Systemgröße); Wenn fieldType=signature ist, kann der Bereich von 20-250px eingestellt werden; Wenn fieldType=stamp ist, kann der Bereich von 30-280px eingestellt werden
			width		int	false	Breite des Signaturfelds, gilt für fieldType=signature/stamp, Einheit ist px, nur positive Ganzzahlen werden unterstützt, Standard ist auto (d. h. automatische Systemgröße); Wenn fieldType=signature ist, kann der Bereich von 20-250px eingestellt werden; Wenn fieldType=stamp ist, kann der Bereich von 30-280px eingestellt werden
			signatureOptions		string	false	Optionen für das Signatur-Steuerelement. Gilt nur, wenn fieldType den Wert "signature" hat. Mögliche Parameter: template handDrawn upload Mehrfachauswahl möglich, durch "," getrennt, standardmäßig alle ausgewählt
			movable		boolean	false	Bewegung der Position während der Unterzeichnung zulassen, standardmäßig false false- Dem Unterzeichner ist es nicht erlaubt, die Position seiner eigenen Signatur-Steuerelemente anzupassen true- Dem Unterzeichner ist es erlaubt, die Position seiner eigenen Signatur-Steuerelemente anzupassen
			allowedOptions		array	false	Optionen, die dem Unterzeichner die Genehmigung ermöglichen, gültig für fieldType vom Typ approval. Standardmäßig ["approve", "decline"] approve-Zustimmen decline-Ablehnen
			pageNo		string	false	Signaturseitenzahlen; fortlaufende Seitenzahlen werden mit "-" verbunden, einzelne Seitenzahlen mit ",", z. B.: 1-3, 6-10
			posX		string	false	X-Achsenkoordinate Zusätzliche Hinweise: Wenn fieldType den Wert „signature“ hat, bezieht sich die Koordinatenposition auf den SignaturbereichUnten links； Wenn fieldType den Wert „stamp“ hat, bezieht sich die Koordinatenposition auf den StempelbereichMittelpunktPosition Ab dem 3. Februar 2026 bezieht sich die Koordinatenposition für fieldType mit dem Wert „signature“ oder „stamp“ auf die Mittelpunktposition des Stempelbereichs.
			posY		string	false	Y-Achsenkoordinate Zusätzliche Hinweise: Wenn fieldType den Wert „signature“ hat, bezieht sich die Koordinatenposition auf den SignaturbereichUnten links； Wenn fieldType den Wert „stamp“ hat, bezieht sich die Koordinatenposition auf den StempelbereichMittelpunktPosition Ab dem 3. Februar 2026 bezieht sich die Koordinatenposition für fieldType = signature oder stamp auf die Position des Mittelpunkts des Stempelbereichs.
		fillConfigs			array	false	Füllen Sie die Steuerelementinformationen aus
			fieldName		string	false	Name des Steuerelements, Zeichenanzahl begrenzt auf 128
			required		boolean	false	Ist obligatorisch, standardmäßig obligatorisch true-obligatorisch false-optional
			fieldType		string	false	Steuerungstyp: 1-Einzeiliger Text 15-Kontrollkästchen
			textField		object	false	Textsteuerelement-Attribute
				overflowType	int	false	Gilt nur für Text, Standardwert 1 1-Automatische Schriftgrößenreduzierung 2-Eingabe beschränken
				minFontSize	float	false	Gilt nur für Text, nur für overflowType=1, Standardwert 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	Steuerelementbreite, Standardwert 160px
				font	int	false	Wirkt sich nur auf Text aus, Schriftart ist standardmäßig SimSun. 1-SimSun 2-NSimSun 4-Heiti 5-Kaiti 6-Arial 7-Helvetica 9-Times New Roman 10-Fangsong 11-Georgia 12-Monospace
				fontSize	float	false	Gilt nur für Text, Schriftgröße, Standard 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	Gilt nur für Text, Hexadezimalfarbe, Standard Schwarz #000
				bold	boolean	false	Gilt nur für Text, ob die Schrift fett gedruckt ist, Standard false true - fett false - nicht fett
				italic	boolean	false	Wirkt sich nur auf Text aus, ob kursiv, Standardwert ist false true-kursiv false-nicht kursiv
				underline	boolean	false	Wirkt sich nur auf Text aus, ob die Schriftart unterstrichen ist, Standardwert ist false true-Unterstreichung hinzufügen false-Keine Unterstreichung hinzufügen
				lineThrough	boolean	false	Gilt nur für Text, ob eine Durchstreichung hinzugefügt werden soll, Standardwert ist false true - Durchstreichung hinzufügen false - Keine Durchstreichung hinzufügen
				horizontalAlignment	string	false	Gilt nur für Text, horizontale Zentrierung, Standardwert ist left LEFT - Linksbündig CENTER - Zentriert RIGHT - Rechtsbündig
			tickBoxField		object	false	Kontrollkästchen-Attribute
				tickOptions	array	false	Gilt nur für Check, Standardwert 1 1-Haken 2-Kreuz
			posX		float	false	X-Koordinate der Steuerelementposition
			posY		float	false	Y-Koordinate der Steuerelementposition
			pageNo		string	false	Seitenzahl des Steuerelements
		signDateConfigs			array	false	Positionsinformationen zum Unterschriftsdatum
			movable		boolean	false	Bewegung der Position während der Unterzeichnung zulässig, Standardwert ist false false- Dem Unterzeichner ist es nicht gestattet, die Position seiner eigenen Unterschriftssteuerelemente anzupassen true- Erlaubt dem Unterzeichner, die Position seiner eigenen Unterschriftsfelder anzupassen
			pageNo		string	false	Seitenzahlen für die Unterschrift; fortlaufende Seitenzahlen werden mit "-" verbunden, einzelne Seitenzahlen mit ",", z. B.: 1-3, 6-10 Bei nicht fortlaufenden Seiten mit "," trennen
			posX		float	false	X-Achsen-Offset, der Ursprung des Koordinatensystems ist die linke untere Ecke der Seite
			posY		float	false	Y-Achsen-Offset, der Ursprung des Koordinatensystems ist die linke untere Ecke der Seite
			signDateFormat		string	false	Datumsformat für die Unterzeichnung, Standardformat ist yyyy-MM-dd Unterstützte Formate: yyyy年MM月dd日 yyyy-MM-dd yyyy/MM/dd dd.MM.yyyy MM dd yyyy dd MM yyyy

Beispielanfrage

{
    "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"
                    ]
                }
            ]
        }
    ]
}

Antwortparameter

Parametername			Typ	Beschreibung
envelopeId			string	Umschlag-ID
signFiles			array	Sammlung von signierten Dokumenten
	fileKey		string	fileKey der signierten Datei
attachments			array	Sammlung von Umschlaganhängen
	fileKey		string	Datei-fileKey
signerInfos			array	Sammlung von Informationen zum Unterzeichner
	businessId		string	Vom Entwickler definierte Geschäftsnummer, Länge 500
	userEmail		string	E-Mail-Adresse des Unterzeichners
	userName		string	Name des Unterzeichners
	signOrder		int	Reihenfolge der Unterzeichnerknoten, Minimum ist 1
		accessCode	string	Zugangspasswort für die Unterzeichnerseite

Beispielantwort

{
    "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"
}