Iniciar envelope rapidamente

POST /esignglobal/v1/envelope/createAndStart

Descrição da interface

Início rápido do envelope, incluindo criação de envelope, adição de documentos pendentes de assinatura e adição de signatários.

Suporta ativação automática: Após o sucesso da chamada da interface, o envelope é criado e ativado com sucesso, iniciando automaticamente o fluxo.
Suporta encerramento automático: Após todos os signatários concluírem a assinatura, o envelope é encerrado automaticamente.

Parâmetros de solicitação

Nome do parâmetro					Tipo	Obrigatório	Descrição
subject					string	true	Título do envelope Exemplo: "Carta de Oferta"
remark					string	false	Observações do envelope, limite de 1000 caracteres
signerSettings					object	false	Operações permitidas para o signatário
	allowTransfer				boolean	false	Se é permitido ao signatário transferir este envelope para outra pessoa assinar, padrão false true - permite que o signatário no envelope tenha o poder de transferir o envelope a terceiros; false - não permite que o signatário no envelope tenha o poder de transferir o envelope a terceiros;
	allowModifyName				boolean	false	Se é permitido à parte signatária modificar o nome, válido apenas para assinaturas em modelo, padrão false true - permite que o signatário modifique o nome false - não permite que o signatário modifique o nome
expireAfterSeconds					long	false	Tempo de expiração do envelope; após quantos segundos o envelope expira Intervalo de expiração: 86.400 segundos (1 dia) ~ 7.776.000 segundos (90 dias)
redirectUrl					string	false	Deve ser um endereço https válido
callBackUrl					string	false	Endereço de retorno (comprimento 500), deve estar em conformidade com o protocolo https.
sendLaterAfterSeconds					long	false	Suporta atraso no envio pelo usuário, em segundos Intervalo de tempo suportado: 3.600 segundos (1 hora) ~ 259.200 segundos (30 dias)
autoFinish					boolean	false	Controla se o envelope termina automaticamente, padrão true true- Encerramento automático do envelope false- Encerramento manual do envelope
CCInfos					array	false	Conjunto de informações dos destinatários em cópia
	userEmail				string	false	Endereço de e-mail do destinatário em cópia
	userName				string	false	Nome do destinatário em cópia, usado para exibir o nome do destinatário em cópia na página de assinatura e no envelope. [Atenção]: Não deve conter os seguintes 9 caracteres especiais: / \ : * " < > \| ? e todos os emojis
	customizeSettings				object	false	Configuração personalizada
		notificationSettings			object	false	Configurações personalizadas para notificações
			notificationLanguage		string	false	Idioma da notificação; por 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
signFiles					array	true	Conjunto de informações dos documentos assinados, exibidos na ordem em que foram adicionados.
	fileKey				string	true	fileKey do documento assinado; apenas o formato PDF é suportado
	documentFields				array	false	Lista de controles dimensionais do documento. Utilizada para adicionar controles dimensionais do documento não vinculados a signatários em um documento especificado.
		fieldType			string	false	Tipo de controle. Transmita eMeterai para indicar o controle de imposto de carimbo da Indonésia.
		pageNo			string	false	Número da página onde o controle está localizado. O controle de imposto de carimbo da Indonésia suporta apenas uma única página específica; deve ser transmitido um único número de página, não sendo suportados formatos de múltiplas páginas contínuas ou não contínuas como 1-3 ou 1,3.
		posX			float	false	Deslocamento no eixo x, com a origem das coordenadas no canto inferior esquerdo da página. A faixa de coordenadas é consistente com a faixa de coordenadas de outros controles.
		posY			float	false	Deslocamento no eixo y, com a origem das coordenadas no canto inferior esquerdo da página. A faixa de coordenadas é consistente com a faixa de coordenadas de outros controles.
attachments					array	false	Conjunto de anexos do envelope, a ordem de exibição segue a ordem de adição dos arquivos.
	fileKey				string	false	fileKey do arquivo
