Adicionar signatário

Nome do parâmetro

Tipo

Obrigatório

Descrição

envelopeId

string

true

ID do envelope

signerInfos

array

true

Conjunto de informações do signatário

businessId

string

false

Número de negócio personalizado pelo desenvolvedor, comprimento máximo de 500 caracteres

roleTypes

array

false

Método de operação do signatário, valor padrão é ["sign", "fill"]

fill-preenchimento

sign-assinatura

string

false

userEmail

string

false

Endereço de e-mail do signatário

documentVisibility

object

false

Configuração de visibilidade dos arquivos, padrão: todos visíveis.

documentViewType

string

false

Estratégia de visibilidade, padrão: all; all permite visualizar todos os documentos assinados dentro do envelope; limited permite visualizar apenas os próprios documentos assinados e os documentos adicionais permitidos para visualização.

viewableFileKeys

array

false

Lista de fileKey adicionalmente permitida para visualização pela parte signatária especificada; só pode ser fornecida e terá efeito quando documentViewType=limited.

phoneNumber

object

false

Obrigatório quando for necessário enviar notificações por SMS; tanto countryCode quanto number devem ser informados. O valor padrão é vazio.

countryCode

string

false

Código internacional do país/região, sem necessidade de incluir o símbolo “+”

number

string

false

Sem validação de formato, comprimento máximo de 13 caracteres.

customizeSettings

object

false

Configuração personalizada

notificationSettings

object

false

Configurações personalizadas para notificações

customizeMessage

string

false

Notificação de mensagem exclusiva, limite de 200 caracteres

notificationLanguage

string

false

Idioma da notificação, padrão: utiliza a configuração “idioma padrão de notificação”

en-US Inglês

zh-CN Chinês Simplificado

zh-Hant Chinês Tradicional

ja-JP Japonês

es-MX espanhol

pt-PT português
th-TH tailandês
id-ID indonésio
vi-VN vietnamita
ms-MY malaio
fil-PH filipino
de-DE alemão
fr-FR francês
ru-RU russo
it-IT italiano
ko-KR coreano

userName

string

true

Nome do signatário, exibido na página de assinatura e no fluxo para o público externo.

[Atenção] Não deve conter os seguintes 9 caracteres especiais: / \ : * " < > | ? nem qualquer emoji

signOrder

int

true

Ordem de assinatura do signatário, com valor mínimo de 1. Para assinaturas sem ordem específica, pode-se atribuir o mesmo valor de ordem.

signTaskSuspend

boolean

false

Se deve configurar um nó de bloqueio de fluxo antes deste local de assinatura, o padrão é false. true - configura o nó de bloqueio; false - não configura o nó de bloqueio. A configuração de bloqueio dentro do grupo de assinatura OR com o mesmo signOrder deve ser consistente.

suspensionKey

string

false

Identificador do nó de bloqueio, máximo de 500 caracteres, único dentro do mesmo envelope. Obrigatório quando signTaskSuspend=true; não pode ser transmitido quando signTaskSuspend=false ou não for fornecido.

suspendReason

string

false

Motivo do bloqueio, não pode estar vazio ao ser transmitido, máximo de 50 caracteres. Só pode ser transmitido quando signTaskSuspend=true; se não for transmitido, o padrão indica que é necessário aguardar o processamento pelo sistema externo. Não pode ser transmitido quando signTaskSuspend=false ou não for fornecido.

anySigner

boolean

false

Se suporta a assinatura por qualquer pessoa, o padrão é false

true - Apenas uma pessoa precisa assinar no mesmo signOrder

false - Todas as pessoas no mesmo signOrder precisam assinar

authModes

string

false

Método de autenticação de identidade, o padrão é noAuth

Tipo enumeração:

authConfig

object

false

Configuração do método de verificação

accessCode

object

false

Configuração da senha de assinatura, obrigatório quando authModes=accessCode, é obrigatório

accessCode

string

false

Conteúdo da senha, sem distinção entre maiúsculas e minúsculas, pode conter letras e números, comprimento máximo de 45 caracteres

promptInfo

string

false

Mensagem de aviso da senha de acesso, não pode conter a própria senha de acesso, limite de comprimento 30, obrigatório quando authModes=accessCode, é obrigatório.

sms

object

false

Verificação OTP por SMS, obrigatório quando authModes=sms, é obrigatório

countryCode

string

false

Código internacional do país/região, sem o símbolo “+”

number

string

false

Sem validação de formato, comprimento máximo de 13 dígitos

idVerification

object

false

Configuração de verificação por documento de identificação, obrigatório quando authModes=idVerification, é obrigatório

name

string

false

Nome completo conforme consta no documento de identificação do signatário, comprimento máximo de 100 caracteres

emailAuth

object

false

Validação OTP por e-mail, obrigatório quando authModes=emailAuth, é obrigatório

authEmail

string

false

Endereço de e-mail para verificação da identidade do signatário

