本文档旨在解决在使用 DocuSign REST API 传递包含非拉丁 UTF-8 字符的 HTML 文档时，字符显示不正确的问题。通过正确设置请求头和确保 HTML 内容的 UTF-8 编码，可以避免字符乱码，使生成的 DocuSign 信封文档正确显示多字节字符。
在使用 DocuSign API 创建信封时，如果 HTML 文档中包含非拉丁字符（例如俄语、中文等），可能会遇到字符显示异常的问题。这通常是由于编码设置不正确导致的。以下是一些关键步骤，以确保 DocuSign 正确处理 HTML 中的 UTF-8 字符。
1. 确保 HTML 文档本身是 UTF-8 编码
首先，需要确认你的 HTML 文档本身保存为 UTF-8 编码。大多数文本编辑器都允许你选择文件的编码方式。如果你的 HTML 文件不是 UTF-8 编码，请将其转换为 UTF-8。
立即学习“前端免费学习笔记（深入）”；
2. 设置正确的 Content-Type 请求头
在将 HTML 文档作为信封创建请求的一部分发送到 DocuSign API 时，需要确保 Content-Type 请求头正确设置。 对于 HTML 部分，请求头应明确指定 charset=utf-8。
Content-Type: text/html;charset=utf-8 Content-Disposition: form-data; filename="foo.html"; name="foo.html"; documentid="1"
同时，整个 multipart 请求的 Content-Type 也需要正确设置：
Content-Type: multipart/form-data; boundary=Boundary_4_1344004434_1669225218640
3. 检查 API 请求日志
DocuSign 提供了服务器端 API 请求日志功能，可以用来验证发送到 DocuSign 的数据是否正确。启用此功能后，你可以查看请求日志，确认 HTML 内容是否以正确的 UTF-8 编码发送。如果在日志中看到字符正确显示，则问题可能出在 DocuSign 的 HTML 到 PDF 转换过程中。
4. 代码示例 (假设使用 Python 和 requests 库)
以下是一个使用 Python 的 requests 库发送包含 UTF-8 字符的 HTML 文档到 DocuSign API 的示例：
import requests
# DocuSign API endpoint 和 authentication 信息 (请替换为你的实际信息)
api_endpoint = "https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes"
access_token = "YOUR_ACCESS_TOKEN"
account_id = "YOUR_ACCOUNT_ID"
# HTML 文档内容 (包含 UTF-8 字符)
html_content = """
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>测试文档</title>
</head>
<body>
<h1>你好，世界！ (Hello, World!)</h1>
<p>这是一个包含中文和英文的测试文档。</p>
<p>俄语示例: банан</p>
</body>
</html>
"""
# 构建 multipart/form-data 请求
files = {
'foo.html': ('foo.html', html_content, 'text/html; charset=utf-8')
}
headers = {
'Authorization': f'Bearer {access_token}',
'Accept': 'application/json'
}
data = {
'envelopeDefinition': '{"emailSubject": "测试信封", "status": "sent", "documents": [{"documentId": "1", "name": "foo.html", "fileExtension": "html"}]}'
}
try:
response = requests.post(api_endpoint.format(accountId=account_id),
headers=headers,
files=files,
data=data)
response.raise_for_status() # 抛出 HTTPError，如果响应状态码不是 200
print(f"信封创建成功！响应：{response.json()}")
except requests.exceptions.RequestException as e:
print(f"请求失败: {e}")
if response is not None:
print(f"响应内容：{response.text}")
注意事项:
- 请确保替换代码中的 YOUR_ACCESS_TOKEN 和 YOUR_ACCOUNT_ID 为你实际的 DocuSign API 访问令牌和账户 ID。
- envelopeDefinition 包含了信封的基本信息，例如邮件主题、状态和文档信息。 根据你的需要进行调整。
- files 字典包含了要上传的 HTML 文件。 关键在于设置正确的 Content-Type 为 text/html; charset=utf-8。
- 捕获 requests.exceptions.RequestException 异常，以便处理请求失败的情况。 打印响应内容有助于调试问题。
5. 其他建议
- 如果问题仍然存在，尝试将 HTML 实体编码用于特殊字符。 例如，将 & 编码为 &，将 < 编码为 。 虽然原问题提到不想这么做，但作为最后的手段，可以尝试对部分字符进行编码。
- 联系 DocuSign 支持，提供详细的请求信息和问题描述，以便他们帮助你诊断问题。
总结
正确处理 DocuSign API 中的 UTF-8 字符需要确保 HTML 文档本身是 UTF-8 编码，并且在 API 请求中正确设置 Content-Type 请求头。 通过检查 API 请求日志，可以验证发送到 DocuSign 的数据是否正确。 如果问题仍然存在，可以尝试 HTML 实体编码或联系 DocuSign 支持。通过遵循这些步骤，你应该能够解决在使用 DocuSign API 时遇到的 UTF-8 字符显示问题。
