资源中心接口调用介绍
您可以点击纯净版进行查看

接口调用概述

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

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

接口(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 POSTHTTP 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 定义了两个业务参数,param1param2,值分别为 param1valueparam2value。系统参数 params 和业务参数的关系为:

params= URLEncode(Base64(RSAEncrypt(param1=URLEncode(param1value)?m2=URLEncode(param2value))))

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

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

最后对 Base64 编码后的 params 参数做一次 URLEncodeURLEncode 后的值最终组成了系统参数 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 的公私钥,双方交换公钥。对于生成公私钥的方式,参考 环境配置 章节。

对于 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 对象),通过一些简单的 gettersetter 方法设置 Request 对象的属性,直接进行请求的提交,并得到对应的 Response 对象。对于页面授权的接口,SDK 同样提供了方便的方法进行页面 URL 的生成。

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

SDK 使用详见开发指南,SDK 下载见开发工具包(SDK)下载。

数据反馈

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

数据反馈

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

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

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

  1. 接口调用概述
  2. 接口(API)的概念
  3. HTTP 服务报文规范
  4. 请求参数规范
  5. 返回值规范
  6. 加解密和加签验签
  7. 业务流水凭证
  8. SDK 使用
  9. 数据反馈
onlineServer