Agregar firmante

Nombre del parámetro

Tipo

Obligatorio

Descripción

envelopeId

string

true

ID del sobre

signerInfos

array

true

Conjunto de información del firmante

businessId

string

false

Número de negocio personalizado por el desarrollador, longitud máxima de 500 caracteres

roleTypes

array

false

Método de operación del firmante, valor predeterminado: ["sign", "fill"]

fill-completar

sign-firmar

string

false

userEmail

string

false

Dirección de correo electrónico del firmante

documentVisibility

object

false

Configuración de visibilidad de archivos, todos visibles por defecto.

documentViewType

string

false

Estrategia de visibilidad, all por defecto; all significa que se pueden ver todos los documentos firmados dentro del sobre, limited significa que solo se pueden ver los documentos firmados por uno mismo y los documentos adicionales permitidos para la visualización.

viewableFileKeys

array

false

Lista de fileKey adicionales permitidos para ser vistos por el firmante especificado; solo se permite su envío y tiene efecto cuando documentViewType=limited.

phoneNumber

object

false

Obligatorio cuando se requiere notificación por SMS; tanto countryCode como number deben ser proporcionados, vacío por defecto.

countryCode

string

false

Código internacional del país/región, sin necesidad de incluir el signo '+'

number

string

false

Sin validación de formato, longitud máxima de 13 caracteres

customizeSettings

object

false

Configuración personalizada

notificationSettings

object

false

Configuración personalizada para notificaciones

customizeMessage

string

false

Notificación de mensaje exclusivo, 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

userName

string

true

Nombre del firmante, que se mostrará en la página de firma y en el flujo para indicar quién firma.

[Nota] No debe contener los siguientes 9 caracteres especiales: / \ : * " < > | ? ni ningún emoji

signOrder

int

true

Orden de firma del firmante, con un valor mínimo de 1. Para firmas simultáneas, se puede asignar el mismo valor de orden.

signTaskSuspend

boolean

false

¿Se debe configurar un nodo de bloqueo del proceso antes de esta posición de firma? El valor predeterminado es false. true: configurar el nodo de bloqueo; false: no configurar el nodo de bloqueo. La configuración de bloqueo dentro de un grupo de firmas OR con el mismo signOrder debe ser consistente.

suspensionKey

string

false

Identificador del nodo de bloqueo, máximo 500 caracteres, único dentro del mismo sobre. Obligatorio cuando signTaskSuspend=true; no se debe proporcionar cuando signTaskSuspend=false o no se envía.

suspendReason

string

false

Motivo del bloqueo. No puede estar vacío al proporcionarlo, máximo 50 caracteres. Solo se puede enviar cuando signTaskSuspend=true; si no se envía, se entiende que se requiere la espera del procesamiento por parte de un sistema externo. No se debe proporcionar cuando signTaskSuspend=false o no se envía.

anySigner

boolean

false

¿Se permite que cualquier persona firme? El valor predeterminado es false

true: solo una persona dentro del mismo signOrder necesita firmar

false: todas las personas dentro del mismo signOrder deben firmar

authModes

string

false

Método de autenticación de identidad, el valor predeterminado es noAuth

Tipo de enumeración:

authConfig

object

false

Configuración del método de verificación

accessCode

object

false

Configuración de la contraseña de firma, obligatorio 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 de 45 caracteres

promptInfo

string

false

Mensaje de aviso de la 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 SMS OTP, obligatorio cuando authModes=sms

countryCode

string

false

Código internacional del país/región, sin incluir el signo "+"

number

string

false

No se realiza validación de formato, longitud máxima de 13 dígitos

idVerification

object

false

Configuración de verificación de documento de identidad, obligatorio cuando authModes=idVerification

name

string

false

Nombre completo tal como aparece 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, obligatoria cuando authModes=digitalId

authApp

string

false

Aplicación utilizada para la verificación de identidad electrónica

singpass-Autenticación de identidad mediante Singpass

iamsmart-Autenticación de identidad mediante MyInfo

idNumber

string

false

Número de documento de identidad pendiente de verificación por el firmante

Cuando authApp=singpassla regla de entrada es: una letra mayúscula + 7 u 8 dígitos + una 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 numéricos;

