Crear sobre rápidamente

POST /esignglobal/v1/envelope/createAndStart

Descripción de la interfaz

Iniciación rápida de un sobre, que incluye funciones como crear un sobre, añadir archivos pendientes de firma y añadir firmantes.

Soporte para activación automática: Tras el éxito de la llamada a la interfaz, se crea y activa correctamente el sobre, comenzando automáticamente su flujo de trabajo.
Soporte para finalización automática: Una vez que todas las partes firmantes han completado la firma, el sobre se cierra automáticamente.

Parámetros de solicitud

Nombre del parámetro					Tipo	Obligatorio	Descripción
subject					string	true	Asunto del sobre Ejemplo: "Carta de oferta"
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 que el firmante transfiera este sobre a otra persona para su firma? El valor predeterminado es false. true: permite que el firmante del sobre tenga la facultad de transferir el sobre a otra persona; false: no permite que el firmante del sobre tenga la facultad de transferir el sobre a otra persona;
	allowModifyName				boolean	false	¿Se permite que la parte firmante modifique su nombre? Esto solo se aplica a las firmas en plantillas. El valor predeterminado es false. true: permite al firmante modificar su nombre false: no permite al firmante modificar su nombre
expireAfterSeconds					long	false	Fecha de vencimiento del sobre; indica cuántos segundos deben transcurrir antes de que el sobre venza. Rango de vencimiento: de 86.400 segundos (1 día) 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 máxima de 500 caracteres), debe cumplir con el protocolo https.
sendLaterAfterSeconds					long	false	Permite la demora del usuario para enviar, expresada en segundos. Rango de tiempo admitido: de 3.600 segundos (1 hora) a 259.200 segundos (30 días).
autoFinish					boolean	false	Controla si el sobre finaliza automáticamente. El valor predeterminado es true. true- Finalización automática del sobre false- Finalización manual del sobre
CCInfos					array	false	Conjunto de información del destinatario en copia
	userEmail				string	false	Dirección de correo electrónico del destinatario en copia
	userName				string	false	Nombre del destinatario en copia, utilizado para mostrar el nombre del destinatario en copia en la página de firma y en el sobre externo. [Nota]: No debe contener los siguientes 9 caracteres especiales: / \ : * " < > \| ? ni ningún emoji
	customizeSettings				object	false	Configuración personalizada
		notificationSettings			object	false	Configuración personalizada para notificaciones
			notificationLanguage		string	false	Idioma de notificación; por defecto se utiliza la configuración "idioma de notificación predeterminado" en-US Inglés zh-CN Chino simplificado zh-Hant Chino tradicional ja-JP Japonés es-MX Español pt-PT Portugués th-TH Tailandés id-ID Indonesio vi-VN vietnamita ms-MY malayo fil-PH filipino de-DE alemán fr-FR francés ru-RU ruso it-IT italiano ko-KR coreano
signFiles					array	true	Conjunto de información de documentos firmados, el orden de visualización corresponde al orden de adición de los documentos.
	fileKey				string	true	fileKey del documento firmado; solo se admite formato PDF
	documentFields				array	false	Lista de controles de dimensiones del documento. Se utiliza para agregar controles de dimensiones del documento en un archivo específico sin vincularlos a un firmante.
		fieldType			string	false	Tipo de control. Indique eMeterai para representar el control de impuesto de timbre de Indonesia.
		pageNo			string	false	Número de página donde se encuentra el control. El control de impuesto de timbre de Indonesia solo admite la especificación de una única página; debe introducirse un número de página individual y no se admiten formatos de múltiples páginas continuas o discontinuas como 1-3 o 1,3.
		posX			float	false	Desplazamiento en el eje x, siendo la esquina inferior izquierda de la página el origen de coordenadas. El rango de coordenadas es el mismo que el de otros controles.
		posY			float	false	Desplazamiento en el eje y, siendo la esquina inferior izquierda de la página el origen de coordenadas. El rango de coordenadas es el mismo que el de otros controles.
attachments					array	false	Conjunto de archivos adjuntos del sobre, el orden de visualización corresponde al orden de adición de los archivos.
	fileKey				string	false	fileKey del archivo