digitalId

array

false

Verificação de identidade eletrônica, obrigatório quando authModes=digitalId

authApp

string

false

Aplicativo utilizado para verificação de identidade eletrônica

singpass- Usar Singpass para autenticação de identidade

iamsmart- Usar SmartID para autenticação de identidade

idNumber

string

false

Número do documento de identificação do signatário a ser verificado

Quando authApp=singpass, a regra de entrada é: letra maiúscula + 7 ou 8 dígitos + letra maiúscula

Quando authApp=iamsmart, a regra de entrada é:

1. Uma letra maiúscula (A-Z) ou duas letras maiúsculas (AA-ZZ), como início da sequência;

2. Seguido por 6 dígitos numéricos;

3. Por fim, um dígito de verificação, que pode ser numérico (0-9) ou alfabético (A-Z). Exemplo: A888888(A)

whatsappAuth

object

false

Verificação OTP via WhatsApp, obrigatório quando authModes=whatsappAuth

countryCode

string

false

Código internacional do país/região, sem incluir o símbolo '+'

number

string

false

Não realizar validação de formato, limitar apenas o comprimento máximo a 13 dígitos

digitalSignature

boolean

false

Se ativar a assinatura digital, padrão false

true- Ativar

false- Não ativar

tsp

string

false

Selecionar o TSP usado pelo signatário, padrão false.

Quando não definido, o signatário escolhe livremente o TSP a ser utilizado. Enumerações incluem:

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

Se o signatário pode usar carimbo/forma de assinatura livre, valor padrão false

Complemento:

Quando freeFormSign estiver definido como true, os demais parâmetros sob sealInfos não precisam ser enviados. Se ambos forem enviados simultaneamente, freeFormSign tem prioridade sobre sealInfos, e os parâmetros em sealInfos não terão efeito.

[Atenção] Assinatura livre significa que não há restrição quanto ao número e à posição dos carimbos/assinaturas que o signatário pode arrastar para dentro do documento.

sealInfos

array

false

Informações da tarefa de assinatura

fileKey

string

true

fileKey do arquivo assinado

signConfigs

array

false

Informações de posicionamento do controle; é obrigatório especificar as informações de posicionamento do controle para realizar a assinatura eletrônica.

fieldType

string

false

Tipo de controle, parâmetros aceitos:

signature- Controle de assinatura

stamp-Controle de carimbo

O padrão é signature

Se é obrigatório, o padrão é obrigatório

true-Obrigatório

false-Não obrigatório

signFieldStyle

string

false

Método de aplicação do carimbo para controles de assinatura, o padrão é normalSeal.

normalSeal-Carimbo comum

pagingSeal-Carimbo de página inteira

Apenas controles de assinatura e controles de carimbo suportam a configuração de carimbos de página inteira.

pagingSealMode

string

false

Intervalo de páginas para aplicação do carimbo de página inteira, o padrão é all.

all-Todas as páginas

assignedPages-Páginas específicas

even-Páginas pares

odd-Páginas ímpares

Suporta especificação apenas quando signFieldStyle=pagingSeal.

sizeRule

string

false

Modo de exibição das dimensões da área de assinatura

originalSize- Posicionamento do carimbo com base no tamanho real da assinatura/carimbo

targetSize- Largura e altura personalizadas da área de assinatura/carimbo

Quando sizeRule, height e width estão todos vazios, o carimbo é posicionado com base no tamanho real da assinatura/carimbo;

Quando sizeRule está vazio, mas height e width não estão vazios, o carimbo é posicionado conforme as dimensões especificadas;

Quando sizeRule não está vazio, o carimbo é posicionado conforme o modo de exibição especificado;

O carimbo de página cruzada não requer a especificação deste parâmetro; ele é posicionado apenas com base no tamanho real.

height

int

false

Altura do controle de assinatura, aplicável quando fieldType é signature/stamp, em px. Suporta apenas números inteiros positivos. O padrão é auto (ou seja, tamanho automático do sistema);

Quando fieldType=signature, o intervalo configurável é de 20 a 250px;

Quando fieldType=stamp, o intervalo configurável é de 30 a 280px;

O carimbo de página cruzada não requer a especificação deste parâmetro.

width

int

false

Largura do controle de assinatura, aplicável quando fieldType é signature/stamp, em px. Suporta apenas números inteiros positivos. O padrão é auto (ou seja, tamanho automático do sistema);

Quando fieldType=signature, o intervalo configurável é de 20 a 250px;

Quando fieldType=stamp, o intervalo configurável é de 30 a 280px;

O selo de sobreposição não requer a especificação deste parâmetro.

signatureOptions

string

false

Opções do controle de assinatura. Aplicável apenas quando fieldType for signature.

Parâmetros de entrada possíveis:

template

handDrawn

upload

aiHandDrawn

Seleção múltipla permitida, separada por ","; padrão: selecionar todos

movable

boolean

false

