拉卡拉新零售学堂

Appearance

开发规范 ​

基本信息 ​

所有的API请求使用HTTPS，并使用 JSON 作为消息体的数据交换格式，设置HTTP头部：

Content-Type: application/json
Accept: application/json
Content-Type: application/json
Accept: application/json

图片上传API除外。

参数兼容性 ​

  • 请求是否成功，与请求参数的顺序无关
  • 请求是否成功，与请求JSON中的键值对出现的顺序无关
  • 处理应答时，不应假设应答JSON中的键值对出现的顺序
  • 新的API版本可能在请求或应答中加入新的参数或者JSON的键值对
  • 新的API版本不会去除请求和应答中已经存在的必填参数或者JSON的键值对
  • 当请求或应答中的JSON键值对的值为空（null）时，可以省略

字符集 ​

仅支持UTF-8字符编码的一个子集：使用一至三个字节编码的字符。不支持Unicode辅助平面中的四至六字节编码的字符。

日期格式 ​

所有的日期对象，使用 ISO 8601 所定义的格式。示例：

yyyy-MM-DDTHH:mm:ss.SSSZ
yyyy-MM-DDTHH:mm:ssZ
yyyy-MM-DDTHH:mm:ss.SSS+08:00
yyyy-MM-DDTHH:mm:ss+08:00
yyyy-MM-DDTHH:mm:ss.SSSZ
yyyy-MM-DDTHH:mm:ssZ
yyyy-MM-DDTHH:mm:ss.SSS+08:00
yyyy-MM-DDTHH:mm:ss+08:00

请求的唯一标识 ​

每个接收到的请求分配了一个唯一标识，请求的唯一标识包含在应答的报文中的sid字段中。当需要拉卡拉云超帮助时，请提供请求的唯一标识，以便我们更快的定位到具体的请求。

错误信息 ​

使用HTTP状态码来表示请求处理的结果。

  • 处理成功的请求，如果有应答的消息体将返回200，
  • 若业务系统处理出现异常或不符合业务预期错误返回203，请求方基于应答报文中的code和message确定具体错误。
  • 请求处理时发生了拉卡拉云超侧的服务系统错误，将返回500/501/503的状态码。这种情况比较少见。

错误码和错误提示 ​

当请求处理失败时，除了HTTP状态码表示错误之外，API将在消息体返回错误相应说明具体的错误原因。

  • _code： 详细错误码
  • _message：错误描述，使用易理解的文字表示错误的原因。

User Agent ​

HTTP协议要求发起请求的客户端在每一次请求中都使用HTTP头 User-Agent来标识自己。建议调用方选用以下两种方式的一种：

  1. 使用HTTP客户端默认的 User-Agent。
  2. 遵循HTTP协议，使用自身系统和应用的名称和版本等信息，组成自己独有的User-Agent。 拉卡拉云超可能会拒绝处理无User-Agent 的请求。

签名规则 ​

交互方式 ​

拉卡拉云超API均采用post + json 格式进行交互，为确保双方交易身份需对交互body字符串作RSA签名，并存放到header中。请求方和拉卡拉云超分别生产RSA公私钥并互换公钥，并自身确保私钥存储安全。

调用方 -> 拉卡拉： 请求签名放到header中的 X-Client-Sign
拉卡拉 -> 调用方： 响应签名放到header中的 X-Server-Sign
调用方 -> 拉卡拉： 请求签名放到header中的 X-Client-Sign
拉卡拉 -> 调用方： 响应签名放到header中的 X-Server-Sign

RSA公私钥 ​

以linux系统为例

Java
# 进入OpenSSL程序
$ openssl
 # 生成私钥
 OpenSSL> genrsa -out rsa_private_key.pem 2048
 # Java开发者需要将私钥转换成PKCS8格式
 OpenSSL> pkcs8 -topk8 -inform PEM -in rsa_private_key.pem -outform PEM -nocrypt
 # 生成公钥
 OpenSSL> rsa -in rsa_private_key.pem -pubout -out rsa_public_key.pem
 # 退出OpenSSL程序
 OpenSSL> exit
# 进入OpenSSL程序
$ openssl
 # 生成私钥
 OpenSSL> genrsa -out rsa_private_key.pem 2048
 # Java开发者需要将私钥转换成PKCS8格式
 OpenSSL> pkcs8 -topk8 -inform PEM -in rsa_private_key.pem -outform PEM -nocrypt
 # 生成公钥
 OpenSSL> rsa -in rsa_private_key.pem -pubout -out rsa_public_key.pem
 # 退出OpenSSL程序
 OpenSSL> exit
  • 密钥对样例
