Iniciar sobre rápido

POST /esignglobal/v1/envelope/createAndStart

Descripción de la interfaz

Inicia rápidamente un sobre, incluyendo la creación del sobre, la adición de documentos para firmar y la adición de firmantes, entre otras funciones.

Soporte para inicio automático：Después de que la llamada a la interfaz sea exitosa, el sobre se crea e inicia con éxito, y el sobre comienza a fluir automáticamente.
Soporte para finalización automática：El sobre finaliza automáticamente después de que todas las partes firmantes hayan completado la firma.

Parámetros de solicitud

Nombre del parámetro					Tipo	Obligatorio	Descripción
subject					string	true	Asunto del sobre Ejemplo: “Offer Letter”
remark					string	false	Notas del sobre，Límite de longitud de 1000 caracteres
signerSettings					object	false	Operaciones permitidas para el firmante
	allowTransfer				boolean	false	¿Se permite al firmante transferir este sobre a otra persona para que lo firme? El valor predeterminado es falso. true: permite que el firmante en el sobre tenga el poder de transferir el sobre a otros; false: no permite que el firmante en el sobre tenga el poder de transferir el sobre a otros;
	allowModifyName				boolean	false	¿Se permite a la parte firmante modificar el nombre? Solo es efectivo para la firma de la plantilla, el valor predeterminado es falso. true: permite que el firmante modifique el nombre false: no permite que el firmante modifique el nombre
expireAfterSeconds					long	false	Tiempo de vencimiento del sobre, después de cuántos segundos el sobre vence Rango de vencimiento: 86,400 segundos (1 día) ~ 7,776,000 segundos (90 días)
redirectUrl					string	false	Debe ser una dirección https válida
callBackUrl					string	false	Dirección de devolución de llamada (longitud 500), debe cumplir con la dirección del protocolo https.
sendLaterAfterSeconds					long	false	Admite el envío diferido por el usuario, en segundos Rango de tiempo admitido: 3600 segundos (1 hora) ~ 259200 segundos (30 días)
CCInfos					array	false	Colección de información del destinatario de copia
	userEmail				string	false	Dirección de correo electrónico del destinatario de copia
	userName				string	false	Nombre del destinatario de copia, que se utiliza para mostrar el nombre del destinatario de copia en la página de firma y en el sobre. 【Atención】: No puede contener los siguientes 9 caracteres especiales: / \ : * " < > \| ？ ni ningún emoji
	customizeSettings				object	false	Configuración personalizada
		notificationSettings			object	false	Configuración personalizada de notificaciones
			notificationLanguage		string	false	Idioma de la notificación, el valor predeterminado es inglés en-US Inglés zh-CN Chino simplificado zh-Hant Chino tradicional ja-JP Japonés ES-MX Español
signFiles					array	true	Colección de información del archivo de firma, el orden de visualización es el orden en que se agregan los archivos.
	fileKey				string	true	fileKey del archivo de firma, solo se admite el formato PDF
attachments					array	false	Colección de archivos adjuntos del sobre, el orden de visualización es el orden en que se agregan los archivos.
	fileKey				string	false	fileKey del archivo
