调用方式

接口基本信息:
  • 服务请求地址:https://saf.cn-shanghai.aliyuncs.com
  • 协议:HTTPS
  • 方式:POST
说明 为了便于进行开发,阿里云还提供Java、Python、PHP、C#、Golang语言的SDK开发包,可以免去拼接HTTPS请求和对签名算法进行编码的麻烦,参见调用方式

调用参数

请求参数
名称 类型 是否必需 描述
Format String 返回值的类型,支持JSONXML,默认为XML
Version String API版本号,为日期形式:YYYY-MM-DD,本版本对应为2017-03-31
AccessKeyId String 阿里云颁发给用户的访问服务所用的密钥ID,请参见 创建AccessKey
Signature String 签名结果串,关于签名的计算方法,请参见 签名机制
SignatureMethod String 签名方式,目前支持HMAC-SHA1
Timestamp String 请求的时间戳。日期格式按照ISO8601标准表示,并需要使用UTC时间。格式为:YYYY-MM-DDThh:mm:ssZ。

例如,2014-7-29T12:00:00Z(为北京时间2014年7月29日的20点0分0秒)。

SignatureVersion String 签名算法版本,目前版本是1.0
SignatureNonce String 唯一随机数,用于防止网络重放攻击。用户在不同请求间要使用不同的随机数值。
Action String 取值必须是ExecuteRequest
Service String 具体服务名,本服务该参数固定为fin_face_verify
ServiceParameters String 具体服务参数的json格式串,具体定义见下面各接口参数定义。
统一返回Code
说明 文档中的返回code做了合并处理,事实上各个环节都有明确的返回码解析,可以暴露出来便于结果查询,也可以统一封装成以上统一code。暂时按照统一封装code返回,减少用户接入成本。
Code Message 说明
200 OK 正确返回
401 参数非法 入参错误
402 应用配置不存在
403 主账号*******,无权调用该服务:fin_face_verify,或已到期、到量、未购买
404 认证场景配置不存在
405 以下两种原因之一:
  • 身份认证记录不存在;
  • 您的年龄未满14周岁,不允许使用此产品。
406 无效的certifyId
407 认证已失效
408 开放认证单据已失效
501 系统错误
502 系统繁忙
503 系统错误

发起认证请求

请求参数

发起认证请求时,其他参数参见调用参数,并在ServiceParameters的json字符串里传入以下字段:
名称 类型 是否必需 描述 示例值
method String 发起认证请求的操作。

取值必须是init

init
sceneId String 认证场景ID,在控制台创建认证场景后自动生成。 1000000006
outerOrderNo String 商户请求的唯一标识,值为32位长度的字母数字组合前面几位字符是商户自定义的简称,中间可以使用一段时间,后段可以使用一个随机或递增序列。 e0c34a77f5ac40a5aa5e6ed20c353888
bizCode String 认证场景码和用户发起认证的端有关:
  • 当用户在 iOS 或安卓平台发起认证时,认证场景码是 FACE_SDK
  • 当用户在小程序中发起认证时,认证场景码是 FACE
FACE_SDK
identityType String 身份信息参数类型,必须传入CERT_INFO。 CERT_INFO
certType String 证件类型,当前支持身份证,必须传入IDENTITY_CARD。 IDENTITY_CARD
certNo String 用户身份证件号。 330103xxxxxxxxxxxx
certName String 用户姓名。 张三
returnUrl String 商户业务页面回调的目标地址。如您不需要回调商户业务页面,您可以在此处传入空字符串。 https://www.aliyun.com
faceContrastPicture String 可选自定义人脸比对图片的base64编码格式的string字符串 /9j/4AAQSkZJRgABAQAAFAAUAAD...
响应参数
名称 类型 是否必需 描述 示例值
certifyId String 认证ID,刷脸认证唯一标识。 7eff3ad26a9c7b68c511b9f35eb1a354
certifyUrl String 认证流程入口URL。 https://picker.antcloudauth.aliyuncs.com/gateway.do?...
响应示例
{
    "code": 200,
    "requestId": "5CD69C04-8A6B-4CC3-A0C9-D18D5FEFA788",
    "data": {
        "certifyUrl": "https://picker.antcloudauth.aliyuncs.com/gateway.do?...",
        "certifyId": "7eff3ad26a9c7b68c511b9f35eb1a354"
    },
    "message": "OK"
}

