API Documentation

Unduh

Mode fokus

Ukuran font

Terakhir diperbarui: 2026-07-03 18:20:12

Note:
This chapter introduces the invocation methods, authentication processes, and core business APIs of commonly used interfaces for developers and Ops personnel who need to integrate Tencent eSign capabilities into their own systems. For the complete set of interfaces, refer to the official documentation.
Basic Conventions Before Access
Before calling any API, please first understand the following unified rules.
Item
Description
API prefix
/openapi/v1
Transport protocol
HTTPS only (HTTP not supported).
Response format
JSON(Content-Type: application/json)
Character encoding
UTF-8
Time format.
RFC3339 / ISO 8601, supporting time zone offset, for example, 2024-01-15T18:30:00+08:00.
Environment Domain Name
Environment
Domain Name
Purpose
Test Environment
https://api.test.sign.tencent.com
Development and Integration Testing
Production Environment (Singapore Node)
https://sgapi.tencent-esign.com
Formal Production
Note:
Complete request URL = Environment domain + API prefix + Specific path, for example: https://sgapi.tencent-esign.com/openapi/v1/envelopes/quick-create.
Common request header
Header
Required
Description
Authorization
Yes (for business interfaces)
Fixed format: Bearer <access_token>
Content-Type
Yes
For business interfaces, use application/json; for OAuth interfaces, use application/x-www-form-urlencoded.
X-Operator-User-Id
No
Specifies the execution identity for this call. If the execution identity is not passed, the system user associated with the application is used. When an envelope is initiated, a real user ID must be passed, and this user is the envelope sender.
SpaceId Description
An application (AppId) can be installed in one or more spaces (Space). When obtaining a token, specify the target space using the space_id. The issued access_token is valid only for that specific space. Subsequent business APIs are executed within that space, and you do not need to pass the SpaceId again.
Authentication API (OAuth 2.0)
Tencent eSign adopts the OAuth 2.0 Client Credentials mode. A valid access_token must be included in all business API calls.
Obtaining a Token (Token Issue)
Project
Content
Request URL
POST /openapi/v1/oauth/token
Content-Type
application/x-www-form-urlencoded
Request Parameters:
Parameter
Type
Required
Description
grant_type
string
Yes
Fixed value: client_credentials
client_id
string
Yes
Application client ID
client_secret
string
Yes
Application client secret
space_id
string
Yes
Space ID
scope
string
Yes
Scope, separate multiple scopes with spaces
Request Example:
POST https://sgapi.tencent-esign.com/openapi/v1/oauth/token
Content-Type: application/x-www-form-urlencoded
﻿
grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&space_id=YOUR_SPACE_ID&scope=envelope:create envelope:read
Key Return Fields:
Field
Description
access_token
Access token, valid for 1 hour
Best Practices:
The client_secret must be securely stored and must not be exposed in frontend code or public repositories. It is recommended to store it using environment variables or a key management service.
Cache the token and renew it approximately 60 seconds before it expires to avoid frequent requests to the token endpoint.
Revoking a Token (Token Revoke)
Project
Content
Request URL
POST /openapi/v1/oauth/revoke
Content-Type
application/x-www-form-urlencoded
Request Parameters:
Parameter
Type
Required
Description
token
string
Yes
The access token to be revoked
client_id
string
Yes
Application client ID
client_secret
string
Yes
Application client secret
Note:
When a token is no longer in use, you can proactively revoke it to invalidate it immediately.
Common Permission Scopes
Scope
Description
envelope:create
Create and send a envelope.
envelope:read
Retrieve envelope status and details.
Core Business API (Envelope Signing)
The following APIs all use the POST method and require the Authorization: Bearer <access_token> Header. A complete signing process typically follows the sequence: upload file → initiate envelope → obtain signing link → query result.
Uploading Files
Upload the file to be signed to the platform to obtain the FileId required for initiating the envelope later.
Project
Content
Request URL
POST /openapi/v1/files/upload
Key Request Parameters:
Parameter
Description
Files
List of files (array)
Files[].FileName
File Name
Files[].FileBody
Base64-encoded file content
Key Return Fields:
Field
Description
FileId
The file ID, valid for 24 hours, must be used to initiate a envelope as soon as possible.
Initiating an Envelope Quickly
The API that creates a envelope and immediately enters the signing process in one step is the most commonly used initiation interface.
Project
Content
Request URL
POST /openapi/v1/envelopes/quick-create
Required Headers
Authorization and X-Operator-User-Id (real user ID of the sender)
Key Request Parameters:
Parameter
Description
BasicInfo
Basic information, including EnvelopeTitle (envelope title) and SigningOrderType (signing order type)
Documents
List of documents, including DocumentId, FileId, and Order
Signers
List of signers, including RecipientId, Name, and Email
Tabs
Signing locations, including TabType, RecipientId, DocumentId, and Position
Key Return Fields:
Field
Description
EnvelopeId
Envelope ID. The envelope goes to the signing process immediately after creation.
Querying Envelope Details
Query the current status and signing progress of the envelope.
Project
Content
Request URL
POST /openapi/v1/envelopes/detail
Key Request Parameters:
Parameter
Description
EnvelopeId
Envelope ID
Note:
Returns detailed information such as the envelope status and signer progress.
Obtaining a Signing Link
Generate a signing page link for the specified signer, which can be sent to the signer to complete the signing.
Project
Content
Request URL
POST /openapi/v1/envelopes/signing-view
Key Request Parameters:
Parameter
Description
EnvelopeId
Envelope ID
RecipientId
Signer ID
Key Return Fields:
Field
Description
SignerInfos
List of signer information
SigningUrl
Signing URL, used for sending to the signer
Typical Call Flow
The following outlines the standard process for an electronic signature from initiation to completion, facilitating a quick understanding of how the above APIs connect.
Step
Operation
Method and API
Key Output
1
Obtain a token.
POST /openapi/v1/oauth/token
access_token
2
Upload files.
POST /openapi/v1/files/upload
FileId
3
Initiate an envelope
POST /openapi/v1/envelopes/quick-create
EnvelopeId
4
Obtain a signing URL.
POST /openapi/v1/envelopes/signing-view
SigningUrl
5
Distribute to the signer for completion.
-
-
6
Query the Result
POST /openapi/v1/envelopes/detail
Signing Status
Status Retrieval Recommendations:
To reduce system load and improve real-time performance, we recommend configuring callback notifications to receive signing completion events instead of frequently polling the query API.
Error Handling and Precautions
HTTPS Enforcement: All APIs support HTTPS only. HTTP requests will be rejected.
Token Endpoint Error Responses conform to the standard format specified in RFC 6749 §5.2.
Token validity period: 1 hour. Please implement caching and refresh mechanisms accordingly. FileId validity period: 24 hours.
Environment Isolation: Different domains are used for testing and production. When switching to production, you must update the domain and credentials.
Key Security: Sensitive information such as client_secret and access_token must not be exposed in the frontend or public code repositories.
Note:
The above is a summary of commonly used APIs. Fields and APIs may be adjusted during official iterations. Before making API calls, please refer to the official documentation.
﻿

