淘宝开放平台

登录
文档中心 > 芝麻开放文档测试

芝麻信用-开始接入-应用开发-技术对接

更新时间：2017/02/10 访问次数：1501

概述

芝麻信用开放平台提供了 Java1.5、Java1.4、PHP 和 .NET 的服务器端 SDK 供商户使用。通过使用服务端 SDK，我们可以避免繁琐的加密加签解密验签的代码，大大提高接入的效率。对于使用服务端SDK进行接入的商户，可以直接参考“服务端SDK的使用”部分，对于没有提供服务器端 SDK 的语言，商户可以通过仔细阅读 HTTP 服务报文规范和**加解密和加签验签**部分来进行接入。

芝麻信用开放平台同时也提供了移动端 SDK 供商户使用，方便商户在自己的移动 App 中集成芝麻的服务，关于如何使用移动端 SDK，参考“移动端 SDK 接入”部分。

芝麻信用产品需要通过调用芝麻信用授权接口进行授权，关于如何进行用户授权，参考用户授权部分。另外，有些产品对接后，是需要商户进行数据反馈的，关于数据反馈，参考数据反馈部分。

接口（API）的概念

目前芝麻信用开放平台支持两种类型的接口，一种是系统调用类接口，主要是商户后端直接通过HTTP的方式进行接口调用，并同步返回结果给商户。另外一种是页面跳转类接口，这种接口的用法是商户在浏览器中输入芝麻信用开放平台的URL并组织好对应的参数，以HTTP GET的方式进行调用，用户页面授权接口(zhima.auth.info.authorize)就是属于页面跳转类接口，用户在页面上完成相应的操作后，浏览器最后跳转到商户提供的callback URL，并带上业务的返回结果在callback页面的URL中，从而商户可以在后台从callback URL的请求中把业务返回结果拿到。

每个通过芝麻信用开放平台输出的芝麻信用产品，都会对应于一个注册在开放平台中的接口（API）,这些接口中会定义业务参数的列表，系统参数列表，返回值字段列表，以及错误码列表。每个接口会有一个对应的接口文档，里面会对系统参数、业务参数、返回值和错误码都有详细的描述。

HTTP 服务报文规范

这个部分介绍了商户应该如何组装 HTTP 请求来调用芝麻信用开放平台以访问芝麻信用产品服务。 ?

芝麻信用开放平台 HTTP 服务地址

https://zmopenapi.zmxy.com.cn/openapi.do

HTTP请求方式：

  1. 对于文件上传的系统调用类接口，只支持HTTP POST
  2. 对于不需要文件上传的系统调用类接口，同时支持HTTP POST和HTTP GET，由于HTTP GET对于报文长度本身的限制，推荐尽量使用HTTP POST的方式。
  3. 对于页面跳转类的服务接口，只支持HTTP GET

请求参数规范

对于系统调用类接口和页面跳转类接口，请求参数的规范都是相同的，包含系统参数部分和业务参数部分，需要注意的是所有参数都需要进行编码（URLEncode），如下所述：

参数名 类型 是否必须 是否芝麻分配 示例值 备注
app_id String 是 是 1000033 商户应用ID
charset String 是 否 UTF-8 加密加签时使用的charset
method String 是 是 zhima.auth.info.authorize 要调用的接口名
version String 是 是 1.0 接口版本，目前只支持1.0
platform String 否 是 zmop 来源平台，默认为zmop
params String 是 否 abc RSA加密后的业务参数
sign String 是 否 bcd 对params参数加密前的签名,算法为SHA1WithRSA

每个接口文档中详细定义了接口业务参数列表，业务参数本身是通过系统参数params发送到服务器端的。这里主要描述这些业务参数是以什么格式组合，并拼装成了系统参数params的。假设接口A定义了两个业务参数，param1和param2，值分别为param1value和param2value。系统参数params和业务参数的关系为：

params= URLEncode(Base64(RSAEncrypt(param1=URLEncode(param1value)&param2=URLEncode(param2value))))

首先对于每个业务参数，先进行一次URLEncode，然后按照URL中传递参数的方式把param1和param2拼接起来（使用&和=号）然后对拼接起来的业务参数进行RSA的加密，得到byte数组

然后对RSA加密后得到byte数组进行Base64编码

最后对Base64编码后的params参数做一次URLEncode，URLEncode后的值最终组成了系统参数params的值以查询用户芝麻信用评分为例，组装params参数的方法如下：

params=URLEncode(Base64(RSAEncrypt(transaction_id=URLEncode(201512100936588040000000465158)&product_code=URLEncode(w1010100100000000001)&open_id=URLEncode(26881000000790944949667687))))?

返回值规范

对于系统调用类接口和页面跳转类接口，返回值的规范有所不同,如下所述：

系统调用类接口：

