华润置地 OpenAPI平台使用接驳

华润置地
OpenAPI平台使用接驳接口说明














2019年7月























更改历史


版本       
日期       
作者       
备注
0.1.0        2019.07.05        曾慧、周伟绅        新建
0.1.1        2019.07.09        周伟绅        添加数据来源字段
0.1.2        2019.07.10        曾慧        添加商品相关信息字段
0.1.3        2019.09.26        曾慧        修改errcode说明和请求参数说明与示例
0.1.4        2019.11.08        曾慧        修改公共请求参数是否必填说明
0.1.5        2019.11.12        曾慧        接口响应报文增加参考号refOrderId
0.1.6        2019.12.10        曾慧        添加2.2.6请求签名内容案例
0.1.7        2021.12.01        曾慧        添加2.2.7openAPI代码加密签名方法范例
0.1.8        2021.12.14        曾慧        1、2.2.5.1添加补充说明
2、2.2.6添加批注请求报文的范例，方便参考签名样例内容
3、3.2接口参数说明补充itemList和payList说明
0.1.9        2021.12.17        曾慧        1、修改签名说明内容
2、添加代码示例
3、修改了请求参数说明





审核历史


版本       
日期       
审核人       
职位
                       
                       
                       






















1、        前言
在承租方与租赁方双方签署的XXXXXX 号商铺（下称“该商铺”）的《XXXXXXXX商铺租赁合同》（下称“租赁合同”）规定的租赁期（下称“租赁期”）内，承租方有义务按照租赁合同内要求将每日每笔销售交易数据通过软件接口的方式，每日按时传送给租赁方（业主）的管理系统内。承租方同意使用租赁方（业主）提供的销售数据上传的形式，并协助租赁方（业主）在商铺开业前，完成数据接口调试与上传工作。
为配合此次项目销售数据实时采集项目的要求；现将数据接口技术方案通过此文给予发布，以便承租方POS研读使用销售数据接口
2、        集成技术规范
2.1集成方式概述
置地提供统一、开放API，系统前端支持REST请求方式，REST请求与响应采用JSON报文格式。
2.2服务接入技术规范
2.2.1传输协议规范
强制规范
集成规范要求信息系统服务集成采用HTTP、HTTPS。
建议规范
HTTP建议采用1.1版本。
2.2.2报文格式规范
强制规范
JSON报文格式作为接入数据格式规范，服务提供方和服务消费方均严格遵循JSON报文格式进行数据交互。
2.2.3报文编码规范
强制规范
JSON报文均采用UTF-8编码。
2.2.4请求参数规范
强制规范
服务请求公共参数详见下表：
名称        类型        最大长度        是否必须        描述
公共请求参数        App_Sub_ID        String        16        是        API调用方应用的编码，同App_ID
        App_Token        String        32        是        API调用方授权令牌
        Api_ID        String        64        是        API调用的API编码
        Api_Version        String        8        是        调用的API版本号
        Time_Stamp        String        19        是        时间戳，格式为yyyy-mm-dd HH:mm:ss:SSS，时区为GMT+8；
        Sign_Method        String        8        是        生成服务请求签名字符串所使用的算法类型，目前仅支持MD5
        Sign        String        32        是        服务请求的签名字符串(采用32位大写)
        Format        String        8        是        响应格式,默认为json格式，可选值：xml或json
        Partner_ID        String        16        是        合作伙伴身份标识
        Sys_ID        String        16        是        合作伙伴系统编码
        App_Pub_ID        String        16        是        被调用API的应用编码

        以上参数建议调用方可灵活配置。