signerInfos					array	true	Colección de información del firmante
	businessId				string	false	Número de negocio personalizado por el desarrollador, límite de longitud de 500
	deliveryMethods				string	false	Método de notificación, el valor predeterminado es auto auto-Envía una notificación por correo electrónico cuando se pasa userEmail, envía una notificación por SMS cuando se pasa phoneNumber none-No enviar notificaciones de mensajes email-Enviar notificación por correo electrónico sms-Enviar notificación por SMS WhatsApp-Enviar notificación de WhatsApp
	userEmail				string	true	Dirección de correo electrónico del firmante
	userName				string	true	Nombre del firmante, utilizado para mostrar el nombre del firmante en la página de firma y el sobre. 【Nota】No puede contener los siguientes 9 caracteres especiales: / \ : * " < > \| ？ y todos los emojis
	phoneNumber				object	false	Número de teléfono, el valor predeterminado es vacío Es un parámetro obligatorio cuando se necesita enviar una notificación por SMS, se deben pasar tanto countryCode como number
		countryCode			string	false	Código internacional del país/región, no es necesario pasar "+"
		number			string	false	Sin verificación de formato, solo limita la longitud máxima a 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 Japonés ES-MX Español
	signOrder				int	true	Orden de firma del firmante, el mínimo es 1. Se puede especificar el mismo valor de orden para firmas desordenadas.
	anySigner				boolean	false	¿Admite la firma de cualquier persona? Predeterminado: falso true-Solo una persona necesita firmar el mismo signOrder false-Todas las personas en el mismo signOrder deben firmar
	authModes				string	false	Método de verificación, el valor predeterminado es noAuth noAuth-No verificar accessCode-Usar la contraseña de firma para verificar sms- Verificación OTP por SMS 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, cuando authModes=accessCodees obligatorio
			accessCode		string	false	Contenido de la contraseña, no distingue entre mayúsculas y minúsculas, puede contener letras y números, longitud máxima de 45
			promptInfo		string	false	Mensaje de sugerencia de la contraseña de acceso, no puede contener la contraseña de acceso, longitud máxima de 30, obligatorio cuando authModes=1.
		sms			object	false	Verificación OTP por SMS, cuando authModes=smses obligatorio
			countryCode		string	false	Código internacional del país/región, no es necesario ingresar “+”
			number		string	false	No se realiza la verificación de formato, solo se limita la longitud máxima a 13 dígitos
		idVerification			object	false	Configuración de verificación de documento de identidad, cuando authModes=idVerificationes obligatorio
			name		string	false	Nombre completo en la identificación del firmante, longitud máxima de 100 caracteres
		emailAuth			object	false	Verificación OTP por correo electrónico, cuando authModes=emailAuthes obligatorio
			authEmail		string	false	Dirección de correo electrónico de verificación de identidad del firmante
		digitalId			array	false	Verificación de identidad electrónica, obligatoria cuando authModes=digitalId
			authApp		string	false	Aplicación utilizada para la verificación de identidad electrónica singpass - Utilizar 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? Predeterminado: false true - Activar, false - No activar
	freeFormSign				boolean	false	¿El firmante puede firmar libremente? Valor predeterminado: false Notas adicionales: Cuando se selecciona freeFormSign como true, 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	Firmar archivo fileKey
		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, el valor predeterminado es signature signature-Control de firma stamp-Control de sello approval-Control de aprobación
			sizeRule		string	false	Método de visualización del tamaño del área de firma originalSize-Sellar de acuerdo con el tamaño real de la firma/sello targetSize-Ancho y alto del área de firma/sello personalizados Cuando sizeRule, height y width están vacíos, el sello se coloca de acuerdo con el tamaño real de la firma/sello; Cuando sizeRule está vacío y height y width no están vacíos, el sello se coloca de acuerdo con el tamaño especificado; Cuando sizeRule no está vacío, el sello se coloca de acuerdo con el método de visualización especificado.
			height		int	false	Altura del control de firma, aplicable a fieldType como signature/stamp, la unidad es px, solo se admite la entrada de enteros positivos, el valor predeterminado es auto (es decir, tamaño automático del sistema); Cuando fieldType=signature, el rango configurable es 20-250px; Cuando fieldType=stamp, el rango configurable 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 configurable es de 20 a 250 px; Cuando fieldType=stamp, el rango configurable es de 30 a 280 px;
			signatureOptions		string	false	Opciones del control de firma. Solo aplicable cuando fieldType es signature Parámetros de entrada posibles: template: firma de plantilla handDrawn: firma dibujada a mano upload: subir imagen de firma local Se pueden seleccionar varias opciones, separadas por ",", la selección predeterminada es todas
			movable		boolean	false	Permitir mover la posición al firmar, el valor predeterminado es false 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 su propio control de firma
			allowedOptions		array	false	Opciones que el firmante puede aprobar, aplicable cuando fieldType es approval. El valor predeterminado es ["approve", "decline"] approve-Aprobar decline-Rechazar
			pageNo		string	false	Páginas de firma; conecte las páginas consecutivas con "-", conecte las páginas individuales con "," Ejemplo: 1-3,6-10
			posX		float	false	Coordenada del eje x [Nota] Si fieldType es signature, la posición de la coordenada se refiere al área de firmaEsquina inferior izquierda； Si fieldType es stamp, la posición de la coordenada se refiere al área de estampadoPunto centralPosición A partir del 3 de febrero de 2026, si fieldType es signature o stamp, la posición de la coordenada se refiere a la posición del punto central del área de estampado.
			posY		float	false	Coordenada del eje y [Nota] Si fieldType es signature, la posición de la coordenada se refiere al área de firmaEsquina inferior izquierda； Si fieldType es stamp, la posición de la coordenada se refiere al área de estampadoPunto 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 estampado.
		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 false-No obligatorio
			fieldType		string	false	Tipo de control: 1-Texto de una sola línea 15-Casilla de verificación
			textField		object	false	Propiedades del control de texto
				overflowType	int	false	Solo aplica a text, 1 por defecto 1-Reducir automáticamente el tamaño de la fuente 2-Restringir la entrada
				minFontSize	float	false	Solo aplica a text, solo aplica a overflowType=1, 8 por defecto 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, 160px por defecto
				font	int	false	Solo aplica al texto, fuente, por defecto 宋体 (Songti) 1-宋体 (Songti) 2-新宋体 (Xin Songti) 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, 12 por defecto 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, negro #000 por defecto
				bold	boolean	false	Solo aplica al texto, si la fuente está en negrita, false por defecto true-Negrita false-Sin negrita
				italic	boolean	false	Solo aplica al texto, si está en cursiva, false por defecto true-Cursiva false-Sin cursiva
				underline	boolean	false	Solo aplica a texto, si la fuente tiene subrayado, por defecto es falso true-Agregar subrayado false-No agregar subrayado
				lineThrough	boolean	false	Solo aplica a texto, si se agrega tachado, por defecto es falso true-Agregar tachado false-No agregar tachado
				horizontalAlignment	string	false	Solo aplica a texto, formato de centrado horizontal, por defecto 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 aplica a tickBox, por defecto 1 1-Marca de verificación 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 posición de la fecha de firma
			movable		boolean	false	Permitir mover la posición al firmar, por defecto 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 su propio control 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 ","，Ejemplo: 1-3, 6-10; Si no es continuo, separe con ",".
			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 la fecha de firma, el formato predeterminado es aaaa-MM-dd Soporta formatos específicos: aaaa年MM月dd日 yyyy-MM-dd yyyy/MM/dd dd.MM.yyyy MM dd yyyy dd MM yyyy