3. Finalmente, un código de comprobación que puede ser un número (0-9) o una letra (A-Z). Ejemplo: A888888(A)

whatsappAuth

object

false

Verificación OTP por WhatsApp, obligatoria cuando authModes=whatsappAuth

countryCode

string

false

Código internacional del país/región, sin incluir el símbolo '+'

number

string

false

No se realiza validación de formato, solo se limita la longitud máxima a 13 dígitos

digitalSignature

boolean

false

Si se habilita la firma digital, valor predeterminado false

true-Habilitar

false-No habilitar

tsp

string

false

Seleccione el TSP que utilizará el firmante, valor predeterminado false.

Si no se establece, el firmante elegirá libremente el TSP que desea utilizar. Las opciones incluyen:

vinotek、eSignPersonal、localCertificates、iAmSmart、vnptSmartCa、adacomOneShot、audkenni

belgianIdCard、certEuropeUsbToken、certSignWebSign、chaveMovel、croatianIdCard、czechIdCard、dTrustSignMe、diia

estonianIdCard、estonianMobileId、evrotrust、finnishIdCard、frejaEid、frejaEidSign、gseGestionDeSeguridadElectronica、halcom

harica、idAustriaATrustSignatur、infoCert、ltId、latvianIdCard、latvianEParakstsMobile、lithuanianIdCard、lithuanianMobileId

mscTrustGate、mitId、norwegianBankId、oneId、pscWorldWallet、spid、serproId、simplySign

smartId、swedenBankId、swissId、swisscom、transSped、trustAsia、zealidApp、certMe

certSignUsbToken、eCertChile、eMudhra、itsme、mojeId、emdha

freeFormSign

boolean

false

Si el firmante puede usar un sello de forma libre, valor predeterminado false

Complemento de explicación:

Cuando freeFormSign se establece en true, no es necesario transmitir otros parámetros bajo sealInfos. Si se transmiten simultáneamente, freeFormSign tiene prioridad sobre sealInfos y los parámetros bajo sealInfos no surtirán efecto.

[Nota] La firma de forma libre significa que no hay restricción en la cantidad ni en 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 firmado

signConfigs

array

false

Información de la posición del control; es obligatorio especificar la información de posición del control para poder realizar la firma electrónica.

fieldType

string

false

Tipo de control, parámetros de entrada posibles:

signature-Control de firma

stamp-Control de sello

El valor predeterminado es signature

Si es obligatorio, el valor predeterminado es obligatorio

true-Obligatorio

false-No obligatorio

signFieldStyle

string

false

Método de colocación del sello para el control de firma, el valor predeterminado es normalSeal.

normalSeal-Sello normal

pagingSeal-Sello de página continua

Solo los controles de firma y de sello admiten la configuración del sello de página continua.

pagingSealMode

string

false

Rango de páginas para la colocación del sello de página continua, el valor predeterminado es all.

all-Todos los números de página

assignedPages-Números de página específicos

even-Páginas pares

odd-Páginas impares

Solo se admite la especificación cuando signFieldStyle=pagingSeal.

sizeRule

string

false

Modo de visualización del tamaño del área de firma

originalSize- Colocar el sello según el tamaño real de la firma/sello

targetSize- Personalizar el ancho y alto del área de firma/sello

Cuando sizeRule, height y width están vacíos, colocar 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, colocar el sello según el tamaño especificado;

Cuando sizeRule no está vacío, colocar el sello según el modo de visualización especificado;

No es necesario especificar este parámetro para los sellos de página; solo se colocan según el tamaño real.

height

int

false

Altura del control de firma, aplicable cuando fieldType es signature/stamp, en unidades de px. Solo se admiten enteros positivos como entrada. 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;

No es necesario especificar este parámetro para los sellos de página.

width

int

false

Anchura del control de firma, aplicable cuando fieldType es signature/stamp, en unidades de px. Solo se admiten enteros positivos como entrada. 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 página cruzada no requiere especificar este parámetro.

signatureOptions

string

false

Opciones del control de firma. Solo aplicable cuando fieldType es signature.

Parámetros de entrada posibles:

template

handDrawn

upload

aiHandDrawn

Selección múltiple permitida, separados por ","; selección completa por defecto

movable

boolean

false

Permitir mover la posición durante la firma; valor predeterminado: false