2.2.5请求签名规范
强制规范
1.        对所有公共请求参数（除去sign参数）和REQUEST_DATA，根据参数名称ASCII码表顺序排序；（REQUEST_DATA里面的参数之间不需要ASCII排序，注意除了timestamp的值外其它REQUEST_DATA里面的参数和值不要有空格,请求报文key:value 要与待签名字符串的key=value一致）
2.        将排序好的参数名和参数值组合成“参数=参数值”的格式，并且把这些参数用&字符连接起来，此时生成的字符串为待签名字符串。
待签名字符串排序示例：Api_ID=***&Api_Version=***&App_Pub_ID=***&App_Sub_ID=***&App_Token=***&Format=***&Partner_ID=***&REQUEST_DATA=***&Sign_Method=***&Sys_ID=***&Time_Stamp=***
3.        将待签名字符串和秘钥组合成“待签名字符串&秘钥”格式，再进行md5算法（采用32位大写格式），得出签名（sign）的值。
注：以下参数由imPOS提供，需提交邮箱申请
（App_ID即App_Sub_ID）



2.2.6请求签名示例(签名样例内容与3.2接口请求报文信息内容一致)
Api_ID=mixc.imPOSWBJB.GLWXCJB.orderCollect&Api_Version=1.0.0&App_Pub_ID=10000133301US&App_Sub_ID=10000133334PY&App_Token=c861e8a4be0f41b182abdb55b986444a&Format=json&Partner_ID=70000006&REQUEST_DATA={"cashierId":"20028hvgl120n0101","checkCode":"p88888888","mall":"20028","orderId":"1081983263","payList":[{"discountAmt":7.96,"payAmt":61,"paymentMethod":"OT","time":"20220405000000","value":53.04}],"store":"HVGL120N01","tillId":"01","time":"20220405105628","totalAmt":"53.04","type":"SALE"}&Sign_Method=md5&Sys_ID=100001333&Time_Stamp=2022-04-20 17:37:50:583&0bca40d57d1f44208d787a4e0a87957d
MD5加密结果：491F3087452F1965020F286193239750

2.2.7请求签名代码加密方法范例

2.3服务报文技术规范
2.3.1请求方REST请求报文规范
强制规范
服务请求方系统的请求报文格式有明确的规定，遵循如下JSON报文格式。
1.        所有API都可以用POST发起请求；
2.        请求参数分为系统级公共请求参数+应用级业务请求参数；
3.        报文样例：JSON
{
"REQUEST": {
  "HRT_ATTRS": {
            
            "Partner_ID": "70000006",
            "Api_Version": "1.0.0",
            "App_Sub_ID": "10000133334PY",
            "Format": "json",
            "Time_Stamp": "2022-04-20 17:37:50:583",
            "Api_ID": "mixc.imPOSWBJB.GLWXCJB.orderCollect",
            "App_Token": "c861e8a4be0f41b182abdb55b986444a",
            "App_Pub_ID": "10000133301US",
            "Sign_Method": "md5",
            "Sign":"491F3087452F1965020F286193239750",（参考2.2.5签名规范）
            "Sys_ID":"100001333"   
            }
    REQUEST_DATA: {
        业务参数
    },
}
}

2.4接口地址
UAT环境：http://ztopenapiuat.crland.com.cn:81/api-gateway/rs-service/
内外网均可访问
3、        接口说明
3.1处理逻辑说明
接口        订单上传接口        源->目标        外部渠道系统->IMPOS
接口需求描述        上传订单信息
备注       


3.2接口请求报文信息
请求参数        参数名        类型        是否必填        说明
收银员编号        cashierId        String        Y        必填项
商品数组        itemList        String        Y        必填项；
填写内容："itemList": [ ]
        商品编号        itemCode        String        N
非必填；
        商品价格        price        number        N        非必填；如果填写了商品编号itemCode，则商品价格必填

        商品数量        quantity        number        N        非必填；如果填写了商品编号itemCode，则商品数量必填

商场编号        mall        String        Y        必填项
长度：最小1位，最大40位

订单号        orderId        String        Y        必填项
长度：最小6位，最大40位

支付行        payList        String        Y        必填项；填写格式
"payList":[{ “参数名”:”值”}],

        支付方式        paymentMethod        String        Y        必填项
根据ERP的支付方式。例如现金是CH；支付宝是AP；微信是WP；银行卡是CI；其它是OT等等
        支付时间        time        String        Y        必填项
格式：
yyyyMMddhhmmss

        支付金额（实收金额）        value        Number        Y        必填项