在接口调用成功的情况下，开放平台对返回数据进行了加密，开放平台返回值的格式如下：

{
    "encrypted": true,
    "biz_response_sign": "业务数据签名",
    "biz_response": "业务密文数据"
}

这是一个json格式的数据，商户首先需要解析encrypted字段，判断是否需要解密，如果值为true，那么需要解密，否则无需解密。在需要解密时，使用商户私钥解密biz_response字段的值，得到接口的业务返回数据。

在接口调用失败的情况下，开放平台不会对返回数据进行加密，开放平台返回值的格式如下：

{
    "encrypted": false,
    "biz_response": {
        "success": false,
        "error_code": "ZMOP.unknow_error",
        "error_message": "未知错误"
    }
}

页面跳转类接口

对于页面跳转类接口，前面提到在用户页面操作完成后，系统会重定向到商户提供的一个callback URL上， 并把业务的返回结果带在callback URL里面。格式如下：

http://merchant_provided_callback_url?params=xxx&sign=xxx

params里面是加密后的业务返回结果，sign是对业务结果加密前的签名。这两个参数都会在URLEncode之后添加在商户提供的callback URL后面。

加解密和加签验签

在进行技术对接之前，芝麻信用和商户要分别生成一对RSA1024的公私钥，双方交换公钥。对于生成公私钥的方式，参考：

RSA 公私钥生成说明

对于Java和.NET语言，需要将私钥转换成PKCS8的格式，转换的具体命令参考上述文档。对于PHP语言，无需进行转换，直接使用生成的公私钥文件即可。

入参加密加签

在接口调用的系统参数中, params参数需要进行RSA1024的加密，具体算法为“RSA/None/PKCS1Padding”，对params参数加密时，使用的是芝麻的公钥。sign参数是对params加密前数据的签名，使用的算法是SHA1WithRSA，签名时使用的是商户的私钥。

返回值解密验签

在返回值规范中，我们提到，对于接口成功调用的情况，返回值的规范是：

{
    "encrypted": true,
    "biz_response_sign": "业务数据签名",
    "biz_response": "业务密文数据"
}

在这里，我们需要对biz_response字段进行RSA解密，具体算法为“RSA/None/PKCS1Padding”，对返回值的加密，使用的是商户RSA公钥，商户需要使用商户RSA私钥对返回值进行解密。同时，我们需要使用biz_response_sign字段里签名值对解密后的业务数据进行验签，具体是用的算法为SHA1WithRSA，由于签名是使用芝麻的RSA私钥进行签名的，因此商户端需要使用芝麻的RSA公钥对签名进行验签。

业务流水凭证

业务流水凭证（transaction_id）是商户（或机构）与芝麻信用系统产生业务交互的唯一凭证，由商户（或机构）生成作为业务入参，并且会作为与芝麻信用明细对账的唯一依据。具体表现为一个长度为不大于64位的字符串，仅能包含0-9A-Za-z_-等字符。

芝麻信用系统会为每次有效的业务返回做默认24小时的缓存（产品的特殊缓存时间见该产品的接口文档），在缓存有效期内，商户（或机构）可以使用与当次业务交互相同的业务流水凭证（transaction_id）和相同的业务入参，调用相同的接口，取到相同的结果。但如果使用不同的业务流水凭（transaction_id），即使其他参数相同，芝麻信用系统将其视为一次新的业务交互。

业务流水凭证的常见误区和代码范例

SDK 使用

为了提高商户的接入效率，芝麻信用开放平台提供了Java1.5、Java1.4、PHP和.NET的开放平台SDK供商户使用。通过使用服务端SDK，我们可以避免繁琐的加密加签解密验签的代码，大大提高接入的效率和成功率。对于每一个接口，开放平台SDK都会生成一个对应的Request对象和一个Response对象（PHP不会生成Response对象），通过一些简单的getter和setter方法设置request对象的属性，直接进行请求的提交，并得到对应的Response对象。对于页面授权的接口，SDK同样提供了方便的方法进行页面URL的生成。

同时，为了加快商户App接入芝麻的速度，?提高接入体验，?芝麻信用提供了移动版的SDK（Android，iOS）。

SDK 使用详见开发指南，SDK 下载见开发工具包（SDK）下载。

数据反馈

部分芝麻信用产品需要商户进行数据反馈，产品需要反馈的数据详情请在已签约产品模块查看，如下：

数据反馈

每个产品文档中也有介绍该产品是否需要商户进行数据反馈。

芝麻信用提供了接口帮助商户进行数据反馈，具体接口参数信息请分别参考文档批量数据反馈。

对于数据反馈的需要反馈哪些数据字段，根据商户所处的行业不同而有所不同。

FAQ

关于此文档暂时还没有FAQ
有用(0) 我要提问
返回
顶部