-----BEGIN PRIVATE KEY-----
MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQDelpOuuEVLcaY7
gP+bD6VP+oOzOt8XY4ZqPJI6RoqO54RTLf8M36nGMClErj+V9yaTvNeHufWjSTaz
VMKukq0WG9JnhYp31B+zaHgjeYzk2h2CSy4w54qwmR8xB9MjVQf/9DyXJNR/hdyW
xGKMK+ti/mb7n72Fh+roML/AkTz2vXj9OawooGKMED28QFfbdUfE0XmR8St+KU9c
wvrv8pXLE1zIubWCbUUo9wdtdZhUvBN1GFimEv7l4HILW6xN5hbtGhp3ax9JB8Ag
YmaoDkzA+RXaApJP1LMOwOSg32ZXPfW/DbTMocX6qCiH1CUBP0/DaHU6tyQB6YVZ
6OlCGr+HAgMBAAECggEBAJIHz9Ps6OlaImkfdJJSbW5POGA522sIzIKeQoEhDn46
vcGkh5P2mPeBWVHJz8WfZBvA5NYS1mjN+6kjjqXhbNT4Y82u+u0qqbGWdFsxv5HU
109H64ICJic+DgyoyYiAnML7hVTTwOX4+IOhS9YSaleD+CRU5I3aYe77LJI1tv1Y
j0HAw6bjQYwhM50csKsmqHtl2bzI2K8HtT+0dzC6U910+yTIGyzZalusgtW6/qLl
1AbEZho0O+KOQr6JHwFg4ffXBsEym8lj5JiqAMYiDihtofsOxRkL+zU3Z3zaEWgo
uZSxm39Fj0thK+a82HWxIzv8EMu2ZH28i5CFoIzHjcECgYEA/ybJjfkl/e02OzXH
qTMmmMzAAIXAEVg8HV9ieNi+cfcSyVDoV7w6GtYldVf2BHYZl86Nats9xwdW7Pqb
d9KM3sJGS3OfZDYjsamyICA8WwC2GBWbCpuGOJGnDgGz4x8UEZbt7GVi348RFO0B
PzAgIrRa6VhkgQfd+b0+f3h7Q6kCgYEA31QRcLXnLsabtVLDw5fCVkPuxBOhgXaj
IBVfnBc+BSd5Dvfbp7e9bEOVQM9TNLZ6VdnK5NiDZbLkqBIJpRf23M3d8FsrUrAC
DZRAtkZzoW2Y1Y+39NTC9jr4wOZe/Vv4cEJBXMvvJfTK1VmQJVHKgQcmbf8AlrXs
uDCCZUu6568CgYBJD4Q7YRJd6aTTw4yOiJUOv+Jiw+nBjbB5AK0jyXyPCZ6Zgs9l
AALrWFKVjUBm+qJNc9nOtUS1Twa3CPOnleS8jIiwZkVH3rDN2Lemt1RRAp0hvF4O
5YXDgQGC4z3tVSLb/onWXRm4xjCv+0WWIGOzTE2T77mnsOcA8g2JVqiFMQKBgQCa
oTnGIZzlbUyomprDVdOQKU8r4i/EVSGTeFkP2aPuq6sNax5inT0BtjWkfyisaeCA
iuEJ3MP16YyatoqJDfO2ZLBT2LxBb26sekboLhWn4xucWvtTAPHQzXopDhkdMc3t
5GIfX3DBhiHe4TmGLYCaIBpCtPpyX5p82dGfU3UhLwKBgQCWaGE8yTFDTAExbpHC
i3AVkldo0/qe/VaiH2B3sMZv5YpTmqngpdvLaF4ti+f4fCg+udil0sVSGC3zBF5v
FK9mN+jTUGWBhi/Ruq8dxsclUQozYKlRocY7woGjuihcWR4rx5F2H95b7Y3tSzoO
TCfvjHGun2ys9BHyPr+x1wNCnQ==
-----END PRIVATE KEY-----
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3paTrrhFS3GmO4D/mw+l
T/qDszrfF2OGajySOkaKjueEUy3/DN+pxjApRK4/lfcmk7zXh7n1o0k2s1TCrpKt
FhvSZ4WKd9Qfs2h4I3mM5NodgksuMOeKsJkfMQfTI1UH//Q8lyTUf4XclsRijCvr
Yv5m+5+9hYfq6DC/wJE89r14/TmsKKBijBA9vEBX23VHxNF5kfErfilPXML67/KV
yxNcyLm1gm1FKPcHbXWYVLwTdRhYphL+5eByC1usTeYW7Road2sfSQfAIGJmqA5M
wPkV2gKST9SzDsDkoN9mVz31vw20zKHF+qgoh9QlAT9Pw2h1OrckAemFWejpQhq/
hwIDAQAB
-----END PUBLIC KEY-----
-----BEGIN PRIVATE KEY-----
MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQDelpOuuEVLcaY7
gP+bD6VP+oOzOt8XY4ZqPJI6RoqO54RTLf8M36nGMClErj+V9yaTvNeHufWjSTaz
VMKukq0WG9JnhYp31B+zaHgjeYzk2h2CSy4w54qwmR8xB9MjVQf/9DyXJNR/hdyW
xGKMK+ti/mb7n72Fh+roML/AkTz2vXj9OawooGKMED28QFfbdUfE0XmR8St+KU9c
wvrv8pXLE1zIubWCbUUo9wdtdZhUvBN1GFimEv7l4HILW6xN5hbtGhp3ax9JB8Ag
YmaoDkzA+RXaApJP1LMOwOSg32ZXPfW/DbTMocX6qCiH1CUBP0/DaHU6tyQB6YVZ
6OlCGr+HAgMBAAECggEBAJIHz9Ps6OlaImkfdJJSbW5POGA522sIzIKeQoEhDn46
vcGkh5P2mPeBWVHJz8WfZBvA5NYS1mjN+6kjjqXhbNT4Y82u+u0qqbGWdFsxv5HU
109H64ICJic+DgyoyYiAnML7hVTTwOX4+IOhS9YSaleD+CRU5I3aYe77LJI1tv1Y
j0HAw6bjQYwhM50csKsmqHtl2bzI2K8HtT+0dzC6U910+yTIGyzZalusgtW6/qLl
1AbEZho0O+KOQr6JHwFg4ffXBsEym8lj5JiqAMYiDihtofsOxRkL+zU3Z3zaEWgo
uZSxm39Fj0thK+a82HWxIzv8EMu2ZH28i5CFoIzHjcECgYEA/ybJjfkl/e02OzXH
qTMmmMzAAIXAEVg8HV9ieNi+cfcSyVDoV7w6GtYldVf2BHYZl86Nats9xwdW7Pqb
d9KM3sJGS3OfZDYjsamyICA8WwC2GBWbCpuGOJGnDgGz4x8UEZbt7GVi348RFO0B
PzAgIrRa6VhkgQfd+b0+f3h7Q6kCgYEA31QRcLXnLsabtVLDw5fCVkPuxBOhgXaj
IBVfnBc+BSd5Dvfbp7e9bEOVQM9TNLZ6VdnK5NiDZbLkqBIJpRf23M3d8FsrUrAC
DZRAtkZzoW2Y1Y+39NTC9jr4wOZe/Vv4cEJBXMvvJfTK1VmQJVHKgQcmbf8AlrXs
uDCCZUu6568CgYBJD4Q7YRJd6aTTw4yOiJUOv+Jiw+nBjbB5AK0jyXyPCZ6Zgs9l
AALrWFKVjUBm+qJNc9nOtUS1Twa3CPOnleS8jIiwZkVH3rDN2Lemt1RRAp0hvF4O
5YXDgQGC4z3tVSLb/onWXRm4xjCv+0WWIGOzTE2T77mnsOcA8g2JVqiFMQKBgQCa
oTnGIZzlbUyomprDVdOQKU8r4i/EVSGTeFkP2aPuq6sNax5inT0BtjWkfyisaeCA
iuEJ3MP16YyatoqJDfO2ZLBT2LxBb26sekboLhWn4xucWvtTAPHQzXopDhkdMc3t
5GIfX3DBhiHe4TmGLYCaIBpCtPpyX5p82dGfU3UhLwKBgQCWaGE8yTFDTAExbpHC
i3AVkldo0/qe/VaiH2B3sMZv5YpTmqngpdvLaF4ti+f4fCg+udil0sVSGC3zBF5v
FK9mN+jTUGWBhi/Ruq8dxsclUQozYKlRocY7woGjuihcWR4rx5F2H95b7Y3tSzoO
TCfvjHGun2ys9BHyPr+x1wNCnQ==
-----END PRIVATE KEY-----
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3paTrrhFS3GmO4D/mw+l
T/qDszrfF2OGajySOkaKjueEUy3/DN+pxjApRK4/lfcmk7zXh7n1o0k2s1TCrpKt
FhvSZ4WKd9Qfs2h4I3mM5NodgksuMOeKsJkfMQfTI1UH//Q8lyTUf4XclsRijCvr
Yv5m+5+9hYfq6DC/wJE89r14/TmsKKBijBA9vEBX23VHxNF5kfErfilPXML67/KV
yxNcyLm1gm1FKPcHbXWYVLwTdRhYphL+5eByC1usTeYW7Road2sfSQfAIGJmqA5M
wPkV2gKST9SzDsDkoN9mVz31vw20zKHF+qgoh9QlAT9Pw2h1OrckAemFWejpQhq/
hwIDAQAB
-----END PUBLIC KEY-----

