# 东软云药店对接规范

# 修改记录

版本号 更改条款及内容 更改人 更改日期
2.0-xj XJ-ZZQ初始版 james.xu 2025.11.04

# 一、背景

实现东软云药店系统与药店管理系统的实时数据交互与共享,解决药店零售活动中的二次录入问题,支持订单跟踪管理,提升作业效率并节省成本。

该接口支持实时库存对接、订单对接、商品对接等功能,药店系统通过发送 HTTP 请求到东软云药店系统服务地址,完成各类交易调用。


# 二、说明

  1. 为适配不同连锁药店的管理系统,制定统一对接规范。

  2. 接口基于HTTP 协议,采用POST 请求,遵循REST API 风格

  3. 接口签名(sign)所需的appkey,需以邮件形式向平台方服务端申请,由服务端统一分配。

  4. 请求参数中的data字段需进行Base64 加密处理。


# 三、签名

每次调用 API 接口时,必须在 HTTP Request Header 中携带以下 5 个参数。

# Header 参数说明

序号 名称 类型 说明
1 appkey String 服务端分配的唯一标识
2 nonce String 随机数,长度限制 36 字符以内
3 timestamp String 时间戳(毫秒级),从 1970 年 1 月 1 日 0 点 0 分 0 秒开始计算
4 sign String 数据签名,用于接口鉴权
5 Content-Type String 固定值:application/json

# sign(数据签名)计算方法

  1. 拼接字符串:按appsecret + nonce + timestamp的顺序拼接成一个字符串。

  2. MD5 加密:对拼接后的字符串进行 MD5 加密,结果转为小写,即为 sign 值。

  3. 校验失败:若签名验证不通过,接口将返回错误信息,调用失败。


# 四、接口

# 1. 商品同步

# 接口说明

将 ERP 系统的商品信息同步到东软收费系统。

# 基本信息

  • URL:/public/syncproduct

  • 请求方式:POST

# Request 参数

序号 参数 类型 是否必填 解释
1 synctype NUMBER(2) 同步类型:1(新增)、2(更改)注:更改操作仅允许在晚上 10 点至早上 6 点期间执行
2 orgcode VARCHAR2(20) 医保定点编号,门店唯一标识
3 oldproductno VARCHAR2(20) 商品 ID(原 ERP 系统中的编号)
4 productname VARCHAR2(100) 商品名称
5 barcode VARCHAR2(100) 商品条形码
6 factoryname VARCHAR2(200) 生产企业名称
7 producttype VARCHAR2(100) 商品规格
8 unit VARCHAR2(20) 单位(数字代码,详见 “六、代码表 - 2、药品单位”)
9 approvedocno VARCHAR2(100) 药品批准文号
10 otcflag NUMBER(1) 处方药标志:0(非处方药)、1(处方药)
11 zyflag NUMBER(1) 中药标志:0(非中药)、1(中药)
12 saleprice NUMBER(16,6) 商品零售价
13 memo VARCHAR2(200) 备注信息
14 securityno VARCHAR2(20) 医保编码(医保对照使用,V1.6 版本起传国码)
15 createdate DATE 商品创建时间

# Response 示例

{
 "code": 200,
 "message": "处理成功",
 "data": null
}
1
2
3
4
5

# 请求示例