signerInfos					array	true	Conjunto de información del firmante
	businessId				string	false	Número de negocio personalizado por el desarrollador, límite de longitud 500
	roleTypes				array	false	Método de operación del firmante, valor predeterminado `["sign", "fill"]` fill-completar sign-firmar
	deliveryMethods				string	false	Método de notificación, predeterminado es auto auto- Al pasar userEmail se envía una notificación por correo electrónico; al pasar phoneNumber se envía una notificación por SMS none- No se envían notificaciones de mensajes email- Se envía notificación por correo electrónico sms- Se envía notificación por SMS WhatsApp- Se envía notificación por WhatsApp
	userEmail				string	false	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 en la presentación externa del sobre. [Nota] No debe contener los siguientes 9 caracteres especiales: / \ : * " < > \| ? ni ningún emoji
	minimumReadingDuration				int	false	Tiempo de cuenta regresiva obligatorio para la lectura en la página de configuración; valor predeterminado: 0 (unidad: segundos, máximo 999) 0 o no enviar indica que no se activa; no hay cuenta regresiva de lectura
	readToEndRequired				boolean	false	Indica si es obligatorio leer hasta el final. Valor predeterminado: false; true indica activado; false o no enviar indica desactivado.
	phoneNumber				object	false	Número de teléfono; vacío por defecto Parámetro obligatorio cuando se requiere notificación por SMS; deben enviarse tanto countryCode como number
		countryCode			string	false	Código internacional del país/región; no incluir el signo «+»
		number			string	false	Sin validación de formato; solo se limita la longitud máxima a 13 dígitos
	customizeSettings				object	false	Configuración personalizada
		notificationSettings			object	false	Configuración personalizada para notificaciones
			customizeMessage		string	false	Notificación de mensajes exclusivos; límite de caracteres: 200
			notificationLanguage		string	false	Idioma de notificación; toma por defecto la configuración «idioma de notificación predeterminado» en-US inglés zh-CN chino simplificado zh-Hant chino tradicional ja-JP japonés es-MX español pt-PT portugués th-TH tailandés id-ID indonesio vi-VN vietnamita ms-MY malayo fil-PH filipino de-DE alemán fr-FR francés ru-RU ruso it-IT italiano ko-KR coreano
	signOrder				int	true	Orden de firma del firmante, mínimo 1. Las firmas no ordenadas pueden especificar el mismo valor de orden.
	anySigner				boolean	false	¿Se admite la firma por cualquier persona? El valor predeterminado es false true- En un mismo signOrder, solo una persona debe firmar false- En un mismo signOrder, todas las personas deben firmar
	authModes				string	false	Método de verificación. El valor predeterminado es noAuth noAuth- Sin verificación accessCode- Verificación mediante contraseña de firma sms- Verificación OTP por SMS idVerification- Verificación mediante documento de identidad emailAuth- Verificación OTP por correo electrónico digitalId- Verificación de identidad electrónica whatsappAuth- Verificación OTP por WhatsApp
	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 máxima: 45 caracteres
			promptInfo		string	false	Mensaje de indicación de contraseña de acceso, no puede contener la contraseña de acceso, límite de longitud 30, obligatorio cuando authModes=accessCode
		sms			object	false	Verificación OTP por SMS, obligatorio cuando authModes=sms
			countryCode		string	false	Código internacional del país/región, sin necesidad de incluir «+»
			number		string	false	No se realiza validación de formato, solo se limita la longitud máxima a 13 caracteres
		idVerification			object	false	Configuración de verificación de documento de identidad, obligatorio cuando authModes=idVerification
			name		string	false	Nombre completo en el documento de identidad del firmante, longitud máxima de 100 caracteres
		emailAuth			object	false	Verificación OTP por correo electrónico, obligatorio cuando authModes=emailAuth
			authEmail		string	false	Dirección de correo electrónico para la verificación de identidad del firmante
		digitalId			array	false	Verificación de identidad electrónica, obligatorio cuando authModes=digitalId
			authApp		string	false	Aplicación utilizada para la verificación de identidad electrónica singpass- Utilizar Singpass para la autenticación de identidad iamsmart-Autenticación de identidad mediante i AM Smart
			idNumber		string	false	Número de documento de identidad del firmante pendiente de verificación Cuando authApp=singpassla regla de entrada es: letra mayúscula + 7 u 8 dígitos + letra mayúscula Cuando authApp=iamsmartla regla de entrada es: 1. Una letra mayúscula (A-Z) o dos letras mayúsculas (AA-ZZ) como inicio de la secuencia; 2. seguido de 6 dígitos; 3. finalmente un código de verificación, que puede ser un número (0-9) o una letra (A-Z). Ejemplo: A888888(A)
		whatsappAuth			object	false	Verificación OTP de WhatsApp, obligatorio cuando authModes=whatsappAuth
			countryCode		string	false	Código internacional del país/región, sin incluir el símbolo '+'
			number		string	false	Sin validación de formato, solo se limita la longitud máxima a 13 caracteres
	digitalSignature				boolean	false	Indica si está habilitada la firma digital, valor predeterminado false true: habilitado, false: no habilitado
	freeFormSign				boolean	false	Indica si el firmante puede aplicar su sello de forma libre, valor predeterminado false Notas adicionales: Cuando freeFormSign se establece en true, no es necesario proporcionar otros parámetros bajo sealInfos. Si se proporcionan ambos, freeFormSign tiene prioridad sobre sealInfos y los parámetros bajo sealInfos no surtirán efecto. [Nota]La firma libre no limita 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 documento a firmar
		signConfigs			array	false	Información de la posición del control; es obligatorio especificar la posición del control para poder realizar la firma electrónica.
			fieldType		string	false	Tipo de control, por defecto signature signature- Control de firma stamp- Control de sello approval- Control de aprobación
			required		boolean	false	Si es obligatorio, por defecto es obligatorio true- Obligatorio false- No obligatorio
			signFieldStyle		string	false	Método de colocación del sello en el control de firma, por defecto normalSeal. normalSeal-Sello ordinario pagingSeal-Sello de costura Solo los controles de firma y de sello admiten la configuración del sello de costura.
			pagingSealMode		string	false	Rango de páginas para aplicar el sello de costura; el valor predeterminado es all. all-Todas las páginas assignedPages-Páginas específicas even-Páginas pares odd-Páginas impares Solo se admite especificar cuando signFieldStyle=pagingSeal.
			sizeRule		string	false	Modo de visualización del tamaño del área de firma originalSize-Aplicar el sello 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 aplica el sello según el tamaño real de la firma/sello; Cuando sizeRule está vacío pero height y width no lo están, se aplica el sello según el tamaño especificado; Cuando sizeRule no está vacío, se aplica el sello según el modo de visualización especificado; El sello de solapado no requiere especificar este parámetro; se aplica únicamente según las dimensiones reales.
			height		int	false	Altura del control de firma, aplicable cuando fieldType es signature/stamp, en unidades de px. Solo se admiten enteros positivos como valor; 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; El sello de solapado no requiere especificar este parámetro.
			width		int	false	Anchura del control de firma, aplicable cuando fieldType es signature/stamp, en unidades de px. Solo se admiten enteros positivos como valor; 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; El sello de solapado no requiere especificar este parámetro.
			signatureOptions		string	false	Opciones del control de firma. Solo aplicable cuando fieldType es signature Valores posibles: template: firma basada en plantilla handDrawn: firma dibujada a mano upload: imagen de firma cargada localmente Se pueden seleccionar varias opciones, separadas por ","; la selección predeterminada es todas.
			movable		boolean	false	Permitir mover la posición al firmar, por defecto false false: no se permite que el firmante ajuste la posición de sus controles de firma true: se permite que el firmante ajuste la posición de sus controles 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	Números de página de firma; las páginas consecutivas se conectan con "-" y las páginas individuales se conectan con "," Ejemplo: 1-3,6-10 Se transmite el rango de páginas donde se colocará el sello de costura cuando pagingSealMode=assignedPages. El sello de costura solo puede utilizarse en documentos de más de una página.
			posX		float	false	Coordenada del eje x [Nota] Si fieldType es signature, la posición de las coordenadas se refiere a la zona de firmaEsquina inferior izquierda； Si fieldType es stamp, la posición de las coordenadas se refiere a la zona de estampadoPunto centralPosición A partir del 3 de febrero de 2026, cuando fieldType sea signature o stamp, la posición de las coordenadas se refiere al punto central del área de sello. El valor para el sello de unión puede ser 0, pero no null; el control está fijado en el borde derecho del documento.
			posY		float	false	Coordenada del eje Y [Nota] Si fieldType es signature, la posición de las coordenadas se refiere al área de firmaEsquina inferior izquierda； Si fieldType es stamp, la posición de las coordenadas se refiere al área de selloPunto centralPosición A partir del 3 de febrero de 2026, cuando fieldType sea signature o stamp, la posición de las coordenadas se refiere al punto central del área de sello.
		fillConfigs			array	false	Rellenar la información del control
			fieldName		string	false	Nombre del control, límite de caracteres: 128
			required		boolean	false	Campo obligatorio, por defecto obligatorio 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, valor predeterminado 1 1-Reducir automáticamente el tamaño de fuente 2-Limitar entrada
				minFontSize	float	false	Solo aplica a text, solo aplica cuando overflowType=1, valor predeterminado 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, valor predeterminado 160px
				font	int	false	Solo aplica a text, fuente, valor predeterminado SimSun 1-SimSun 2-Nuevo SimSun 4-Heiti 5-Kaiti 6-Arial 7-Helvetica 9-Times New Roman 10-FangSong 11-Georgia 12-Monospace
				fontSize	float	false	Solo aplica a text, tamaño de fuente, valor 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 afecta al texto, color hexadecimal, negro por defecto #000
				bold	boolean	false	Solo afecta al texto, si la fuente está en negrita, falso por defecto true-negrita false-sin negrita
				italic	boolean	false	Solo afecta al texto, si la fuente está en cursiva, falso por defecto true-cursiva false-no cursiva
				underline	boolean	false	Solo afecta al texto, si la fuente tiene subrayado, falso por defecto true-subrayado false-sin subrayado
				lineThrough	boolean	false	Solo afecta al texto, si la fuente tiene tachado, falso por defecto true-tachado false-sin tachado
				horizontalAlignment	string	false	Solo afecta al texto, formato de alineación horizontal, izquierda por defecto IZQUIERDA-a la izquierda CENTER-centrado RIGHT-derecha
			tickBoxField		object	false	Propiedades de la casilla de verificación
				tickOptions	array	false	Solo aplica a tickBox, valor por defecto 1 1-marca de verificación 2-cruz
			posX		float	false	Coordenada X 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 sobre la posición de la fecha de firma
			movable		boolean	false	Permitir mover la posición durante la firma, valor por defecto false false-no se permite al firmante ajustar la posición de sus controles de firma true-se permite al firmante ajustar la posición de sus controles de firma
			pageNo		string	false	Número(s) de página(s) para firmar; las páginas consecutivas se conectan con "-", y las no consecutivas con ",". Ejemplo: 1-3, 6-10; Si no son consecutivas, utilice "," como separador.
			posX		float	false	Desplazamiento en el eje x, con el origen de coordenadas en la esquina inferior izquierda de la página
			posY		float	false	Desplazamiento en el eje y, con el origen de coordenadas en la esquina inferior izquierda de la página
			signDateFormat		string	false	Formato de la fecha de firma; el formato predeterminado es yyyy-MM-dd Se admite el siguiente formato: aaaa año MM mes dd día yyyy-MM-dd yyyy/MM/dd dd.MM.yyyy MMM dd,yyyy dd MMM 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 de los destinatarios 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 de los documentos firmados
	fileKey	string	Clave de archivo para firmar
attachments		array	Conjunto de archivos adjuntos del sobre
	fileKey	string	Clave de archivo
signerInfos		array	Información de firma
	recipientId	string	ID del firmante
	businessId	string	Número de negocio personalizado por el desarrollador, límite de longitud 500
	userEmail	string	Dirección de correo electrónico del firmante
	userName	string	Nombre del firmante
	signUrl	string	URL del enlace de firma
	signOrder	int	Orden de firma del firmante, mínimo 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"
}