签名样例 ​

假设请求json内容如下，

Java
{"accessId":"THIRD","timestamp":1629955213000,"sid":"abc123","type":1}
{"accessId":"THIRD","timestamp":1629955213000,"sid":"abc123","type":1}

RSA (SHA1withRSA)加密并做BASE64编码后结果

Java
fvBaxjptLx43Md8al6IySCYpvOV6Ivz/U7EiFTW0HNDnJCrFkT0QKuVuS5X/7fW0LtJbzAlT75oskCZDr491+/Arl7Nx9VkzRQtz9YViOz70vve+HlYtf4xKFO3iJpfAH2ng9gFZK5AMVdHEYeC9R2tuyZBL5itTxDVwWWvcTKDYyM1x51iG5BqGvgaygGILBrSK9d3cTtLigLo9qdlWHEcq4/7zxTHgpx+rPNfF9zU4JuNClJccVDBuasr1gYFt7AplQjOqxc+x0ZAuA7Eim8/j14zfI7hWkMOhg7S6qbZisyZTbyAVR55NSF7k+YASaP/L3YIabZLdx1MSLjryZg==
fvBaxjptLx43Md8al6IySCYpvOV6Ivz/U7EiFTW0HNDnJCrFkT0QKuVuS5X/7fW0LtJbzAlT75oskCZDr491+/Arl7Nx9VkzRQtz9YViOz70vve+HlYtf4xKFO3iJpfAH2ng9gFZK5AMVdHEYeC9R2tuyZBL5itTxDVwWWvcTKDYyM1x51iG5BqGvgaygGILBrSK9d3cTtLigLo9qdlWHEcq4/7zxTHgpx+rPNfF9zU4JuNClJccVDBuasr1gYFt7AplQjOqxc+x0ZAuA7Eim8/j14zfI7hWkMOhg7S6qbZisyZTbyAVR55NSF7k+YASaP/L3YIabZLdx1MSLjryZg==