appKey: naeD7NMWlFc=
nonce: 0b5f1c1c-8cd7-42cc-9ee9-dfd5b3a952a6
timestamp: 1605603022467
sign: df34f1f6d2b4ceaedb8ad12bc3d239b9
Content-Type: application/json
1
2
3
4
5
# Body(密文)
{
 "data": "W3sKCSJzeW5jdHlwZSI6IDEsCgkib3JnY29kZSI6ICI0NzE1NDIiLAoJIm9sZHByb2R1Y3RubyI6ICIxMDAwMDIiLAoJInByb2R1Y3RuYW1lIjogIumYv+iOq+ilv+aelyIsCgkiYmFyY29kZSI6ICIxMjM0NTYiLAoJImZhY3RvcnluYW1lIjogIuWMl+S6rOiNr+S4miIsCgkicHJvZHVjdHR5cGUiOiAiMTUv55uSIiwKCSJ1bml0Ijoi55uSIiwKCSJhcHByb3ZlZG9jbm8iOiAi5Zu96I2v5YeG5a2XMTIzIiwKCSJvdGNmbGFnIjogMSwKCSJ6eWZsYWciOiAwLAoJInNhbGVwcmljZSI6IDEyLjMsCgkiY3JlYXRlZGF0ZSI6ICIyMDIwLTAzLTAyIiwKCSJtZW1vIjogIjEyMzEyMzEyMyIsCiAgICAgICAgInNlY3VyaXR5bm8iOiIyMDAwMTM5NzEwMDEiCn0sICB7Cgkic3luY3R5cGUiOiAxLAoJIm9yZ2NvZGUiOiAiNDcxNTQyIiwKCSJvbGRwcm9kdWN0bm8iOiAiMTAwMDAzIiwKCSJwcm9kdWN0bmFtZSI6ICLpmL/ojqvopb/mnpcyIiwKCSJiYXJjb2RlIjogIjEyMzQ1Njc4IiwKCSJmYWN0b3J5bmFtZSI6ICLljJfkuqzoja/kuJoiLAoJInByb2R1Y3R0eXBlIjogIjE1L+ebkiIsCgkidW5pdCI6IuebkiIsCgkiYXBwcm92ZWRvY25vIjogIuWbveiNr+WHhuWtlzEyMyIsCgkib3RjZmxhZyI6IDEsCgkienlmbGFnIjogMCwKCSJzYWxlcHJpY2UiOiAxMi41LAoJImNyZWF0ZWRhdGUiOiAiMjAyMC0wMy0wMiIsCgkibWVtbyI6ICIxMjMxMjMxMjMiLAogICAgICAgICJzZWN1cml0eW5vIjoiMjAwMDEzOTcxMDAxIgp9XQo="
}
1
2
3
# Data 明文
[
 {
     "synctype": 1,
     "orgcode": "471542",
     "oldproductno": "100002",
     "productname": "阿莫西林",
     "barcode": "123456",
     "factoryname": "北京药业",
     "producttype": "15/盒",
     "unit": 1,
     "approvedocno": "国药准字123",
     "otcflag": 1,
     "zyflag": 0,
     "saleprice": 12.3,
     "createdate": "2020-03-02",
     "memo": "123123123",
     "securityno": "200013971001"
 },
 {
     "synctype": 1,
     "orgcode": "471542",
     "oldproductno": "100003",
     "productname": "阿莫西林2",
     "barcode": "12345678",
     "factoryname": "北京药业",
     "producttype": "15/盒",
     "unit": 1,
     "approvedocno": "国药准字123",
     "otcflag": 1,
     "zyflag": 0,
     "saleprice": 12.5,
     "createdate": "2020-03-02",
     "memo": "123123123",
     "securityno": "200013971001"
 }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

# 2. 库存同步

# 接口说明

将 ERP 系统的商品库存信息同步到东软收费系统。

# 备注

  • 初始系统对接时,需同步全量库存;后续仅需同步变化库存(按医保最新需求)。

# 基本信息

  • URL:/public/syncstock

  • 请求方式:POST

# Request 参数

序号 参数 类型 是否必填 解释
1 synctype NUMBER(2) 同步类型:1(总库存)、2(变化库存)
2 orgcode VARCHAR2(20) 医保定点编号,门店唯一标识
3 oldproductno VARCHAR2(20) 商品 ID(原 ERP 系统中的编号)
4 oldproductname VARCHAR2(100) 商品名称
5 datatype NUMBER(2) 库存变动类型(入库 / 出库):0(期初入库)、1(采购入库)、2(报溢 / 盘盈入库)、3(赠予入库)、4(调拨入库)、5(其他入库)、6(采购退货出库)、7(报损 / 盘损出库)、8(赠予出库)、9(调拨出库)、10(其他出库)
6 productqty NUMBER(16,6) 商品数量:- synctype=1、datatype=0(期初入库):表示总库存数量 - synctype=2(变化库存):表示变动数量(如盘损 5 盒传 5,系统自动减库存)
7 lotno NUMBER(36) 商品批号
8 stockstatus NUMBER(2) 库存状态:1(合格)、2(不合格)注:正常情况传 1,禁止传 0
9 memo VARCHAR2(200) 调拨时必传 备注信息,调拨场景需注明原因
10 makedate VARCHAR2(20) 商品生产日期
11 invalidate VARCHAR2(20) 商品有效期
12 createdate VARCHAR2(20) 库存记录创建时间
13 purprice NUMBER(16,6) 商品进价

# Response 示例

{
 "code": 200,
 "message": "处理成功",
 "data": null
}
1
2
3
4
5

# 请求示例

# Header
appKey: naeD7NMWlFc=
nonce: 0b5f1c1c-8cd7-42cc-9ee9-dfd5b3a952a6
timestamp: 1605603022467
sign: df34f1f6d2b4ceaedb8ad12bc3d239b9
Content-Type: application/json
1
2
3
4
5
# Body(密文)
{
 "data": "W3sKCSJjcmVhdGVkYXRlIjogIjIwMjAtMDYtMjggMjA6MjA6MjAiLAogICAgICAgICJtYWtlZGF0ZSI6IjIwMjAtMDYtMjgiLAogICAgICAgICJpbnZhbGlkYXRlIjoiMjAyMC0wNi0yOCIsCgkibG90bm8iOiAiMjAyMDAxMDEiLAoJIm1lbW8iOiAiNjY2NjY2IiwKCSJvbGRwcm9kdWN0bmFtZSI6ICLpmL/ojqvopb/mnpczIiwKCSJvbGRwcm9kdWN0bm8iOiAiMTAwMDAzIiwKCSJvcmdjb2RlIjogIjQ3MTU0MiIsCgkicHJvZHVjdHF0eSI6IDE1MDAsCgkicHVycHJpY2UiOiA1LAoJInN0b2Nrc3RhdHVzIjogMSwKCSJzeW5jdHlwZSI6IDEKfSwgewoJImNyZWF0ZWRhdGUiOiAiMjAyMC0wNi0yOCAyMDoyMDoyMCIsCgkibG90bm8iOiAiMjAyMDAyMDIiLAogICAgICAgICJtYWtlZGF0ZSI6IjIwMjAtMDYtMjgiLAogICAgICAgICJpbnZhbGlkYXRlIjoiMjAyMi0wNi0yOCIsCgkibWVtbyI6ICI4ODg4ODg4OCIsCgkib2xkcHJvZHVjdG5hbWUiOiAi6Zi/6I6r6KW/5p6XNCIsCgkib2xkcHJvZHVjdG5vIjogIjEwMDAwMyIsCgkib3JnY29kZSI6ICI0NzE1NDIiLAoJInByb2R1Y3RxdHkiOiAxNTAwLAoJInB1cnByaWNlIjogMywKCSJzdG9ja3N0YXR1cyI6IDEsCgkic3luY3R5cGUiOiAxCn1d"
}
1
2
3
# Data 明文
[
 {
     "createdate": "2020-06-28 20:20:20",
     "makedate": "2020-06-28",
     "invalidate": "2022-06-28",
     "lotno": "20200101",
     "memo": "666666",
     "oldproductname": "阿莫西林3",
     "oldproductno": "100003",
     "orgcode": "471542",
     "productqty": 1500,
     "purprice": 5,
     "stockstatus": 1,
     "synctype": 1
 },
 {
     "createdate": "2020-06-28 20:20:20",
     "lotno": "20200202",
     "makedate": "2020-06-28",
     "invalidate": "2022-06-28",
     "memo": "88888888",
     "oldproductname": "阿莫西林4",
     "oldproductno": "100004",
     "orgcode": "471542",
     "productqty": 1500,
     "purprice": 3,
     "stockstatus": 1,
     "synctype": 1
 }

]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# 3. 订单同步

# 接口说明

将 ERP 系统的零售订单信息同步到东软云药店收费系统(销售场景)。

# 基本信息

  • URL:/public/syncorder

  • 请求方式:POST

# Request 参数(订单主信息)

序号 参数 类型 是否必填 解释
1 orderno VARCHAR2(20) 订单总单 ID,唯一流水号
2 orgcode VARCHAR2(20) 医保定点编号,门店唯一标识(V1.6 版本起传门店新国码)
3 createdate DATE 订单录入时间
4 realmoney NUMBER(16,6) 订单成交总金额(需与细单金额合计一致)
5 memo VARCHAR2(200) 订单备注信息 (好药师)
6 dtllines NUMBER(3) 订单细目笔数(需与细单列表条数一致)
7 saleFlag VARCHAR2(4) 订单类型标志,默认填 0 或不填 暂时没存
8 originalOrderno VARCHAR2(20) 原订单号,暂时传空
9 respUrl VARCHAR2(100) 回调地址

# 4.3.4 Request 参数(订单细单信息:orderdetailList)

序号 参数 类型 是否必填 解释
1 orderdetailno VARCHAR2(20) 订单细单 ID,唯一流水号
2 oldproductno VARCHAR2(20) 商品 ID(原 ERP 系统中的编号)
3 oldproductname VARCHAR2(100) 商品名称
4 tax NUMBER(4,2) 商品税率
5 productqty NUMBER(16,6) 商品销售数量
6 realprice NUMBER(16,6) 商品实际销售单价
7 realmoney NUMBER(16,6) 商品实际销售金额(需与单价 × 数量一致)
8 lotno VARCHAR2(100) 商品批号(启用库存管理时必传)
9 feetype VARCHAR2(4) 医保费用类别(详见 “六、代码表 - 1、费用类别”)
10 securityno VARCHAR2(20) 医保编码
11 securityflag VARCHAR2(20) 医保标志
12 sourcecode VARCHAR2(100) 溯源码 "8111111,8222222"

# Response 示例

{
 "code": 200,
 "message": "处理成功",
 "data": null
}
1
2
3
4
5

# 请求示例

# Header
appKey: naeD7NMWlFc=
nonce: 0b5f1c1c-8cd7-42cc-9ee9-dfd5b3a952a6
timestamp: 1605603022467
sign: df34f1f6d2b4ceaedb8ad12bc3d239b9
Content-Type: application/json
1
2
3
4
5
# Body(密文)
{
 "data": "eyJvcmRlcm5vIjoiWjEwMTEyMDI1MDUxNTA4MDUiLCJvcmdjb2RlIjoiUDY1MDEwNDAxNDExIiwiY3JlYXRlZGF0ZSI6IjIwMjUtMDUtMTUgMTU6MTQ6MzYiLCJyZWFsbW9uZXkiOjMwLCJtZW1vIjoiIiwiZHRsbGluZXMiOjIsInNhbGVGbGFnIjoiMCIsIm9yaWdpbmFsT3JkZXJubyI6IiIsInJlc3BVcmwiOiJodHRwOi8vMTI3LjAuMC4xOjg4ODgiLCJvcmRlcmRldGFpbExpc3QiOlt7Im9yZGVyZGV0YWlsbm8iOiJaMTAxMTIwMjUwNTE1MDgwNTAwMSIsIm9sZHByb2R1Y3RubyI6IjMiLCJvbGRwcm9kdWN0bmFtZSI6IuiOsuiKsea4heeYn+iDtuWbiiIsInRheCI6MTMsInByb2R1Y3RxdHkiOjEsInJlYWxwcmljZSI6MTIsInJlYWxtb25leSI6MTIsImxvdG5vIjoiMjkyNDExMDQiLCJmZWV0eXBlIjoiMTEiLCJpdGVtY2xhc3NpZmljYXRpb24iOiIxIiwic2VjdXJpdHlubyI6IlhOMDJCRUY2OTZCMDAyMDEwMTAzMzc3Iiwic2VjdXJpdHlmbGFnIjoiMSIsInNvdXJjZWNvZGUiOiIxMTExMTExMTExMTEifSx7Im9yZGVyZGV0YWlsbm8iOiJaMTAxMTIwMjUwNTE1MDgwNTAwMiIsIm9sZHByb2R1Y3RubyI6IjEiLCJvbGRwcm9kdWN0bmFtZSI6IumYv+iOq+ilv+ael+iDtuWbiiIsInRheCI6MTMsInByb2R1Y3RxdHkiOjEsInJlYWxwcmljZSI6MTgsInJlYWxtb25leSI6MTgsImxvdG5vIjoiODg4ODgiLCJmZWV0eXBlIjoiMTEiLCJpdGVtY2xhc3NpZmljYXRpb24iOiIxIiwic2VjdXJpdHlubyI6IlhOMDJCRUY2OTZCMDAyMDEwMTAzMzc3Iiwic2VjdXJpdHlmbGFnIjoiMSIsInNvdXJjZWNvZGUiOiIyMjIyMjIyMjIyMjIifV19"
}
1
2
3
# Data 明文
{
  "orderno": "Z1011202505150805",
  "orgcode": "P65010401411",
  "createdate": "2025-05-15 15:14:36",
  "realmoney": 30,
  "memo": "好药师",
  "dtllines": 2,
  "saleFlag": "0",
  "originalOrderno": "",
  "respUrl": "http://127.0.0.1:8888",
  "orderdetailList": [
    {
      "orderdetailno": "Z1011202505150805001",
      "oldproductno": "3",
      "oldproductname": "莲花清瘟胶囊",
      "tax": 13,
      "productqty": 1,
      "realprice": 12,
      "realmoney": 12,
      "lotno": "29241104",
      "feetype": "11",
      "securityno": "XN02BEF696B002010103377",
      "securityflag": "1",
      "sourcecode": "111111111111"
    },
    {
      "orderdetailno": "Z1011202505150805002",
      "oldproductno": "1",
      "oldproductname": "阿莫西林胶囊",
      "tax": 13,
      "productqty": 1,
      "realprice": 18,
      "realmoney": 18,
      "lotno": "88888",
      "feetype": "11",
      "securityno": "XN02BEF696B002010103377",
      "securityflag": "1",
      "sourcecode": "222222222222"
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

# 4 支付回调

# 接口说明

接收东软云药店收费系统的支付结果回调,同步零售订单支付状态(支付场景)。

  • URL:/pay/callback

  • 请求方式:POST

# 支付回调主信息

序号 参数名 类型 是否必填 解释
2 code String 响应状态码编码规则需与对接方约定
3 message String 状态描述(成功 / 失败原因,如 "处理成功"" 订单号不存在 ")
4 ordeno String 订单编号(外部系统流水号),关联外部与内部订单
5 orderType String 回调单据类型 1普通结算单 2处方流转结算单
6 retailId String 零售总单 ID
7 rtpRetail ViewRtpRetail 零售总单
8 rtpRetailDetail List<ViewRtpRetailDetail> 零售细单列表

# "rtpRetail" 节点

编号 参数名 类型 是否必填 解释
1 retailid Long 零售总单 ID
2 retailcode String 零售总单号
3 oldretailcode String 退货原总单ID
4 oldretailid Long 退货总单编号
5 comid Long 公司ID
6 shopid Long 门店ID
7 shopcode String 门店编码
8 shopname String 门店名称
9 createdate Date 录入时间
10 useday Date 逻辑日
11 discmoney Double 折扣金额
12 realmoney Double 成交金额
13 cashierid Long 收款员ID
14 cashiername String 收款员
15 retailtype Integer 销售类型
16 recmoney Double 收款额
17 changemoney Double 找零
18 memo String 结算备注
19 dtllines Integer 细目笔数
20 ypdocid Long 饮片药方ID
21 lossmoney Double 抹零金额
22 paystatus Integer 缴款状态
23 bagnum Double 药方付数
24 mcardno String 社会保障卡号
25 ext81 String 经办机构
26 ext2 Double 统筹支付
27 ext7 Double 账户支付
28 ext8 Double 现金支付
29 ext21 String 医疗类别
30 diseaseno String 诊断疾病编码
31 diseasename String 诊断疾病名称
32 prescriptionid Long 处方ID
33 prescriptionno String 处方笺号
34 prescriptiondate Date 处方日期
35 institution String 医疗机构
36 fsource String 处方来源
37 patientname String 患者姓名
38 idcard String 身份证号
39 doctorname String 医生姓名
40 checkdoctor String 复核医生姓名
41 filepath String 处方图片

# "rtpRetailDetail" 节点

< 暂时不用 >

参数名 类型 是否必填 解释
retaildetailid Long 零售细单 ID
retailid Long 零售总单 ID
retailcode String 零售总单编号
retaildetailcode String 零售细单编号
createdate Date 细单录入时间
useday Date 业务核算逻辑日
productid Long 商品 ID,关联商品基础信息
productcode String 商品编码,业务层商品唯一标识
productname String 商品名称
producttype String 商品规格
unit String 商品单位(如盒、瓶)
areaname String 商品产地
factoryname String 生产企业名称
approvedocno String 商品批准文号
barcode String 商品条形码
registdocno String 商品注册证号
lotno String 商品批号(启用库存管理时必传)
tax Double 商品税率
unitprice Double 商品零售价
productqty Double 商品销售数量
totalmoney Double 商品原价总金额(零售价 × 数量)
discmoney Double 商品折扣金额

# 五、响应码

代码 描述 详细解释
200 处理成功 接口调用成功,业务逻辑执行完成
404 未找到 服务器无法找到请求的接口地址
500 服务内部错误 服务器端出现内部逻辑错误,建议稍后重试
1001 appsecret 错误 appkey 与对应的 appsecret 不匹配
1002 签名错误 客户端计算的 sign 值与服务器端校验结果不一致
2000 订单重复 订单编号已存在,避免重复同步
2001 未匹配到该药品 商品信息未在系统中匹配到
2002 未匹配到医保药品 医保编码对应的药品未匹配到
2003 细单条数不一致 订单总单中的 dtllines 字段值与实际细单列表条数不相等
2004 对应商品未找到 订单细单中的商品 ID 未匹配到系统中的商品
2005 金额不一致 订单总单金额与细单金额合计不相等
2006 细单金额计算错误 细单中商品单价 × 数量的结果与细单金额不一致
2007 医保机构未找到 orgcode 对应的医保机构信息未找到
2008 参数错误 请求参数缺失、格式错误或不符合业务规则

# 六、代码表

# 1. 费用类别

类别代码 类别名称 说明 类别代码 类别名称 说明
11 西药费 31 治疗费
12 中成药费 32 特殊治疗费
13 中草药费 33 护理费
21 检查费 34 床位费
22 特殊检查费 35 体检费
23 输氧费 36 一次性材料费
24 手术费 91 其他费用
25 化验费 92 挂号费
26 输血费
27 诊察费
28 统筹基金单独支付的诊疗项目

# 2. 药品单位

代码 单位名称 代码 单位名称 代码 单位名称
1 20 39
2 21 40
3 22 41 中盒
4 23 42
5 24 43 中包
6 25 44
7 26 45
8 27 46
9 28 千克 47
10 29 48
11 30 49
12 31 50
13 32 51
14 33 52
15 34 53 G
16 35 54 10G
17 36 55 100G
18 37 56 KG
19 38 57