正数：销售订单
负数：退货订单
        应收金额        payAmt        Number        Y        必填项
正数：销售订单
负数：退货订单

        优惠金额        discountAmt        Number        Y        必填项
正数：销售订单
负数：退货订单
        支付银行bankcode        cardBank        String        N        非必填
        银行卡卡号        cardNumber        String        N        非必填
店铺编号        store        String        Y        必填项
长度：最小1位,最大40位
收银机编号        tillId        String        Y        必填项
长度必须为2位数字，例如：01
订单时间        time        String        Y        必填项
格式：yyyyMMddhhmmss；时区：GMT+8
（此接口仅支持接收48天内的订单）
订单总金额        totalAmt        String        Y        必填项
正数：销售订单
负数：退货订单
订单类型        type        String        Y        必填项
销售：SALE
退货：ONLINEREFUND
店铺验证密钥(登录密码)        checkCode        String        Y        必填项
店铺验证密钥(密码) 由IMPOS提供
备注        comments        String        N        非必填；长度：最大200位
会员手机号        mobile        String        N        非必填
关联原订单号        refOrderId        String        N        非必填；长度：最小6位，最大40位；
若是退货订单可以填写原订单号

来源        source        String        N        01:店铺
02:数据采集盒子
Json请求示例（如示例或截图）
Headers需填写Content-Type：application/json;charset=UTF-8（设置后返回的错误信息不会乱码）
Body请求参数示例：
{"REQUEST":{"REQUEST_DATA":{"cashierId":"20028hvgl120n0101","checkCode":"p88888888","mall":"20028","orderId":"1081983263","payList":[{"discountAmt":7.96,"payAmt":61,"paymentMethod":"OT","time":"20220405000000","value":53.04}],"store":"HVGL120N01","tillId":"01","time":"20220405105628","totalAmt":"53.04","type":"SALE"},"HRT_ATTRS":{"Partner_ID":"70000006","Api_Version":"1.0.0","App_Sub_ID":"10000133334PY","Format":"json","Time_Stamp":"2022-04-20 17:37:50:583","Api_ID":"mixc.imPOSWBJB.GLWXCJB.orderCollect","App_Token":"c861e8a4be0f41b182abdb55b986444a","App_Pub_ID":"10000133301US","Sign_Method":"md5","Sign":"491F3087452F1965020F286193239750","Sys_ID":"100001333"}}}

3.3接口响应报文信息
请求参数        参数名        类型        是否必填        说明
订单号        orderId        String        N       
参考号        refOrderId        String        N       

响应报文:
{"RETURN_DATA":
{"header":{"errcode":"0000","errmsg":"成功"},"body":{"orderId":"1103600458211214010001","refOrderId":"HSS0351001100120041010007"}},"RETURN_CODE":"INTERFACE HAS NO CODE","RETURN_DESC":"INTERFACE HAS NO DESC","RETURN_STAMP":""}

errcode说明:
0000：成功
1001：失败，不同错误“errmsg”中提示不同错误信息

4、        对接必要信息
租户在对接时，需要向商场申请“接驳信息表”、“XX项目店铺信息”获取必要的参数信息（注：UAT参数与生产参数不同）。
        店铺个性参数：
租户申接驳信息表
收银员编号（imPOS登录账号）        店铺验证密码        商场编号        收银机编号
20063km1l0309b0101        p88888888        20063        01

　        　        　        　
        公用参数：
API ID        App_Pub_ID        加密方式        版本号        描述
mixc.imPOSWBJB.GLWXCJB.orderCollect                10000133301US
        MD5        1.0.0       
签名信息如下
Partner_ID         70000006
Sys_ID         100001333
App_ID         10000133334PY
名称         imPOS测试接驳店铺
简称         imPOS测试接驳店铺
缩写         CSJBDPJB
签名密钥         0bca40d57d1f44208d787a4e0a87957d
Token         c861e8a4be0f41b182abdb55b986444a
沙箱签名密钥         b977e4a1556e465086c478c002e1e19c
沙箱Token         0e54124e205e470e9a43a40b7f104488

请问遇到什么问题了呢？请简单描述一下