平台概述

量子保开放平台将核心的通用保险产品引擎适配对接多家保险公司后台,以开放接口的形式提供给合作商家,一站式的为商家提供保险行业标准的全生命周期的保单管理,以及理赔单管理服务,提升合作商家的产品竞争力和财务风险管理能力。

在使用该文档之前,量子保平台会为商家提供量子保商户平台的登录资格(http://www.liangzibao.cn/merchant/do/login),并指导技术对接。

文档概述

本文档主要包含两个部分:

通用约定

本文档主要包含两个部分:

全部API采用HTTP协议交互,API全部参数采用POST方法进行传递

调用API时必须按照 《API接入说明》对调用参数进行加密和签名

如不加特殊说明,API同时适用于沙箱环境和生产环境

在下文的API接入说明和应用API说明中,商家将被称为开发者,避免歧义

接入流程图

流程图

接入准备

量子保平台目前仅支持rsa加密算法对API参数进行加密和验签,其流程如图2-1所示:

1. 当开发者客户端向量子保开放平台发送请求信息时,开发者客户端先使用量子保开放平台的公钥对数据进行加密,然后使用自己的私钥对数据进行加签。量子保开放平台收到数据之后,先使用量子保自己的私钥对数据进行解密,然后使用开发者的公钥对数据进行验签。

2. 当量子保开放平台向开发者客户端发送返回结果信息时,量子保开放平台先使用开放者的公钥对数据进行加密,然后使用自己的私钥对数据进行加签。开发者客户端收到数据后,应先使用自己的私钥对数据进行解密,然后使用量子保的公钥对数据进行验签。

获取量子保开放平台的rsa公钥

开发者在量子保商户平台登录后,可以通过页面获取量子保开放平台相应环境的rsa公钥。

开发者生成rsa密钥对并上传rsa公钥

1. 生成私钥

例:openssl genrsa -out rsa_private_key.pem 1024

2. 生成公钥

例:openssl rsa -in rsa_private_key.pem -pubout -out rsa_public_key.pem

3. 在量子保商户平台的页面中上传rsa_public_key.pem的内容。

请求流程

应用参数加密流程:

1. 开发者需要将应用API参数组装成json字符串,例:

{
        "product_mask":"184371",
        "mer_order_id":"123"
    }

2. 使用对应环境的量子保平台公钥对1步的json字符串做rsa加密,该加密串作为biz_content参数的内容,例:

biz_content=qmd\/ap+lacLJDCLzI5A61BQTn6tCF9eLy0yH58+7JLslTtXPHRLaIKxAU4ejr4CyFRD\/9TsRkfw16J6RQMzUVgqydd7nP99+dnIo6snZk6SqrS0t0p9dbk9ooOrDK956eaUCj3bp4Gb0hYiUyU2619rmTG7YZWow1uNvU3lBSj94ASKPJHcbX4bBp3kG71EHY6NPp8FG9VF2Q7X7CaMbkvk0GnqgY7eMe75I8cOUtZV6CneOaj4JMav67q6FuruzTMVv2Ymwv+ftpvIIZ3ryNjpaiIJZaSPKUSGKrePvh4Y6eLcAgYfULTEtl0GbBpUAMvwDwaaHU\/6uxddZcXK\/Jlke\/8Uf9HB+m9pjoiCh9d+MOSqslxAyjq+BZj1dGEqd8tULiqLweq+S3L5z73EBlJcOLKIIvdQWsZpl0CswJzc1\/18byqm7kmrkklZGhJ8qe6mFqg0nDNJeopLv0XNfuAgVWKd9i2hNnj3QhHaLcSMfrXGpHp+N+ACDvCmZ\/\/1C

安全签名并发送:

1. 开发者将所有的请求公共参数,包括biz_content,按照字段名的ASCII码进行从小到大排序组装成一个json字符串,例:

{
     "app_key":"6823490131d9146da878b66119dcd313",
     "biz_conent":"qmd\/ap+lacLJDCLzI5A61BQTn6tCF9eLy0yH58+7JLslTtXPHRLaIKxAU4ejr4CyFRD\/9TsRkfw16J6RQMzUVgqydd7nP99+dnIo6snZk6SqrS0t0p9dbk9ooOrDK956eaUCj3bp4Gb0hYiUyU2619rmTG7YZWow1uNvU3lBSj94ASKPJHcbX4bBp3kG71EHY6NPp8FG9VF2Q7X7CaMbkvk0GnqgY7eMe75I8cOUtZV6CneOaj4JMav67q6FuruzTMVv2Ymwv+ftpvIIZ3ryNjpaiIJZaSPKUSGKrePvh4Y6eLcAgYfULTEtl0GbBpUAMvwDwaaHU\/6uxddZcXK\/Jlke\/8Uf9HB+m9pjoiCh9d+MOSqslxAyjq+BZj1dGEqd8tULiqLweq+S3L5z73EBlJcOLKIIvdQWsZpl0CswJzc1\/18byqm7kmrkklZGhJ8qe6mFqg0nDNJeopLv0XNfuAgVWKd9i2hNnj3QhHaLcSMfrXGpHp+N+ACDvCmZ\/\/1C",
     "charset":"UTF8",
     "format":"JSON",
     "service_name":"lzb.ride.policy.create",
     "sign_type":"RSA",
     "timestamp":1482487731,
     "version":"1.0.0"
}

2. 使用开发者自己的rsa秘钥对1步骤的json字符串做签名,签名字符串作为sign参数的内容。

3. 将1步骤参数列表和2步骤的sign参数合并,生成json字符串,通过HTTP的POST方式发送请求,请注意HTTP的header字段Content-Type 为"application/x-www-form-urlencoded;charset=utf-8",例:

{
     "app_key":"6823490131d9146da878b66119dcd313",
     "service_name":"lzb.ride.policy.create",
     timestamp":1482487731,
     "format":"JSON",
     "sign_type":"RSA",
     "charset":"UTF8",
     "version":"1.0.0",
     "biz_conent":"qmd\/ap+lacLJDCLzI5A61BQTn6tCF9eLy0yH58+7JLslTtXPHRLaIKxAU4ejr4CyFRD\/9TsRkfw16J6RQMzUVgqydd7nP99+dnIo6snZk6SqrS0t0p9dbk9ooOrDK956eaUCj3bp4Gb0hYiUyU2619rmTG7YZWow1uNvU3lBSj94ASKPJHcbX4bBp3kG71EHY6NPp8FG9VF2Q7X7CaMbkvk0GnqgY7eMe75I8cOUtZV6CneOaj4JMav67q6FuruzTMVv2Ymwv+ftpvIIZ3ryNjpaiIJZaSPKUSGKrePvh4Y6eLcAgYfULTEtl0GbBpUAMvwDwaaHU\/6uxddZcXK\/Jlke\/8Uf9HB+m9pjoiCh9d+MOSqslxAyjq+BZj1dGEqd8tULiqLweq+S3L5z73EBlJcOLKIIvdQWsZpl0CswJzc1\/18byqm7kmrkklZGhJ8qe6mFqg0nDNJeopLv0XNfuAgVWKd9i2hNnj3QhHaLcSMfrXGpHp+N+ACDvCmZ\/\/1C",
     sign:”vdHfiiw8IiMO6cIh4Zv8FoW77K3HsrSxPFcZXX1MS8O8qwDPVG9tR4Fx8Fl3UkRPHB/BtRb5n/n6HKmPYtbFc7Gp4ZY8nb160HDhY+TfxWz3WFFjLW2meN062E3XKCaJ7DOzYhhWB53CFVbn8f+oQ/a8oq/TDCfM0utaf3cpOQE=”
    }

请求公共参数

调用任意一个API都需要保证传递以下公共参数:

参数名称 参数类型 是否必须 参数描术 样例参数
app_key string 平台分配给每个接入商户的唯一标示
service_name string 应用API名称
biz_content string 应用参数报文,目前是json字符串
format string API报文格式,目前仅支持json JSON
timestamp string 请求时间戳,使用unix timestamp
sign_type string API参数签名方法,目前仅支持ras RSA
sign string API参数签名
charset string API字符编码 UTF8
version string API版本号 1.0.0

响应公共参数

调用任意一个API都需要保证传递以下公共参数:

参数名称 参数类型 参数描术 样例参数
biz_content string 应用参数报文,目前是json字符串
format string API报文格式,目前仅支持json JSON
timestamp string 请求时间戳,使用unix timestamp
sign_type string API参数签名方法,目前仅支持ras RSA
sign string API参数签名
charset string API字符编码 UTF8
ret_code int 返回码
ret_msg string 返回信息

响应流程

返回值验签:

1. 开发者将除了sign以外的所有的返回参数,按照字段名的ASCII码进行从小到大排序组装成一个json字符串,例:

openssl genrsa -out rsa_private_key.pem 1024

2. 生成公钥,例:

{
     "biz_content": "NEPW9dEt4wsgmzSEoUJZJ57rP1nMZXnFrQotpQyMXNXffB0PQmQ0+6yhhNkiiaC5tHXuivy0uyjEZOTB8DaSOetkW4KH58uIXoWiMdmulEcblRj4S6b/kbodOnXL0MDlEwOlK6IPBdYvm2TlJdCTY2WeKQmX2n8YPlDcT5o49b0=",
     "chartset": "UTF8",
     "format": "JSON",
     "sign_type": "RSA",
     "timestamp": "1482487731"
    }

3. 用对应环境的量子保开放平台公钥对sign的值进行验签。

返回值解密

验签成功后,开发者用自己密钥对返回值中biz_content做rsa解密操作,获取应用返回值,例:

{
     “status”:1,
      "policy_id":"P23978776656875520"
    }

状态字典

保单状态字典

保单状态码 保单状态描述 备注
10 创建保单
13 核保
14 核保失败
15 核保失败
17 待支付
20 出单中
30 出单完成
40 出单失败
50 保障中
60 保障期满
70 取消保单
80 保单终止
90 退保

理赔单状态字典

理赔单状态码 理赔单状态描述 备注
10 发起理赔
20 举证
30 核赔中
40 核赔完成
50 已赔付
60 拒绝赔付
70 取消理赔

保单创建接口

该接口用于生成出行类保单

请求参数

公共参数表:

参数名称 参数类型 是否必须 参数描述 样例参数
product_mask string 出行保险品类下的不同类型保险的唯一ID
mer_order_id string 对应商家的订单ID,不同的保单该ID可以相同
mer_order_uuid string 商家定制唯一ID,要求不同保单该ID不同
start_time string 保单生效时间,实际用户乘车时间
end_time string 保单结束时间,实际用户下车时间

被保人参数表- insurance_user_info:

参数名称 参数类型 是否必须 参数描述 样例参数
user_id string 被保人唯一ID

商家订单关联保信息表- mer_order_info:

参数名称 参数类型 是否必须 参数描述 样例参数
book_user_id int 商户订车人唯一ID

响应参数

公共响应参数表:

参数名称 参数类型 是否必须 样例参数
status int 1-正确,2-失败 保单号

保单更新接口

该接口用于更新出行类保单的结束时间字段

请求参数

公共参数表:

参数名称 参数类型 是否必须 参数描述 样例参数
product_mask string 出行保险品类下的不同类型保险的唯一ID
mer_order_uuid string 商家定制唯一ID,要求不同保单该ID不同
policy_id string 保单号
end_time string 保单结束时间,实际用户下车时间

响应参数

公共响应参数表:

参数名称 参数类型 是否必须 样例参数
status int 1-正确,2-失败
policy_id string 保单号
mer_order_uuid string 商家定制唯一ID,要求不同保单该ID不同

保单详情接口

该接口用于返回保单的详细信息

请求参数

公共请求参数表:

参数名称 参数类型 是否必须 参数描述 样例参数
product_mask string 出行保险品类下的不同类型保险的唯一ID
mer_order_uuid string 商家定制唯一ID,要求不同保单该ID不同
policy_id string 保单号

响应参数

公共响应参数表:

参数名称 参数类型 是否必须 样例参数
status int 1-正确,2-失败