查询认证结果

请求参数

查询认证结果时,其他参数参见调用参数,并在 ServiceParameters 的 json 字符串里传入以下字段:
名称 类型 是否必需 描述 示例值
method String 查询人脸比对结果的操作。

取值必须为query

query
certifyId String 认证ID,需与发起认证请求时返回的certifyId保持一致。 7eff3ad26a9c7b68c511b9f35eb1a354
sceneId String 认证场景ID,需与发起认证请求时的sceneId保持一致。 1000000006
响应参数
名称 类型 是否必需 描述 示例值
passed String 是否通过,通过为T,不通过为F。 T
identityInfo String 认证的主体信息,一般的认证场景返回为空。 "IdentityInfo": "{"cert_type":"IDENTITY_CARD","cert_no":"330103xxxxxxxxxxxx","cert_name":"张三"}"
materialInfo String 认证主体附件信息,主要为图片类材料,一般的认证场景都是返回空。 {"facial_picture_front":{ "FEATURE_FACE":"xydasf=="}}

完整代码示例(Java语言)

添加 Maven 依赖
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-saf</artifactId>
    <version>1.0.2</version>
</dependency>
Maven 推荐依赖仲裁
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-core</artifactId>
    <optional>true</optional>
    <version>4.1.1</version>
</dependency>

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>1.2.60</version>
</dependency>

<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.8.2</version>
</dependency>
调用接口
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
import com.alibaba.fastjson.JSON;
import com.aliyuncs.CommonRequest;
import com.aliyuncs.CommonResponse;
import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.exceptions.ServerException;
import com.aliyuncs.http.MethodType;
import com.aliyuncs.http.ProtocolType;
import com.aliyuncs.profile.DefaultProfile;

public class IntlFaceVerifyTest {
    public static void main(String[] args) throws IOException {
        DefaultProfile profile = DefaultProfile.getProfile("cn-shanghai", "<your-access-key-id>", "<your-access-key-secret>");
        IAcsClient client = new DefaultAcsClient(profile);

        CommonRequest request = new CommonRequest();
        request.setMethod(MethodType.POST);

        request.setDomain("saf.cn-shanghai.aliyuncs.com")
        request.setVersion("2017-03-31");
        request.setAction("ExecuteRequest");
        request.setProtocol(ProtocolType.HTTPS);

        // 业务详细参数
        Map<String, Object> serviceParams = new HashMap<String, Object>();

        // 发起认证请求
        serviceParams.put("method",  "init");
        serviceParams.put("sceneId",  "1000000006");
        serviceParams.put("outerOrderNo",  "e0c34a77f5ac40a5aa5e6ed20c353888");
        serviceParams.put("bizCode", "FACE");
        serviceParams.put("identityType", "CERT_INFO");
        serviceParams.put("certType", "IDENTITY_CARD");        
        serviceParams.put("certNo", "330103xxxxxxxxxxxx");
        serviceParams.put("certName", "张三");
        serviceParams.put("returnUrl", "https://www.aliyun.com");

        /*
        // 查询认证结果
        serviceParams.put("method",  "query");
        serviceParams.put("certifyId", "7eff3ad26a9c7b68c511b9f35eb1a354");
        serviceParams.put("sceneId", "1000000006");
        */

        request.putQueryParameter("ServiceParameters", JSON.toJSONString(serviceParams));
        // 固定值,Service = fin_face_verify
        request.putQueryParameter("Service", "fin_face_verify");

        try {
            CommonResponse response = client.getCommonResponse(request);
            System.out.println(response.getData());
        } catch (ServerException e) {
            e.printStackTrace();
        } catch (ClientException e) {
            e.printStackTrace();
        }
    }
}