调用Zoho Sign创建文档API返回"Extra key found"错误的排查咨询

问题场景 #

使用Python requests库调用Zoho Sign文档创建接口时，遇到两个问题：

• 最初通过form-data传递嵌套在requests键里的参数，返回错误：

  {"code":9015,"error_param":"requests","message":"Extra key found","status":"failure"}
  

• 改用json=参数传递数据后错误消失，但所有业务参数都被接口忽略。

原代码：

import requests

requests.post('https://sign.zoho.com/api/v1/requests', {
    'requests': {
        'request_name': 'My Signing Request',
        'expiration_days': 18,
        'email_reminders': True,
        'reminder_period': 5,
        'notes': '',
        'is_sequential': True,
        'actions': ACTION_ARRAY,
    }
}, files={
    'file': FILE_IN_BYTES
})

解决方案 #

1. 移除多余的requests嵌套层级

Zoho Sign的该接口要求所有业务参数直接作为顶层字段传递，不需要嵌套在requests键中。之前的9015错误就是因为接口识别到了多余的requests键。

2. 修正后的正确代码

将原来嵌套的参数直接放到data参数中，同时保留files参数上传文件：

import requests

# 确保ACTION_ARRAY是符合接口要求的数组格式
payload = {
    'request_name': 'My Signing Request',
    'expiration_days': 18,
    'email_reminders': 'true',  # 若布尔值传递报错，可尝试字符串格式
    'reminder_period': 5,
    'notes': '',
    'is_sequential': 'true',
    'actions': ACTION_ARRAY,
}

# FILE_IN_BYTES可为字节流或open('你的文件路径', 'rb')获取的文件对象
response = requests.post(
    'https://sign.zoho.com/api/v1/requests',
    data=payload,
    files={'file': FILE_IN_BYTES}
)

print(response.json())

3. 为什么json=参数会导致参数被忽略？

当同时传递files和json参数时，requests会将JSON数据封装成form-data的一个名为json的字段，但Zoho Sign的接口不会读取这个字段，因此所有业务参数都被忽略。必须将业务参数放在data中，与文件一起组成标准的multipart/form-data请求。

4. 额外注意事项

• 确认ACTION_ARRAY的格式完全符合接口要求（比如每个元素需包含recipient_email、action_type等必填字段）。
• 若布尔类型参数传递后仍有问题，尝试转为字符串格式的'true'或'false'，部分接口对multipart/form-data中的布尔值格式有特殊要求。
• 确保FILE_IN_BYTES是有效的文件字节流或文件对象。

内容的提问来源于stack exchange，提问作者meesterguyperson