SDK调用接入

重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

当您使用SDK进行开发时,无需拼接HTTPS请求或实现签名算法,开发更方便。因此建议您通过SDK方式在服务端集成金融级实人认证。本文为您介绍金融级实人认证服务端需要集成的接口,以及多语言(Java、Python、PHP、C#、Golang、Node.js)的SDK调用示例。

调用说明

  • 全局接入地址:saf.cn-shanghai.aliyuncs.com

  • 请求方法:POST

  • 传输协议:HTTPS

  • QPS限量:API独享QPS限量,详情请参见服务端接口QPS限量说明

发起认证请求

请求参数

method字段传入init值表示调用发起认证请求接口

发起认证请求时,传入以下参数:

名称

类型

是否必选

描述

示例值

method

String

发起认证请求的操作。

取值:init

init

sceneId

String

认证场景ID,该ID在控制台创建认证场景后自动生成。关于如何创建认证场景,请参见添加认证场景

10000*****

outerOrderNo

String

客户服务端自定义的业务唯一标识,用于后续定位排查问题时使用。值最长为32位长度的字母和数字组合,请确保唯一。

e0c34a77f5ac40a5aa5e6ed20c********

bizCode

String

认证场景码和商户发起认证的接入端有关:

  • 当商户在iOS或安卓平台发起认证时,认证场景码为FACE_SDK

  • 当商户在小程序中H5页面中发起认证时,认证场景码为FACE

FACE

identityType

String

身份信息的参数类型,必须传入CERT_INFO。

CERT_INFO

certType

String

用户证件类型。支持的证件类型,请参见方案概述

不同证件类型,取值均为IDENTITY_CARD

IDENTITY_CARD

certNo

String

用户身份证件号码。

330103xxxxxxxxxxxx

certName

String

用户姓名。

张三

returnUrl

String

商户业务页面回调的目标地址。

  • 如您不需要回调商户业务页面,您可以在此处传入空字符串。

  • 当您采用端外唤起支付宝H5方式,且希望您的用户唤起支付宝完成认证后,能够跳回您的应用页面,您需要在此参数下传入您应用的Scheme。更多内容,请参见端外唤起支付宝H5页面

https://www.aliyun.com

callbackUrl

String

认证结果的回调通知地址,必须以HTTPS开头。平台完成认证后会回调该地址,并自动添加certifyIdpassed

https://www.aliyun.com

callbackToken

String

安全Token,由您自行生成,用于防重复、防篡改校验。如果设置了该值会在回调地址显示CallbackToken字段。

NMjvQanQgplBSaEI0sL********

encryptType

String

加密类型。为空表示不加密。

如开启加密传输,需传入加密算法。目前仅支持SM2国密算法。

如需传入加密算法,需对certNamecertNo进行加密,并传入加密后的密文。有关参数加密的更多信息,请参见参数加密说明

说明

目前仅Java语言提供有关开启加密传输的示例代码。更多信息,请参见SDK调用示例

SM2

响应参数

名称

类型

描述

示例值

RequestId

String

请求ID。

130A2C10-B9EE-4D84-88E3-5384FF039795

Message

String

请求消息的响应信息。

OK

certifyId

String

认证ID,刷脸认证的唯一标识。

警告

CertifyId字段为计费统计字段,为了方便后续核对账单,请您在本地留存该字段信息。

初始化接口返回的认证CertifyId在30分钟有效仅能认证提交一次,请您在有效期内应用,避免重复使用。

7eff3ad26a9c7b68c511b9f35eb1****

certifyUrl

String

认证流程入口Url。

重要

初始化接口返回的认证CertifyUrl在30分钟有效仅认证仅能提交一次,请您在有效期内使用,避免重复使用。

https://picker.antcloudauth.aliyuncs.com/gateway.do?...

Code

String

返回码。200表示返回成功,其他返回码均为失败。

200

查询认证结果

method参数的值需设定为query,表示调用查询认证结果。

查询认证结果时,传入以下参数:

请求参数

名称

类型

是否必选

描述

示例值

method

String

查询认证结果的操作。

取值:query

query

certifyId

String

认证ID,需与发起认证请求时返回的certifyId保持一致。

7eff3ad26a9c7b68c511b9f35eb1****

sceneId

String

认证场景ID,需与发起认证请求时的sceneId保持一致。

100000*****

encToken

String

公钥加密后的AES 256密钥(Base64编码),用于获取加密图片。仅面向持牌金融客户KYC留存的认证图片。如何使用RSA公钥加密AES密钥,请参见支付宝小程序或H5方案密钥加密说明

l1tmZUQKdclKdGHzy2hljqltxPYPRo42JjRL04JVHxh9wWP19xHZpVvlKy9lxXRXCiWTKfJAaDfw4pKlZfetvZHdVdjroiXaLt7jx68rpp24wCeWo8wgjMF1lBwJmYZGcTrCVJ+Tonn7CHN7ur11Pn9d4IdkbTi5rBoOx8JITTn6krEH6ssZ5Cj3xFJ4/3PyvloU8UX+FQIPpskYR36jHcqs+Nt4EeTK/wWsAQItl6RfI9FN+8UJ42RVNt/IWHuk3U9aQNxzt7Z+7hbvqpBf/uKp4sgP6fbyYhZ+2tM+KXF1ODOYGenQ65wliaS/C1fTqjUJYcONMEW61Te/de4r4A==

响应参数

名称

类型

是否必选

描述

示例值

passed

String

是否通过认证。取值:

  • T:认证通过。

  • F:未通过认证。

T

identityInfo

String

预留字段,默认返回为空。

materialInfo

String

预留字段,默认返回为空。

SDK调用示例

Java

说明

如需Java SDK源码,请访问aliyun-openapijava-sdk页面下载。

  1. 在pom.xml中添加如下依赖,即可在Maven工程中使用SDK。

    <dependency>
        <groupId>com.aliyun</groupId>
        <artifactId>aliyun-java-sdk-saf</artifactId>
        <version>3.0.2</version>
    </dependency>
    <dependency>
        <groupId>com.aliyun</groupId>
        <artifactId>credentials-java</artifactId>
        <version>LATEST</version>
    </dependency>

    推荐Maven依赖仲裁:

    <dependency>
        <groupId>com.aliyun</groupId>
        <artifactId>aliyun-java-sdk-core</artifactId>
        <optional>true</optional>
        <version>4.6.4</version>
    </dependency>
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>fastjson</artifactId>
        <version>2.0.47</version>
    </dependency>
    <dependency>
        <groupId>com.google.code.gson</groupId>
        <artifactId>gson</artifactId>
        <version>2.10.1</version>
    </dependency>
    <dependency>
            <groupId>com.aliyun</groupId>
            <artifactId>tea</artifactId>
            <version>LATEST</version>
    </dependency>
    说明
  2. 示例代码如下:

    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.FormatType;
    import com.aliyuncs.http.MethodType;
    import com.aliyuncs.http.ProtocolType;
    import com.aliyuncs.profile.DefaultProfile;
    
    public class FaceVerifyTest {
        public static void main(String[] args) throws IOException {
    
            // 阿里云账号AccessKey拥有所有API的访问权限,建议您使用RAM用户进行API访问或日常运维。
            // 强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。
            // 本示例通过阿里云Credentials工具从环境变量中读取AccessKey,来实现API访问的身份验证。
            com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();
            String accesssKeyId = credentialClient.getCredential().getAccessKeyId();
            String accessKeySecret = credentialClient.getCredential().getAccessKeySecret();
    
            DefaultProfile profile = DefaultProfile.getProfile("cn-shanghai",accesssKeyId,accessKeySecret);
            IAcsClient client = new DefaultAcsClient(profile);
    
            CommonRequest request = new CommonRequest();
            request.setSysMethod(MethodType.POST);
    
            request.setSysDomain("saf.cn-shanghai.aliyuncs.com");
            request.setSysVersion("2017-03-31");
            request.setSysAction("ExecuteRequest");
            request.setSysProtocol(ProtocolType.HTTPS);
            request.setHttpContentType(FormatType.FORM);
    
            // 业务详细参数。
            Map<String, Object> serviceParams = new HashMap<String, Object>();
    
            // 发起认证请求。
            serviceParams.put("method",  "init");
            serviceParams.put("sceneId",  "100001***");
            // outerOrderNo参数要求每次都唯一,建议使用UUID工具每次生成。
            serviceParams.put("outerOrderNo",  UUID.randomUUID().toString().replaceAll("-",""));
    
            // 当用户在iOS或安卓平台发起认证时,认证场景码是FACE_SDK;在小程序中,认证场景码则为FACE。
            serviceParams.put("bizCode", "FACE");
            serviceParams.put("identityType", "CERT_INFO");
            serviceParams.put("certType", "IDENTITY_CARD");
            serviceParams.put("certNo", "142702******");
            serviceParams.put("certName", "张三");
            // 认证后回调的页面地址。
            serviceParams.put("returnUrl", "");
            //serviceParams.put("callbackUrl", "https://www.aliyundoc.com");
            //serviceParams.put("callbackToken", "NMjvQanQgplBSaEI0sL86WnQplB");
    
            /*
            // 如需开启个人信息加密传输。
            serviceParams.put("encryptType",  "SM2");
            serviceParams.put("certNo", "BMjsstxK3S4b1YH*****Pet8ECObfxmLN92SLsNg==");
            serviceParams.put("certName", "BCRD/7ZkNy7Q*****M1BMBezZe8GaYHrLwyJv558w==");
            */
    
            // 查询认证结果。
            //serviceParams.put("method",  "query");
            //serviceParams.put("certifyId", "7eace0bcc45a07940d0c50cb69***");
            //serviceParams.put("sceneId", "100001***");
    
            request.putBodyParameter("ServiceParameters", JSON.toJSONString(serviceParams));
            // 固定值,Service = fin_face_verify。
            request.putBodyParameter("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();
            }
        }
    }

Python

  1. 安装SDK核心库。

    • 如果您使用的是Python 2.x,执行以下命令,安装阿里云SDK核心库。

      pip install aliyun-python-sdk-core
    • 如果您使用的是Python 3.x,执行以下命令,安装阿里云SDK核心库。

      pip install aliyun-python-sdk-core-v3
  2. 安装云产品SAF SDK。

    pip install aliyun-python-sdk-saf
  3. 安装Credentials工具。Credentials工具配置方法,请参见身份验证配置

    pip install alibabacloud_credentials==0.3.2
  4. 示例代码如下:

    from aliyunsdkcore import client
    from aliyunsdksaf.request.v20170331 import ExecuteRequestRequest
    from alibabacloud_credentials.client import Client as CredClient
    
    # 阿里云账号AccessKey拥有所有API的访问权限,建议您使用RAM用户进行API访问或日常运维。
    # 强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。
    # 本示例通过阿里云Credentials工具从环境变量中读取AccessKey,来实现API访问的身份验证。
    cred = CredClient()
    accessKey = cred.get_access_key_id()
    accessKeySecret = cred.get_access_key_secret()
    
    clt = client.AcsClient(accessKey, accessKeySecret, 'cn-shanghai')
    
    # 设置参数。
    request = ExecuteRequestRequest.ExecuteRequestRequest()
    request.set_accept_format('json')
    # 产品Service请参考[公共参数]文档中的Service字段描述。
    request.add_query_param('Service', '购买的产品Service')
    request.add_query_param('ServiceParameters', '入参JSON字符串')
    
    # 发起请求。
    response = clt.do_action_with_exception(request)
    print(response)
    
说明

Python SDK的环境准备、安装和使用,请参见阿里云SDK开发指南

PHP

  1. 安装依赖。

    • 安装 SDK 核心库 Core ,如果已在系统上全局安装 Composer,请直接在项目目录中运行以下内容来安装 Alibaba Cloud SDK for PHP 作为依赖项:

      复制composer require alibabacloud/client

      一些用户可能由于网络问题无法安装,可以通过以下命令切换为阿里云 Composer 全量镜像。

      复制composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
    • 安装云产品SAF SDK。

      composer require alibabacloud/saf
  2. 示例代码如下:

    <?php
    require __DIR__ . '/vendor/autoload.php';
    use AlibabaCloud\Client\AlibabaCloud;
    use AlibabaCloud\Client\Exception\ClientException;
    use AlibabaCloud\Client\Exception\ServerException;
    use AlibabaCloud\Credentials\Credential;
    
    // 设置一个全局客户端。
    // 阿里云账号AccessKey拥有所有API的访问权限,建议您使用RAM用户进行API访问或日常运维。
    // 强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。
    // 本示例通过阿里云Credentials工具从环境变量中读取AccessKey,来实现API访问的身份验证。
    
    $credential = new Credential([]);
    $credential->getAccessKeyId() = accessKey ;
    $credential->getAccessKeySecret() = accessKeySecret;
    
    AlibabaCloud::accessKeyClient(accessKey, accessKeySecret)
                ->regionId('cn-shanghai')
                ->asDefaultClient();
    
    // 下述参数依照实际使用的接口做调整,本演示仅针对认证初始化接口。
    $serviceParams = array(
        "method"=>       "init",
        "sceneId"=>      "1000000006",
        "outerOrderNo"=> "e0c34a77f5ac40a5aa5e6ed20c353903",
        "bizCode"=>      "FACE",
        "identityType"=> "CERT_INFO",
        "certType"=>     "IDENTITY_CARD",
        "certNo"=>       "330103xxxxxxxxxxxx",
        "certName"=>     "张三",
        "returnUrl"=>    "https://www.aliyun.com",
        "callbackUrl"=>  "https://www.aliyun.com",
        "callbackToken"=>"NMjvQanQgplBSaEI0sL86WnQplB"
       );
    
    
    try {
        // 下述参数无需调整。
        $result = AlibabaCloud::rpcRequest() 
                               ->product('saf') 
                               ->scheme('https')
                               ->version('2017-03-31')
                               ->action('ExecuteRequest') 
                               ->method('POST')
                               ->host('saf.cn-shanghai.aliyuncs.com')
                               ->options([
                                             'query' => [
                                                 'Service' => 'fin_face_verify',
                                                 'ServiceParameters' => json_encode($serviceParams)
                                             ],
                                         ])
                               ->request();
    
        echo($result);
    } catch (ClientException $exception) {
        echo $exception->getMessage() . PHP_EOL;
    } catch (ServerException $exception) {
        echo $exception->getMessage() . PHP_EOL;
        echo $exception->getErrorCode() . PHP_EOL;
        echo $exception->getRequestId() . PHP_EOL;
        echo $exception->getErrorMessage() . PHP_EOL;
    }
    
    ?>
说明

C#

  1. 引入SDK依赖。

    dotnet add package aliyun-net-sdk-saf --version 3.0.1
    dotnet add package Aliyun.Credentials
  2. 代码示例如下:

    using System.Text.Json;
    using Aliyun.Acs.Core;
    using Aliyun.Acs.Core.Exceptions;
    using Aliyun.Acs.Core.Profile;
    using Aliyun.Credentials.Models;
    
    class FaceVerifyTest
    {
        static void Main(string[] args)
        {
          
            // 阿里云账号AccessKey拥有所有API的访问权限,建议您使用RAM用户进行API访问或日常运维。
            // 强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。
            // 本示例通过阿里云Credentials工具从环境变量中读取AccessKey,来实现API访问的身份验证。
            Credential=new Aliyun.Credentials.Client(null)
            string accessKeyId = credentialClient.GetAccessKeyId();
            string accessKeySecret = credentialClient.GetAccessKeySecret();
       
            IClientProfile profile = DefaultProfile.GetProfile(
                "cn-shanghai",
                accessKeyId,
                accessKeySecret);
            DefaultAcsClient client = new DefaultAcsClient(profile);
            try
            {
                // 构造请求
                CommonRequest request = new CommonRequest();
                request.Protocol = Aliyun.Acs.Core.Http.ProtocolType.HTTPS;
                request.Domain = "saf.cn-shanghai.aliyuncs.com";
                request.Version = "2017-03-31";
                request.Action = "ExecuteRequest";
    
                //固定值,Service = fin_face_verify。
                request.AddQueryParameters("Service", "fin_face_verify");
    
                Dictionary<string, string> ServiceParameters = new Dictionary<string, string>();
                ServiceParameters.Add("method", "init");
                ServiceParameters.Add("sceneId", "100000000");
                ServiceParameters.Add("outerOrderNo", "e0c34a77f5ac40a5aa5e6ed20c353888");
                ServiceParameters.Add("bizCode", "FACE");
                ServiceParameters.Add("identityType", "CERT_INFO");
                ServiceParameters.Add("certType", "IDENTITY_CARD");
                ServiceParameters.Add("certNo", "330103xxxxxxxxxxxx");
                ServiceParameters.Add("certName", "张三");
                ServiceParameters.Add("returnUrl", "https://www.aliyun.com");
                ServiceParameters.Add("callbackUrl", "https://www.aliyun.com");
                ServiceParameters.Add("callbackToken", "NMjvQanQgplBSaEI0sL86WnQplB");
                /**
                 * 查询认证结果。
                 * map.Add("method", "query");
                 * map.Add("certifyId", "7eff3ad26a9c7b68c511b9f35eb1a354");
                 * map.Add("sceneId", "100000000");
                 */
                request.AddQueryParameters("ServiceParameters", JsonSerializer.Serialize(ServiceParameters));
                // 发起请求,并得到Response
                CommonResponse response = client.GetCommonResponse(request);
                System.Console.WriteLine(response.Data);
            }
            catch (ServerException ex)
            {
                System.Console.WriteLine(ex.ToString());
            }
            catch (ClientException ex)
            {
                System.Console.WriteLine(ex.ToString());
            }
        }
    }
说明

Golang

  1. 安装依赖。

    • 安装 SDK 核心库 Core ,使用pip安装包依赖:

      pip install aliyun-python-sdk-core
    • 安装云产品SAF SDK。

      pip install aliyun-python-sdk-saf==undefined
  2. 示例代码:

    package main
    
    import (
        "encoding/json"
        "fmt"
    
        "github.com/aliyun/alibaba-cloud-sdk-go/sdk"
        "github.com/aliyun/alibaba-cloud-sdk-go/sdk/requests"
        "github.com/aliyun/credentials-go/credentials"
    )
    
    // ResponseContent返回体。
    type ResponseContent struct {
        Data      map[string]string `json:"data"`
        RequestID string            `json:"requestId"`
        Code      string            `json:"code"`
        Message   string            `json:"message"`
    }
    // 阿里云账号AccessKey拥有所有API的访问权限,建议您使用RAM用户进行API访问或日常运维。
    // 强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。
    // 本示例通过阿里云Credentials工具从环境变量中读取AccessKey,来实现API访问的身份验证。
    func main() {
        credential, _err := credentials.NewCredential(nil)
        if _err != nil {
        panic(_err)
      }
      accessKeyId, err := akCredential.GetAccessKeyId()
      accessKeySecret, err := akCredential.GetAccessKeySecret()
        client, err := sdk.NewClientWithAccessKey(
            "cn-shanghai", accessKeyId, accessKeySecret)
        request := requests.NewCommonRequest()
        // 下述参数无需调整。
        request.Domain = "saf.cn-shanghai.aliyuncs.com"
        request.Version = "2017-03-31"
        request.ApiName = "ExecuteRequest"
        request.Scheme = "https"
        request.QueryParams["Service"] = "fin_face_verify"
    
        // 下述参数依照实际使用的接口做调整,本演示仅针对认证初始化接口。
        serviceParam := map[string]string{
            "method":       "init",
            "sceneId":      "1000000006",
            "outerOrderNo": "e0c34a77f5ac40a5aa5e6ed20c353900",
            "bizCode":      "FACE",
            "identityType": "CERT_INFO",
            "certType":     "IDENTITY_CARD",
            "certNo":       "330103xxxxxxxxxxxx",
            "certName":     "张三",
            "returnUrl":    "https://www.aliyun.com",
            "callbackUrl":  "https://www.aliyun.com",
            "callbackToken":"NMjvQanQgplBSaEI0sL86WnQplB"
        }
    
        serviceParamByte, err := json.Marshal(serviceParam)
        if err != nil {
            panic(err)
        }
        request.QueryParams["ServiceParameters"] = string(serviceParamByte)
    
        response, err := client.ProcessCommonRequest(request)
        if err != nil {
            panic(err)
        }
        respContent := ResponseContent{}
        err = json.Unmarshal(response.GetHttpContentBytes(), &respContent)
        fmt.Printf("response data is %#v\n", respContent.Data)
        fmt.Println("end")
    }
说明

Node.js

  1. 执行以下命令安装@alicloud/pop-core模块。

    $ npm install @alicloud/pop-core --save

    命令中的--save会将模块写入应用的package.json文件中,作为依赖模块。

  2. Node.js 代码示例:

    const Core = require('@alicloud/pop-core');
    const { default: Credential } = require('@alicloud/credentials');
    
    // 阿里云账号AccessKey拥有所有API的访问权限,建议您使用RAM用户进行API访问或日常运维。
    // 强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。
    // 本示例通过阿里云Credentials工具从环境变量中读取AccessKey,来实现API访问的身份验证。
    const cred = new Credential;
    var client = new Core({
      credential: cred,
      endpoint: 'https://saf.cn-shanghai.aliyuncs.com',
      apiVersion: '2017-03-31'
    });
    
    // 下述参数依照实际使用的接口做调整,本演示仅针对认证初始化接口。
    var serviceParams = {
        "method":       "init",
        "sceneId":      "1000000006",
        "outerOrderNo": "e0c34a77f5ac40a5aa5e6ed20c353901",
        "bizCode":      "FACE",
        "identityType": "CERT_INFO",
        "certType":     "IDENTITY_CARD",
        "certNo":       "330103xxxxxxxxxxxx",
        "certName":     "张三",
        "returnUrl":    "https://www.aliyun.com",
        "callbackUrl":  "https://www.aliyun.com",
        "callbackToken":"NMjvQanQgplBSaEI0sL86WnQplB"
    }
    
    var params = {
      "RegionId": "cn-shanghai",
      "Service": "fin_face_verify",
      "ServiceParameters": JSON.stringify(serviceParams)
    }
    
    var requestOption = {
      method: 'POST'
    };
    
    client.request('ExecuteRequest', params, requestOption).then((result) => {
      console.log(JSON.stringify(result));
    }, (ex) => {
      console.log(ex);
    })
说明