CURL请求样例

curl -X 'POST' 'https://xxx.lakala.com/b2b-cps-server/abc' -H 'accept: */*' -H 'Content-Type: application/json' -H 'X-Client-Sign: fvBaxjptLx43Md8al6IySCYpvOV6Ivz/U7EiFTW0HNDnJCrFkT0QKuVuS5X/7fW0LtJbzAlT75oskCZDr491+/Arl7Nx9VkzRQtz9YViOz70vve+HlYtf4xKFO3iJpfAH2ng9gFZK5AMVdHEYeC9R2tuyZBL5itTxDVwWWvcTKDYyM1x51iG5BqGvgaygGILBrSK9d3cTtLigLo9qdlWHEcq4/7zxTHgpx+rPNfF9zU4JuNClJccVDBuasr1gYFt7AplQjOqxc+x0ZAuA7Eim8/j14zfI7hWkMOhg7S6qbZisyZTbyAVR55NSF7k+YASaP/L3YIabZLdx1MSLjryZg==' -d '{"accessId":"THIRD","timestamp":1629955213000,"sid":"abc123","type":1}'
curl -X 'POST' 'https://xxx.lakala.com/b2b-cps-server/abc' -H 'accept: */*' -H 'Content-Type: application/json' -H 'X-Client-Sign: fvBaxjptLx43Md8al6IySCYpvOV6Ivz/U7EiFTW0HNDnJCrFkT0QKuVuS5X/7fW0LtJbzAlT75oskCZDr491+/Arl7Nx9VkzRQtz9YViOz70vve+HlYtf4xKFO3iJpfAH2ng9gFZK5AMVdHEYeC9R2tuyZBL5itTxDVwWWvcTKDYyM1x51iG5BqGvgaygGILBrSK9d3cTtLigLo9qdlWHEcq4/7zxTHgpx+rPNfF9zU4JuNClJccVDBuasr1gYFt7AplQjOqxc+x0ZAuA7Eim8/j14zfI7hWkMOhg7S6qbZisyZTbyAVR55NSF7k+YASaP/L3YIabZLdx1MSLjryZg==' -d '{"accessId":"THIRD","timestamp":1629955213000,"sid":"abc123","type":1}'

接入地址 ​

环境地址
测试https://fbbc.wsmsd.cn/

拉卡拉新零售文档

© 2023-至今 拉卡拉云超科技有限公司 版权所有