手机号码三要素验证 API 集成指南

在现代应用开发中，验证用户的身份信息是一个重要的环节。本文将介绍如何集成手机号码三要素验证 API，以验证手机号码、姓名和身份证号码的真实性和一致性。这个 API 特别适用于需要用户身份验证的场景，比如金融服务、社交应用等。

环境准备

在开始之前，请确保你已具备以下条件：

注册并登录 Ace Data Cloud 账户。
申请使用手机号码三要素验证 API 服务。

申请使用 API

要使用手机号码三要素验证 API，首先需要在 Ace Data Cloud API 页面上申请相应的服务。进入页面后，点击"获取"按钮，如下图所示：

如果尚未登录或注册，你将自动重定向到登录页面。完成登录或注册后，你会返回到当前页面。首次申请时，将获得免费的配额，允许你免费使用 API。

基本用法

了解基本的使用方法后，你可以通过输入手机号码来获取处理结果。你需要传递一个 phone 字段。以下是相关的界面设置：

在请求头中，我们需要设置：

accept: 你希望接收的响应结果格式，填写为 application/json，表示 JSON 格式。
authorization: 调用 API 的密钥，申请后可以直接选择。

同时，设置请求体，包括：

name: 需要处理的用户姓名，必填。
phone: 需要处理的手机号码，必填。
id_card: 需要处理的身份证号码，必填。
verify_mode: 验证模式（长版/短版）。
encrypt_list/ciphertext_blob/iv: 可选的加密参数，用于加密敏感字段。

通过选择后，右侧会生成相应的代码，如下图所示：

点击"尝试"按钮进行测试，返回的结果如下：

json 复制代码

{
  "result": "0",
  "description": "认证通过",
  "isp": "移动",
  "result_detail": null
}

返回的结果包含多个字段，具体如下：

result: 认证结果代码，收费情况如下。
收费结果代码：
- 0: 验证结果一致
- 1: 验证结果不一致
非收费结果代码：
- -1: 未找到记录
- -2: 未知引擎错误
- -3: 引擎服务异常
- -4: 姓名验证失败
- -5: 手机号码无效
- -6: 认证尝试超过每日限制，请明天再试
description: 业务结果描述。

可以看到，手机号码、姓名和身份证号码的真实性和一致性信息已经查询到。

如果你想生成相应的集成代码，可以直接复制，例如 CURL 代码如下：

shell 复制代码

curl -X POST 'https://api.acedata.cloud/identity/phone/check-3e' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "name": "***",
  "phone": "***",
  "id_card": "***"
}'

Python 集成代码如下：

python 复制代码

import requests

url = "https://api.acedata.cloud/identity/phone/check-3e"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "name": "***",
    "phone": "***",
    "id_card": "***"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

错误处理

在调用 API 时，如果发生错误，API 将返回相应的错误代码和消息。例如：

400 token_mismatched: 错误请求，可能由于缺失或无效的参数。
401 invalid_token: 未授权，令牌无效或缺失。
429 too_many_requests: 请求过多，已超过速率限制。
500 api_error: 内部服务器错误，服务器出现问题。

错误响应示例

json 复制代码

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

总结

通过本文，你学习了如何使用手机号码三要素验证 API 验证手机号码、姓名和身份证号码的真实性和一致性。这将帮助你更好地集成和使用该 API。如果你有任何问题，请随时联系技术支持团队。

技术标签

API集成
身份验证
Python开发
数据安全
Ace Data Cloud