Agregar firmante

POST/esignglobal/v1/envelope/recipients/addSigners

Descripción de la interfaz

Agrega firmantes al sobre, los firmantes son las tareas de firma. Incluye agregar controles al firmante, métodos de autenticación y otra información.

Nota:

Admite agregar nuevos firmantes después de que se abre el sobre. El orden de firma de los nuevos firmantes agregados no puede ser menor o igual que el valor del orden de firma de ningún firmante que esté firmando.
No se permite agregar el mismo firmante (con el correo electrónico como identificador único del usuario) repetidamente. Si necesita actualizar la información de la tarea de firma, vuelva a agregar el firmante correspondiente.
Solo puede haber un máximo de 10 firmantes en un sobre.

Parámetros de solicitud

Nombre del parámetro					Tipo	Obligatorio	Descripción
envelopeId					string	true	ID del sobre
signerInfos					array	true	Colección de información del firmante
	businessId				string	false	Número de negocio personalizado por el desarrollador, longitud 500
	userEmail				string	true	Dirección de correo electrónico del firmante
	phoneNumber				object	false	Obligatorio cuando se necesita enviar notificaciones por SMS, se deben ingresar los parámetros countryCode y number, el valor predeterminado es vacío
		countryCode			string	false	Código internacional del país o región, no es necesario ingresar “+”
		number			string	false	No se realiza la verificación de formato, la longitud máxima es de 13 dígitos
	customizeSettings				object	false	Configuración personalizada
		notificationSettings			object	false	Configuración personalizada de notificaciones
			customizeMessage		string	false	Notificación de mensaje exclusiva, límite de 200 caracteres
			notificationLanguage		string	false	Idioma de la notificación, el idioma predeterminado es inglés en-US Inglés zh-CN Chino simplificado zh-Hant Chino tradicional ja-JP Japonés ES-MX Español
	userName				string	true	Nombre del firmante, utilizado para mostrar el nombre del firmante en la página y el proceso de firma. 【Atención】No debe contener los siguientes 9 caracteres especiales: / \ : * " < > \| ？ ni ningún emoji
	signOrder				int	true	Orden de firma del firmante, el mínimo es 1. Se puede especificar el mismo valor de orden para firmas no secuenciales.
	anySigner				boolean	false	Indica si se permite que firme cualquiera, el valor predeterminado es falso true: solo se requiere que firme una persona del mismo signOrder false: se requiere que firmen todas las personas del mismo signOrder
	authModes				string	false	Método de autenticación, el valor predeterminado es noAuth Tipo de enumeración: noAuth-Sin verificación accessCode-Verificación con contraseña de firma sms-Verificación por SMS OTP idVerification-Verificación de documento de identidad emailAuth-Verificación OTP por correo electrónico digitalId-Verificación de identidad electrónica
	authConfig				object	false	Configuración del método de verificación
		accessCode			object	false	Configuración de la contraseña de firma, obligatoria cuando authModes=accessCode
			accessCode		string	false	Contenido de la contraseña, no distingue entre mayúsculas y minúsculas, puede contener letras y números, longitud 45
			promptInfo		string	false	Mensaje de sugerencia de contraseña de acceso, no puede contener la contraseña de acceso, longitud limitada a 30, cuando authModes=accessCodees obligatorio.
		sms			object	false	Verificación de SMS OTP, cuando authModes=smses obligatorio
			countryCode		string	false	Código internacional del país/región, no es necesario incluir el signo “+”
			number		string	false	No se realiza la verificación de formato, la longitud máxima es de 13 dígitos
		idVerification			object	false	Configuración de verificación de identificación, obligatoria cuando authModes=idVerification
			name		string	false	Nombre completo del firmante que aparece en su identificación, longitud máxima de 100 caracteres
		emailAuth			object	false	Verificación OTP por correo electrónico, obligatoria cuando authModes=emailAuth
			authEmail		string	false	Dirección de correo electrónico de verificación de identidad del firmante
		digitalId			array	false	Autenticación de identidad electrónica, obligatoria cuando authModes=digitalId
			authApp		string	false	Aplicación utilizada para la autenticación de identidad electrónica singpass: usa Singpass para la autenticación
			idNumber		string	false	Número de identificación del firmante que se va a verificar
	digitalSignature				boolean	false	¿Activar la firma digital? El valor predeterminado es falso true-Activado false-No activado
	freeFormSign				boolean	false	Si el firmante firma libremente, el valor predeterminado es falso Notas adicionales: Cuando se selecciona freeFormSign como verdadero, no es necesario pasar otros parámetros bajo sealInfos. Si se pasan al mismo tiempo, la prioridad de freeFormSign es mayor que la de sealInfos, y los parámetros bajo sealInfos no tendrán efecto. [Atención] La firma libre no restringe la cantidad ni la posición de los sellos/firmas que el firmante puede arrastrar.
	sealInfos				array	false	Información de la tarea de firma
		fileKey			string	true	FileKey del archivo de firma
		signConfigs			array	false	Información de la ubicación del control, la información de la ubicación del control debe especificarse para realizar la firma electrónica.
			fieldType		string	false	Tipo de control, parámetros de entrada posibles: signature-Control de firma stamp-Control de sello approval-Control de aprobación El valor predeterminado es signature
			sizeRule		string	false	Forma de visualización del tamaño del área de firma originalSize-Sellar según el tamaño real de la firma/sello targetSize-Ancho y alto personalizados del área de firma/sello Cuando sizeRule, height y width están vacíos, se sella según el tamaño real de la firma/sello; Cuando sizeRule está vacío y height, width no están vacíos, estampe según el tamaño especificado; Cuando sizeRule no está vacío, estampe según el método de visualización especificado.
			height		int	false	Altura del control de firma, aplicable cuando fieldType es signature/stamp, la unidad es px, solo se admiten enteros positivos, el valor predeterminado es auto (es decir, tamaño automático del sistema); Cuando fieldType=signature, el rango que se puede establecer es de 20 a 250 px; Cuando fieldType=stamp, el rango que se puede establecer es de 30 a 280 px
			width		int	false	Ancho del control de firma, aplicable cuando fieldType es signature/stamp, la unidad es px, solo se admiten enteros positivos, el valor predeterminado es auto (es decir, tamaño automático del sistema); Cuando fieldType=signature, el rango que se puede establecer es de 20 a 250 px; Cuando fieldType=stamp, el rango que se puede establecer es de 30 a 280 px
			signatureOptions		string	false	Opciones del control de firma. Solo aplica cuando fieldType es signature. Parámetros de entrada: template handDrawn upload Puede seleccionar múltiples opciones, separadas por ",", por defecto se seleccionan todas
			movable		boolean	false	Permitir mover la ubicación al firmar, por defecto es falso false-No permitir que el firmante ajuste la ubicación de su propio control de firma true-Permitir que el firmante ajuste la ubicación de su propio control de firma
			allowedOptions		array	false	Opciones que permiten al firmante aprobar, aplicable cuando fieldType es approval. El valor predeterminado es ["approve", "decline"] approve-Aprobar decline-Rechazar
			pageNo		string	false	Página de firma; las páginas consecutivas están conectadas con "-", las páginas individuales están conectadas con ",", por ejemplo: 1-3, 6-10
			posX		string	false	Coordenada del eje X Notas adicionales: Si fieldType es signature, la posición de las coordenadas se refiere al área de la firmaEsquina inferior izquierda； Si fieldType es stamp, la posición de las coordenadas se refiere al área del selloPunto centralPosición A partir del 3 de febrero de 2026, si fieldType es signature o stamp, la posición de las coordenadas se refiere a la posición del punto central del área del sello.
			posY		string	false	Coordenada del eje Y Información adicional: Si fieldType es signature, la posición de las coordenadas se refiere al área de la firmaEsquina inferior izquierda； Si fieldType es stamp, la posición de las coordenadas se refiere al área del selloPunto centralPosición A partir del 3 de febrero de 2026, si fieldType es signature o stamp, la posición de las coordenadas se refiere a la posición del punto central del área de sellado.
		fillConfigs			array	false	Completar la información del control
			fieldName		string	false	Nombre del control, límite de 128 caracteres
			required		boolean	false	¿Es obligatorio? Obligatorio por defecto true-Obligatorio falso-no obligatorio
			fieldType		string	false	Tipo de control: 1-Texto de una línea 15-Casilla de verificación
			textField		object	false	Propiedades del control de texto
				overflowType	int	false	Solo aplica al texto, por defecto 1 1-Reducir automáticamente el tamaño de la fuente 2-Restringir la entrada
				minFontSize	float	false	Solo aplica al texto, solo aplica a overflowType=1, por defecto 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	Ancho del control, por defecto 160px
				font	int	false	Solo funciona con texto, fuente, fuente SimSun predeterminada. 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	Solo aplica al texto, tamaño de fuente, predeterminado 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	Solo aplica al texto, color hexadecimal, predeterminado negro #000
				bold	boolean	false	Solo aplica al texto, si la fuente está en negrita, predeterminado falso true-Negrita false-Sin negrita
				italic	boolean	false	Solo aplica al texto, si es cursiva, por defecto es falso true-Cursiva false-No cursiva
				underline	boolean	false	Solo aplica al texto, si la fuente tiene subrayado, por defecto es falso true-Agregar subrayado false-No agregar subrayado
				lineThrough	boolean	false	Solo aplica a text, indica si se agrega una línea tachada, el valor predeterminado es false true-Agregar línea tachada false-No agregar línea tachada
				horizontalAlignment	string	false	Solo aplica a text, formato de centrado horizontal, el valor predeterminado es left LEFT-A la izquierda CENTER-Centrado RIGHT-A la derecha
			tickBoxField		object	false	Atributos de la casilla de verificación
				tickOptions	array	false	Solo es efectivo para Check, 1 por defecto 1-Gancho 2-Cruz
			posX		float	false	Coordenada X horizontal de la posición del control
			posY		float	false	Coordenada Y de la posición del control
			pageNo		string	false	Número de página donde se encuentra el control
		signDateConfigs			array	false	Información de la ubicación de la fecha de firma
			movable		boolean	false	Permitir mover la posición al firmar, el valor predeterminado es falso false- No permitir que el firmante ajuste la posición de su propio control de firma true-Permitir que el firmante ajuste la posición de sus propios controles de firma
			pageNo		string	false	Número de página de firma; los números de página consecutivos se conectan con "-", los números de página individuales se conectan con ",", por ejemplo: 1-3, 6-10 Si no son consecutivos, ingrese "," para separar
			posX		float	false	Desplazamiento del eje x, la esquina inferior izquierda de la página es el origen de las coordenadas
			posY		float	false	Desplazamiento del eje y, la esquina inferior izquierda de la página es el origen de las coordenadas
			signDateFormat		string	false	Formato de fecha de firma, el formato predeterminado es yyyy-MM-dd Formatos admitidos: yyyy年MM月dd日 yyyy-MM-dd yyyy/MM/dd dd.MM.yyyy MM dd yyyy dd MM yyyy

Ejemplo de solicitud

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

Parámetros de respuesta

Nombre del parámetro			Tipo	Descripción
envelopeId			string	ID del sobre
signFiles			array	Colección de documentos firmados
	fileKey		string	fileKey del documento firmado
attachments			array	Colección de archivos adjuntos del sobre
	fileKey		string	fileKey del archivo
signerInfos			array	Colección de información del firmante
	businessId		string	Número de negocio personalizado por el desarrollador, longitud 500
	userEmail		string	Dirección de correo electrónico del firmante
	userName		string	Nombre del firmante
	signOrder		int	Orden del nodo del firmante, el mínimo es 1
		accessCode	string	Contraseña de acceso a la página de firma

Ejemplo de respuesta

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