身份信息及有效期核验 API 对接说明
内容提要
本文介绍身份信息及有效期核验API的对接方法。用户需在Ace Data Cloud获取API Token，通过传入姓名、身份证号、有效期起止等字段，校验信息真实性与一致性。返回结果码0表示一致，-1表示不一致，其他代码表示非法输入或系统错误。文章提供CURL和Python示例代码及错误处理说明。
延伸解读
返回码区分收费与不收费
该API的返回码设计值得注意：结果码0和-1为收费结果码，分别表示姓名和身份证号一致或不一致；而-2至-7等异常情况（如非法身份证号、证件库无记录、系统升级等）为不收费结果码。这意味着只有成功完成比对才会产生费用，调用方在计费时需区分处理，避免对异常情况误计费。
有效期字段的格式要求
调用时需传入身份证有效期起止时间，格式为YYYYMMDD，长期有效需用“00000000”代替结束日期。开发者需确保日期格式正确，否则可能返回非法参数错误。此外，该API还支持可选的敏感字段加密参数，若需上送密文可启用encryption字段，但文档未详述加密方式，实际使用前需进一步确认。
错误处理与限流提示
文档列出了常见HTTP错误码，如401表示token无效，429表示请求超限。特别地，返回码-7表示当日认证次数超限，提示该API可能有每日调用配额。开发者应在代码中处理这些错误场景，并注意token的权限管理，因为一个token可调用平台所有服务，需妥善保管以防滥用。
Q&A
如何获取身份信息及有效期核验 API 的调用凭证？
需要先到 Ace Data Cloud 控制台注册或登录，然后获取 API Token。一个 Token 即可调用平台所有服务，首次申请会赠送免费额度。
身份信息及有效期核验 API 需要传入哪些参数？
需要传入姓名（name）、身份证号（id_card）、身份证有效期开始时间（validity_begin）和结束时间（validity_end），格式为 YYYYMMDD，长期有效用 00000000 代替。可选参数包括人脸图片链接（image_url）和敏感字段加密参数（encryption）。
身份信息及有效期核验 API 返回结果码 0 和 -1 分别代表什么？
返回结果码 0 表示姓名和身份证号一致，-1 表示不一致。这两个结果码是收费的。
身份信息及有效期核验 API 有哪些不收费的结果码？
不收费的结果码包括：-2 非法身份证号、-3 非法姓名、-4 证件库服务异常、-5 证件库中无此身份证记录、-6 权威比对系统升级中、-7 认证次数超过当日限制。
如何用 Python 调用身份信息及有效期核验 API？
使用 requests 库发送 POST 请求到 https://api.acedata.cloud/identity/idcard/check-2e，在 headers 中设置 accept 为 application/json、authorization 为 Bearer {token}、content-type 为 application/json，在 payload 中传入 name、id_card、validity_begin、validity_end 等字段，然后打印响应文本。
调用身份信息及有效期核验 API 时遇到 401 错误怎么办？
401 错误表示 invalid_token，即授权 token 无效或缺失。需要检查 authorization 请求头是否正确，确保使用了有效的 API Token。
