{ "openapi": "3.0.3", "info": { "title": "新开普一卡通 Windows 程序对接接口", "version": "1.0.0", "description": "Windows 一卡通终端程序调用智慧餐厅 Linux 服务端的三个接口。厂商读卡器、Change DLL、PSAM 和校园卡中心扣款接口不在本文档范围内。" }, "servers": [ { "url": "https://xxx.com", "description": "实际地址由部署环境提供" } ], "paths": { "/api/oneCardTerminal/acquire": { "post": { "summary": "接口 B：获取待结算订单", "operationId": "oneCardTerminalAcquire", "tags": [ "外部接口/三方调用康比特/新开普一卡通" ], "x-apifox-folder": "外部接口/三方调用康比特/新开普一卡通", "x-apifox-status": "developing", "description": "# 接口 B：获取待结算订单\n\n## 1. 接口概述\n\nWindows 程序先调用一卡通寻卡接口取得有符号32位整数 `uid`，再调用读卡接口取得成功响应中的完整 `data`。本接口将 `uid` 与读卡 `data` 中的全部字段展开后，以顶层平铺参数提交给智慧餐厅，智慧餐厅据此定位人员并查询待刷卡结算订单，返回订单号和订单金额。\n\n读卡接口外层的 `code`、`message` 不需要传入本接口，也不传 `data` 对象本身；只将 `data` 内的全部字段展开到请求体顶层。字段名称、大小写和数值必须保持新开普读卡结果原样，不进行重命名或金额换算。\n\n## 2. 接口信息\n\n- **接口地址**：`https://xxx.com/api/oneCardTerminal/acquire`\n- **请求方法**：POST\n- **Content-Type**：`application/x-www-form-urlencoded`\n- **接口版本**：v1.0\n\n## 3. 请求头（Header）\n\n## 4. 请求参数（Body）\n\n| 参数名 | 类型 | 是否必填 | 描述 | 示例值 |\n| --- | --- | --- | --- | --- |\n| uid | Integer | 是 | 寻卡接口返回的原始 uid，为有符号32位整数；`-1845026871` 按无符号32位解释后对应十六进制 UID `92071FC9` | -1845026871 |\n| cardClass | Integer | 是 | 卡类别，厂商原始字段 | 8 |\n| customerID | Integer | 是 | 一卡通人员账号 | 29373 |\n| cardNO | Integer | 是 | 一卡通业务卡号 | 1705827 |\n| cardSN | Integer | 是 | 持卡序号 | 2 |\n| status | Integer | 是 | 卡状态原始值，状态含义按新开普 SDK 解释 | 241 |\n| subType | Integer | 是 | 补助钱包类型原始值 | 0 |\n| ze | Integer | 是 | 新开普读卡结果中的 ze 原始值，不在 Windows 端换算 | 66464 |\n| ye | Integer | 是 | 主钱包余额原始值，不在 Windows 端换算 | 211 |\n| opCount | Integer | 是 | 主钱包消费计数 | 38 |\n| subYe | Integer | 是 | 补助钱包余额原始值 | 0 |\n| subCount | Integer | 是 | 补助钱包消费计数 | 0 |\n| cardASN | String | 是 | 卡应用序列号 | AA030000026D60992AB9 |\n\n请求示例：\n\n```json\n{\n \"uid\": -1845026871,\n \"cardClass\": 8,\n \"customerID\": 29373,\n \"cardNO\": 1705827,\n \"cardSN\": 2,\n \"status\": 241,\n \"subType\": 0,\n \"ze\": 66464,\n \"ye\": 211,\n \"opCount\": 38,\n \"subYe\": 0,\n \"subCount\": 0,\n \"cardASN\": \"AA030000026D60992AB9\"\n}\n```\n\n## 5. 响应格式\n\n**获取待结算订单成功响应示例**\n\n```json\n{\n \"code\": 0,\n \"message\": \"success\",\n \"data\": {\n \"order_no\": \"260815120000001\",\n \"amount\": 1234\n },\n \"trace_id\": \"6a671d7d5539d\"\n}\n```\n\n**未找到待结算订单响应示例**\n\n```json\n{\n \"code\": 1,\n \"message\": \"未找到待刷卡结算订单\",\n \"data\": [],\n \"trace_id\": \"6a671d7d5539d\"\n}\n```\n\n只有 `code=0` 时才能使用返回的订单号和订单金额继续进行一卡通扣款，扣款金额必须以 `data.amount` 为准。\n\n## 6. 状态码说明\n\n| code | 描述 | Windows处理方式 |\n| --- | --- | --- |\n| 0 | 获取待结算订单成功 | 使用返回的 order_no 和 amount 继续扣款 |\n| 1 | 未找到卡片对应人员或待结算订单 | 不发起扣款，显示 message |\n\n## 7. 响应字段说明\n\n| 字段名 | 类型 | 描述 |\n| --- | --- | --- |\n| code | Integer | 接口处理结果：0成功、1失败 |\n| message | String | 接口处理消息或失败原因 |\n| data | Object / Array | 成功时为订单对象，失败时为空数组 |\n| data.order_no | String | 智慧餐厅待结算订单号 |\n| data.amount | Integer | 待结算订单金额，单位分；由智慧餐厅数据库中的元乘以100转换 |\n| trace_id | String | 本次请求链路标识，由系统通用返回方法生成 |\n\n## 8. trace_id 说明\n\n本接口通过系统通用返回方法在响应顶层返回 `trace_id`。问题排查时请优先提供 `trace_id`，并补充接口调用时间、`uid`、响应 `code`、`message`；完整卡片信息应脱敏后提供。", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/AcquireRequest" }, "example": { "uid": -1845026871, "cardClass": 8, "customerID": 29373, "cardNO": 1705827, "cardSN": 2, "status": 241, "subType": 0, "ze": 66464, "ye": 211, "opCount": 38, "subYe": 0, "subCount": 0, "cardASN": "AA030000026D60992AB9" } } } }, "responses": { "200": { "description": "接口业务响应，成功时data仅返回订单号和订单金额", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquireResponse" }, "examples": { "success": { "summary": "获取待结算订单成功", "value": { "code": 0, "message": "success", "data": { "order_no": "260815120000001", "amount": 1234 }, "trace_id": "6a671d7d5539d" } }, "notFound": { "summary": "未找到待结算订单", "value": { "code": 1, "message": "未找到待刷卡结算订单", "data": [], "trace_id": "6a671d7d5539d" } } } } } } } } } }, "components": { "schemas": { "AcquireRequest": { "type": "object", "required": [ "uid", "cardClass", "customerID", "cardNO", "cardSN", "status", "subType", "ze", "ye", "opCount", "subYe", "subCount", "cardASN" ], "properties": { "uid": { "type": "integer", "format": "int32", "description": "寻卡接口返回的原始uid，为有符号32位整数；-1845026871按无符号32位解释后对应十六进制UID 92071FC9", "example": -1845026871 }, "cardClass": { "type": "integer", "description": "卡类别，厂商原始字段", "example": 8 }, "customerID": { "type": "integer", "description": "一卡通人员账号", "example": 29373 }, "cardNO": { "type": "integer", "description": "一卡通业务卡号", "example": 1705827 }, "cardSN": { "type": "integer", "description": "持卡序号", "example": 2 }, "status": { "type": "integer", "description": "卡状态原始值", "example": 241 }, "subType": { "type": "integer", "description": "补助钱包类型原始值", "example": 0 }, "ze": { "type": "integer", "description": "新开普读卡结果中的ze原始值", "example": 66464 }, "ye": { "type": "integer", "description": "主钱包余额原始值", "example": 211 }, "opCount": { "type": "integer", "description": "主钱包消费计数", "example": 38 }, "subYe": { "type": "integer", "description": "补助钱包余额原始值", "example": 0 }, "subCount": { "type": "integer", "description": "补助钱包消费计数", "example": 0 }, "cardASN": { "type": "string", "description": "卡应用序列号", "example": "AA030000026D60992AB9" } }, "additionalProperties": false }, "AcquireResponse": { "type": "object", "required": [ "code", "message", "data", "trace_id" ], "properties": { "code": { "type": "integer", "description": "0成功、1失败", "example": 0 }, "message": { "type": "string", "description": "处理消息", "example": "success" }, "data": { "type": "object", "required": [ "order_no", "amount" ], "properties": { "order_no": { "type": "string", "description": "智慧餐厅待结算订单号", "example": "260815120000001" }, "amount": { "type": "integer", "description": "待结算订单金额，单位分；由智慧餐厅数据库中的元乘以100转换", "example": 1234 } } }, "trace_id": { "type": "string", "description": "请求链路标识，由系统通用返回方法生成", "example": "6a671d7d5539d" } } } } } }