Bantuan dan Dukungan

Apakah halaman ini membantu?

Anda juga dapat Menghubungi Penjualan atau Mengirimkan Tiket untuk meminta bantuan.

masukan

Parameter	Description
`BasicInfo`	Basic information, including `EnvelopeTitle` (envelope title) and `SigningOrderType` (signing order type)
`Documents`	List of documents, including `DocumentId`, `FileId`, and `Order`
`Signers`	List of signers, including `RecipientId`, `Name`, and `Email`
`Tabs`	Signing locations, including `TabType`, `RecipientId`, `DocumentId`, and `Position`

Item	Description
API prefix	`/openapi/v1`
Transport protocol	HTTPS only (HTTP not supported).
Response format	JSON(`Content-Type: application/json`)
Character encoding	UTF-8
Time format.	RFC3339 / ISO 8601, supporting time zone offset, for example, `2024-01-15T18:30:00+08:00`.

Environment	Domain Name	Purpose
Test Environment	`https://api.test.sign.tencent.com`	Development and Integration Testing
Production Environment (Singapore Node)	`https://sgapi.tencent-esign.com`	Formal Production

Header	Required	Description
`Authorization`	Yes (for business interfaces)	Fixed format: `Bearer <access_token>`
`Content-Type`	Yes	For business interfaces, use `application/json`; for OAuth interfaces, use `application/x-www-form-urlencoded`.
`X-Operator-User-Id`	No	Specifies the execution identity for this call. If the execution identity is not passed, the system user associated with the application is used. When an envelope is initiated, a real user ID must be passed, and this user is the envelope sender.

Project	Content
Request URL	`POST /openapi/v1/oauth/token`
Content-Type	`application/x-www-form-urlencoded`

Parameter	Type	Required	Description
`grant_type`	string	Yes	Fixed value: `client_credentials`
`client_id`	string	Yes	Application client ID
`client_secret`	string	Yes	Application client secret
`space_id`	string	Yes	Space ID
`scope`	string	Yes	Scope, separate multiple scopes with spaces

Field	Description
`access_token`	Access token, valid for 1 hour

Scope	Description
`envelope:create`	Create and send a envelope.
`envelope:read`	Retrieve envelope status and details.

Parameter	Description
`Files`	List of files (array)
`Files[].FileName`	File Name
`Files[].FileBody`	Base64-encoded file content

Field	Description
`FileId`	The file ID, valid for 24 hours, must be used to initiate a envelope as soon as possible.

Field	Description
`EnvelopeId`	Envelope ID. The envelope goes to the signing process immediately after creation.

Field	Description
`SignerInfos`	List of signer information
`SigningUrl`	Signing URL, used for sending to the signer

Step	Operation	Method and API	Key Output
1	Obtain a token.	POST /openapi/v1/oauth/token	access_token
2	Upload files.	POST /openapi/v1/files/upload	FileId
3	Initiate an envelope	POST /openapi/v1/envelopes/quick-create	EnvelopeId
4	Obtain a signing URL.	POST /openapi/v1/envelopes/signing-view	SigningUrl
5	Distribute to the signer for completion.	-	-
6	Query the Result	POST /openapi/v1/envelopes/detail	Signing Status

tencent cloud

Tencent eSign

API Documentation

Basic Conventions Before Access

Environment Domain Name

Common request header

SpaceId Description

Authentication API (OAuth 2.0)

Obtaining a Token (Token Issue)

Revoking a Token (Token Revoke)

Common Permission Scopes

Core Business API (Envelope Signing)

Uploading Files

Initiating an Envelope Quickly

Querying Envelope Details

Obtaining a Signing Link

Typical Call Flow

Error Handling and Precautions

Bantuan dan Dukungan