Ejemplo de solicitud

{
    "subject": "员工入职合约",
    "remark": "这是描述",
    "expireAfterSeconds": 86400,
    "redirectUrl": "https://app-sml.esignglobal.com/home/main/esign/contract/list/inbox",
    "signFiles": [
      {
        "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c"
      },
      {
        "fileKey": "$c7567683-2fc1-47a5-82c1-570d4839afd8$3119805980"
      }
    ],
    "signerInfos": [
      {
        "userEmail": "sender_user@tsign.cn",
        "userName": "sender_user_name",
        "phoneNumber": {
        	"countryCode": "86",
        	"number": "158****9242"
        }
        "signOrder": 1,
        "authModes": "sms",
        "authConfig": {
            "sms": {
                "countryCode": "86",
                "number": "158****9242"
            }
        },
        "sealInfos": [
        {
            "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c",
            "signConfigs": [
              {
                "fieldType": "stamp",
                "pageNo": "1,3-5",
                "posX": 100.22222,
                "posY": 100.11111
              }
              "fillConfigs": [
              {
                "fieldId": "df0dd777bc774a2ba3fec4d108de242d",
                "fieldKey": "必填单行文本自动缩小字号最小字号Arial",
                "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": "888b899853544c49bd819d9f6d1e52cf",
                  "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
CCInfos		array	Conjunto de información del destinatario en copia
	userEmail	string	Dirección de correo electrónico del destinatario en copia
	userName	string	Nombre del destinatario en copia
signFiles		array	Conjunto de información del documento firmado
	fileKey	string	fileKey del documento firmado
attachments		array	Conjunto de archivos adjuntos del sobre
	fileKey	string	fileKey del archivo
signerInfos		array	Información de la firma
	businessId	string	Número de negocio personalizado por el desarrollador, longitud limitada a 500
	userEmail	string	Dirección de correo electrónico del firmante
	userName	string	Nombre del firmante
	signUrl	string	Dirección del enlace de firma
	signOrder	int	Orden de firma 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": [
      {
        "accessCode": "123456",
        "userEmail": "sender_user@tsign.cn",
        "signUrl": "http://app-test.esignglobal-inc.com/home/main/sign/start/base/dosign?envelopeId=4cd738a60225445f9d5f3afec468a639&signature=eyJhbGciOiJIUzI1NiIsInppcCI6IkRFRiJ9.eNqqVkrOzytJrShRsqpWSs0rS83JL0gNSSzO9kxRslJKtjC1MDKxTDVIMzA0SU4xSTIwNjAxSDRNTTVKMTIxTFOqrQUAAAD__w.YMBA5X9O8Ylk7x2rma-s1WxGwo2cjqy-O9CCQopzw88&tenantToken=AA0DDgQ0Y2Q3MzhhNjAyMjU0NDVmOWQ1ZjNhZmVjNDY4YTYzuQ4GNGNkNzM4YTYwMjI1NDQ1ZjlkNWYzYWZlYzQ2OGE2M7kOCjRjZDczOGE2MDIyNTQ0NWY5ZDVmM2FmZWM0NjhhNjO5AIBjNDIwMzg1ZDMyYzU0MGE4YTk1ZTE3ZTNkZmZjMDNm4g%3D%3D",
        "userName": "sender_user_name",
        "signOrder": "1"
      }
    ],
      "signFiles": [
      {
        "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c"
      },
      {
        "fileKey": "$c7567683-2fc1-47a5-82c1-570d4839afd8$3119805980"
      }
    ],
      "envelopeId": "4cd738a60225445f9d5f3afec468a639"
  },
  "message": "success"
}