Permite mover a posição durante a assinatura; padrão: false

false- Não permite que o signatário ajuste a posição dos seus controles de assinatura

true- Permite que o signatário ajuste a posição dos seus controles de assinatura

allowedOptions

array

false

Opções para aprovação pelo signatário, aplicáveis quando fieldType for approval. Padrão: ["approve", "decline"]

approve- Aprovar

decline- Recusar

pageNo

string

false

Número(s) da(s) página(s) da assinatura; páginas consecutivas são conectadas com "-", e páginas individuais com ","; por exemplo: 1-3, 6-10

Quando pagingSealMode=assignedPages, informe o intervalo de páginas onde o selo de sobreposição será aplicado. O selo de sobreposição só pode ser usado em documentos com mais de uma página.

posX

string

false

Coordenada no eixo X

Observações adicionais:

Se fieldType for signature, a posição das coordenadas refere-se à área de assinaturacanto inferior esquerdo；

Se fieldType for stamp, a posição das coordenadas refere-se à área do carimboponto centralposição

A partir de 3 de fevereiro de 2026, quando fieldType for signature ou stamp, a posição das coordenadas refere-se ao ponto central da área do carimbo.

Para o carimbo de sobreposição, pode-se transmitir 0, mas não null; o controle fica fixo na borda direita do documento.

posY

string

false

coordenada do eixo Y

Observações adicionais:

Se fieldType for signature, a posição das coordenadas refere-se à área de assinaturacanto inferior esquerdo；

Se fieldType for stamp, a posição das coordenadas refere-se à área do carimboponto centralposição

A partir de 3 de fevereiro de 2026, quando fieldType for signature ou stamp, a posição das coordenadas refere-se ao ponto central da área do carimbo.

fillConfigs

array

false

Preencha as informações do controle

fieldName

string

false

Nome do controle, limite de 128 caracteres

required

boolean

false

Obrigatório ou não, padrão é obrigatório

true-obrigatório

false-não obrigatório

fieldType

string

false

Tipo de controle:

1-texto de uma linha

15-caixa de seleção

textField

object

false

Propriedades do controle de texto

overflowType

int

false

Apenas válido para text, padrão 1

1-redução automática do tamanho da fonte

2-limitar entrada

minFontSize

float

false

Apenas válido para text, apenas válido quando overflowType=1, padrão 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

Largura do controle, padrão 160px

font

int

false

Apenas válido para text, fonte, padrão SimSun.

1-SimSun

2-Songti Novo

4-Heiti

5-Kaiti

6-Arial

7-Helvetica

9-Times New Roman

10-Fangsong

11-Georgia

12-Monospace

fontSize

float

false

Aplica-se apenas ao texto, tamanho da fonte, padrão 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

Aplica-se apenas ao texto, cor hexadecimal, padrão preto #000

bold

boolean

false

Aplica-se apenas ao texto, se a fonte está em negrito, padrão false

true-negrito

false-sem negrito

italic

boolean

false

Aplica-se apenas ao texto, se a fonte está em itálico, padrão false

true-itálico

false-sem itálico

underline

boolean

false

Aplica-se apenas ao texto, se a fonte tem sublinhado, padrão false

true-com sublinhado

false-sem sublinhado

lineThrough

boolean

false

Aplica-se apenas ao texto; indica se deve ser adicionado um risco, padrão false

true - adicionar risco

false - não adicionar risco

horizontalAlignment

string

false

Aplica-se apenas ao texto; formato de alinhamento horizontal, padrão left

LEFT - à esquerda

CENTER - centralizado

RIGHT - à direita

tickBoxField

object

false

Propriedades da caixa de seleção

tickOptions

array

false

Aplica-se apenas a Check; padrão 1

1 - marca de verificação

2 - X

posX

float

false

Coordenada X da posição do controle

posY

float

false

Coordenada Y da posição do controle

pageNo

string

false

Número da página onde o controle está localizado

signDateConfigs

array

false

Informações sobre a posição da data de assinatura

movable

boolean

false

Permitir mover a posição ao assinar, padrão false

false- Não permitir que o signatário ajuste a posição de seus controles de assinatura

true- Permitir que o signatário ajuste a posição de seus controles de assinatura

pageNo

string

false

Número da página de assinatura; páginas consecutivas são conectadas com "-", páginas individuais são conectadas com ",", por exemplo: 1-3, 6-10

Se não contínuo, use "," para separar

posX

float

false

Deslocamento no eixo x, a origem das coordenadas é o canto inferior esquerdo da página

posY

float

false

Deslocamento no eixo y, a origem das coordenadas é o canto inferior esquerdo da página

signDateFormat

string

false

Formato da data de assinatura, o formato padrão é yyyy-MM-dd

Suporta formatos especificados:

yyyy ano MM mês dd dia

yyyy-MM-dd

yyyy/MM/dd

dd.MM.yyyy

MM dd yyyy

dd MM yyyy