false- No se permite que el firmante ajuste la posición de su propio control de firma

true- Se permite que el firmante ajuste la posición de su propio control de firma

allowedOptions

array

false

Opciones que permiten al firmante aprobar o rechazar; aplicable cuando fieldType es approval. Valor predeterminado: ["approve", "decline"]

approve- Aprobar

decline- Rechazar

pageNo

string

false

Números de página de firma; páginas consecutivas se conectan con "-", páginas individuales se conectan con ","; por ejemplo: 1-3, 6-10

Cuando pagingSealMode=assignedPages, se proporciona el rango de páginas para aplicar el sello de página cruzada. El sello de página cruzada solo puede utilizarse en archivos con más de una página.

posX

string

false

Coordenada en el eje X

Notas adicionales:

Si fieldType es signature, la posición de coordenadas se refiere a la zona de firmaesquina inferior izquierda；

Si fieldType es stamp, la posición de las coordenadas se refiere al área del sello.punto centralposición

A partir del 3 de febrero de 2026, si fieldType es signature o stamp, su posición de coordenadas se refiere al punto central del área del sello.

El sello de unión puede enviarse como 0, no puede enviarse como null; el control está fijado en el borde derecho del documento.

posY

string

false

coordenada del eje Y

Notas adicionales:

Si fieldType es signature, la posición de las coordenadas se refiere al área de firma.esquina inferior izquierda；

Si fieldType es stamp, la posición de las coordenadas se refiere al área del sello.punto centralposición

A partir del 3 de febrero de 2026, si fieldType es signature o stamp, su posición de coordenadas se refiere al punto central del área del sello.

fillConfigs

array

false

completar la información del control

fieldName

string

false

Nombre del control, límite de caracteres: 128

required

boolean

false

Campo obligatorio, por defecto es obligatorio

true - Obligatorio

false - 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 a text, valor por defecto: 1

1 - Reducir automáticamente el tamaño de fuente

2 - Limitar la entrada

minFontSize

float

false

Solo aplica a text y solo cuando overflowType=1, valor 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, valor por defecto: 160px

font

int

false

Solo aplica a text, fuente, valor por defecto: SimSun.

1 - SimSun

2-SimSun

4-SimHei

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, por defecto 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 a text, color hexadecimal, por defecto negro #000

bold

boolean

false

Solo aplica a text, si la fuente está en negrita, por defecto false

true-negrita

false-no negrita

italic

boolean

false

Solo aplica a text, si la fuente está en cursiva, por defecto false

true-cursiva

false-no cursiva

underline

boolean

false

Solo aplica a text, si la fuente tiene subrayado, por defecto false

true-subrayado

false-sin subrayado

lineThrough

boolean

false

Solo aplica a text, si se añade o no un tachado, por defecto false

true: añadir tachado

false: no añadir tachado

horizontalAlignment

string

false

Solo aplica a text, formato de centrado horizontal, por defecto left

LEFT: alineado a la izquierda

CENTER: centrado

RIGHT: alineado a la derecha

tickBoxField

object

false

Propiedades del cuadro de verificación

tickOptions

array

false

Solo aplica a Check, por defecto 1

1: marca de verificación

2: aspa

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 de la posición de la fecha de firma

movable

boolean

false

Permitir mover la posición al firmar, valor predeterminado false

false-No se permite que el firmante ajuste la posición de sus propios controles de firma

true-Se permite que el firmante ajuste la posición de sus propios controles de firma

pageNo

string

false

Número(s) de página(s) a firmar; los números de página consecutivos se conectan con "-", y los números de página individuales se conectan con ",", por ejemplo: 1-3, 6-10

Si no son consecutivos, utilizar "," como separador

posX

float

false

Desplazamiento en el eje x, el origen de coordenadas es la esquina inferior izquierda de la página

posY

float

false

Desplazamiento en el eje y, el origen de coordenadas es la esquina inferior izquierda de la página

signDateFormat

string

false

Formato de la fecha de firma, el formato predeterminado es yyyy-MM-dd

Soporta especificar el siguiente formato:

dd de MM de yyyy

yyyy-MM-dd

yyyy/MM/dd

dd.MM.yyyy

MM dd yyyy

dd MM yyyy