signerInfos					array	true	Conjunto de informações do signatário
	businessId				string	false	Número de negócio personalizado pelo desenvolvedor, limite de comprimento: 500 caracteres
	roleTypes				array	false	Método de operação do signatário, valor padrão: `["sign", "fill"]` fill-preencher sign-assinar
	deliveryMethods				string	false	Método de notificação, padrão: auto auto- Ao informar userEmail, envia notificação por e-mail; ao informar phoneNumber, envia notificação por SMS none- Não envia notificação por mensagem email- Envia notificação por e-mail sms- Envia notificação por SMS WhatsApp- Envia notificação via WhatsApp
	userEmail				string	false	Endereço de e-mail do signatário
	userName				string	true	Nome do signatário, utilizado na página de assinatura e na exibição externa do envelope para mostrar o nome do signatário. [Nota] Não deve conter os seguintes 9 caracteres especiais: / \ : * " < > \| ? e todos os emojis
	minimumReadingDuration				int	false	Define o tempo de contagem regressiva obrigatório para leitura na página de configuração. O valor padrão é 0 (unidade: segundos, valor máximo: 999) 0 ou não informar indica que a função está desativada; não há contagem regressiva de leitura
	readToEndRequired				boolean	false	Indica se é necessário ler até o final. Valor padrão: false; true indica que está ativado; false ou não informar indica que está desativado.
	phoneNumber				object	false	Número de telefone, vazio por padrão Parâmetro obrigatório quando for necessária uma notificação por SMS; tanto countryCode quanto number devem ser fornecidos
		countryCode			string	false	Código internacional do país/região, sem necessidade de incluir o “+”
		number			string	false	Sem validação de formato, apenas limite de comprimento máximo de 13 dígitos
	customizeSettings				object	false	Configuração personalizada
		notificationSettings			object	false	Configurações personalizadas para notificações
			customizeMessage		string	false	Notificação exclusiva de mensagens, limite de caracteres: 200
			notificationLanguage		string	false	Idioma da notificação; por padrão, usa 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
	signOrder				int	true	Ordem de assinatura do signatário, com valor mínimo de 1. Assinaturas sem ordem podem ter o mesmo valor de ordem.
	anySigner				boolean	false	Se suporta a assinatura por qualquer pessoa, padrão false true- Para um mesmo signOrder, apenas uma das pessoas precisa assinar false- Para um mesmo signOrder, todas as pessoas precisam assinar
	authModes				string	false	Método de validação, padrão noAuth noAuth- Sem validação accessCode- Validação usando senha de assinatura sms- Validação OTP via SMS idVerification- Validação por documento de identidade emailAuth- Validação OTP por e-mail digitalId- Validação de identidade eletrônica whatsappAuth- Validação OTP via WhatsApp
	authConfig				object	false	Configuração do método de validação
		accessCode			object	false	Configuração da senha de assinatura, 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, limite de comprimento: 45
			promptInfo		string	false	Mensagem de dica da senha de acesso, não pode conter a senha de acesso, limite de comprimento 30, obrigatório quando authModes=accessCode
		sms			object	false	Verificação OTP SMS, obrigatório quando authModes=sms
			countryCode		string	false	Código internacional do país/região, sem necessidade de incluir o sinal “+”
			number		string	false	Sem validação de formato, apenas limitação de comprimento máximo de 13 caracteres
		idVerification			object	false	Configuração de verificação de documento de identidade, obrigatório quando authModes=idVerification
			name		string	false	Nome completo no documento de identidade do signatário, comprimento máximo de 100 caracteres
		emailAuth			object	false	Verificação OTP por e-mail, obrigatório quando authModes=emailAuth
			authEmail		string	false	Endereço de e-mail para verificação de 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-Autenticação de identidade usando i AM Smart
			idNumber		string	false	Número do documento de identificação do signatário pendente de validação 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; 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 do WhatsApp, obrigatório quando authModes=whatsappAuth
			countryCode		string	false	Código internacional do país/região, sem incluir o “+”
			number		string	false	Sem validação de formato, apenas limite máximo de comprimento de 13 caracteres
	digitalSignature				boolean	false	Se a assinatura digital está ativada, padrão false true - ativado, false - desativado
	freeFormSign				boolean	false	Se o signatário pode assinar livremente, valor padrão false Informações adicionais: Quando freeFormSign estiver definido como true, não é necessário transmitir outros parâmetros sob sealInfos. Se ambos forem transmitidos simultaneamente, freeFormSign terá prioridade sobre sealInfos, e os parâmetros em sealInfos não serão aplicados. [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; o valor padrão é signature signature- Controle de assinatura stamp- Controle de carimbo approval- Controle de aprovação
			required		boolean	false	Se é um campo obrigatório; o valor padrão é obrigatório true- Obrigatório false- Não obrigatório
			signFieldStyle		string	false	Método de aplicação do carimbo no controle de assinatura; o valor padrão é normalSeal. normalSeal-Carimbo simples pagingSeal-Carimbo de sobreposição Apenas os controles de assinatura e carimbo suportam a configuração do carimbo de sobreposição.
			pagingSealMode		string	false	Faixa de páginas para aplicação do carimbo de sobreposiçã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-Aplicar carimbo com base nas dimensões reais da assinatura/carimbo targetSize-Largura e altura personalizadas da área de assinatura/carimbo Quando sizeRule, height e width estão todos vazios, aplica o carimbo conforme as dimensões reais da assinatura/carimbo; Quando sizeRule está vazio, mas height e width não estão vazios, aplica o carimbo conforme as dimensões especificadas; Quando sizeRule não está vazio, aplica o carimbo conforme o modo de exibição especificado; O carimbo de sobreposição não requer a especificação deste parâmetro; o carimho será aplicado com base nas dimensões reais.
			height		int	false	Altura do controle de assinatura, aplicável quando fieldType é signature/stamp, em pixels (px). Suporta apenas números inteiros positivos. O padrão é auto (dimensão automática pelo sistema); Quando fieldType=signature, o intervalo configurável é de 20 a 250 px; Quando fieldType=stamp, o intervalo configurável é de 30 a 280 px; O carimbo de sobreposição não requer a especificação deste parâmetro.
			width		int	false	Largura do controle de assinatura, aplicável quando fieldType é signature/stamp, em pixels (px). Suporta apenas números inteiros positivos. O padrão é auto (dimensão automática pelo sistema); Quando fieldType=signature, o intervalo configurável é de 20 a 250 px; Quando fieldType=stamp, o intervalo configurável é de 30 a 280 px; O carimbo 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 é signature Parâmetros de entrada disponíveis: template: assinatura por modelo handDrawn: assinatura desenhada à mão upload: upload de imagem de assinatura local Pode selecionar múltiplas opções, separadas por ",". A seleção padrão é todas as opções.
			movable		boolean	false	Permite mover a posição ao assinar, padrão false false - Não permite que o signatário ajuste a posição de seus controles de assinatura true - Permite que o signatário ajuste a posição de seus controles de assinatura
			allowedOptions		array	false	Opções que permitem ao signatário aprovar, aplicável quando fieldType for approval. Padrão: ["approve", "decline"] approve- Aprovar decline- Recusar
			pageNo		string	false	Números das páginas de assinatura; páginas consecutivas são conectadas com "-" e páginas individuais com "," Exemplo: 1-3,6-10 Ao usar pagingSealMode=assignedPages, informe o intervalo de páginas para aplicação do selo de página contínua. O selo de página contínua só pode ser usado em documentos com mais de uma página.
			posX		float	false	Coordenada do eixo X [Atenção] Se fieldType for signature, a posição da coordenada refere-se à área de assinaturaCanto inferior esquerdo； Se fieldType for stamp, a posição da coordenada refere-se à área de 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. O carimbo de sobreposição pode ser transmitido como 0, mas não como null; o controle está fixado na borda direita do documento.
			posY		float	false	Coordenada do eixo Y [Atenção] 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	Preencher informações do controle
			fieldName		string	false	Nome do controle, limite de caracteres: 128
			required		boolean	false	Campo obrigatório? 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	Aplica-se apenas ao text, padrão 1 1-Ajustar automaticamente o tamanho da fonte 2-Limitar entrada
				minFontSize	float	false	Aplica-se apenas ao text, aplica-se apenas 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	Aplica-se apenas ao text, fonte, padrão SimSun 1-SimSun 2-Novos SimSun 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 text, 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	Apenas afeta o texto, cor hexadecimal, padrão preto #000
				bold	boolean	false	Apenas afeta o texto, se a fonte está em negrito, padrão false true - negrito false - sem negrito
				italic	boolean	false	Apenas afeta o texto, se a fonte está em itálico, padrão false true - itálico false - não itálico
				underline	boolean	false	Apenas afeta o texto, se a fonte tem sublinhado, padrão false true - com sublinhado false - sem sublinhado
				lineThrough	boolean	false	Apenas afeta o texto, se a fonte tem riscado, padrão false true - com riscado false - sem riscado
				horizontalAlignment	string	false	Apenas afeta o texto, alinhamento horizontal centralizado, padrão left LEFT - à esquerda CENTER-Centralizado RIGHT-Alinhado à direita
			tickBoxField		object	false	Propriedades da caixa de seleção
				tickOptions	array	false	Aplica-se apenas ao tickBox, padrão 1 1-Marcado 2-Cruzado
			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	Permite mover a posição durante a assinatura, padrão false false-O signatário não pode ajustar a posição dos seus controles de assinatura true-O signatário pode ajustar a posição dos seus controles de assinatura
			pageNo		string	false	Número(s) da(s) página(s) de assinatura; páginas consecutivas são conectadas com "-", páginas individuais com ",". Exemplo: 1-3, 6-10; Para páginas não consecutivas, use "," para separar.
			posX		float	false	Deslocamento no eixo x, com a origem das coordenadas no canto inferior esquerdo da página
			posY		float	false	Deslocamento no eixo y, com a origem das coordenadas no canto inferior esquerdo da página
			signDateFormat		string	false	Formato da data de assinatura; o formato padrão é yyyy-MM-dd Suporta os seguintes formatos: dd de MM de yyyy yyyy-MM-dd yyyy/MM/dd dd.MM.yyyy MMM dd,yyyy dd MMM yyyy

Exemplo de solicitação

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

Nome do parâmetro		Tipo	Descrição
envelopeId		string	ID do envelope
CCInfos		array	Conjunto de informações dos destinatários em cópia
	userEmail	string	Endereço de e-mail do destinatário em cópia
	userName	string	Nome do destinatário em cópia
signFiles		array	Conjunto de informações dos documentos assinados
	fileKey	string	Chave do arquivo a ser assinado
attachments		array	Conjunto de anexos do envelope
	fileKey	string	Chave do arquivo
signerInfos		array	Informações de assinatura
	recipientId	string	ID do signatário
	businessId	string	Número de negócio personalizado pelo desenvolvedor, limite de comprimento 500
	userEmail	string	Endereço de e-mail do signatário
	userName	string	Nome do signatário
	signUrl	string	URL do link de assinatura
	signOrder	int	Ordem de assinatura do signatário, mínimo 1
	accessCode	string	Senha de acesso à página de assinatura

Exemplo de resposta

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