{ "openapi": "3.0.3", "info": { "title": "荣海小学账单缴费移动端接口", "version": "2026-05-22", "description": "移动端账单记录、账单详情、账单支付和支付结果反查接口。本批接口写入 Apifox 项目 5737553，目标目录 48690333。" }, "servers": [ { "url": "https://zhctdev.yyangpt.cn", "description": "开发环境" } ], "tags": [ { "name": "账单记录", "description": "荣海小学移动端月度账单缴费接口" } ], "paths": { "/aizhct/api/h5/bills": { "get": { "tags": [ "账单记录" ], "x-apifox-folder": "账单记录", "summary": "移动端账单列表", "description": "查询当前登录家长/用户可见的月度账单列表。待核对账单不返回；支持按状态、年份筛选。账单列表页默认传当前年份。", "operationId": "h5BillingList", "parameters": [ { "name": "Access-Token", "in": "header", "description": "登录 token", "required": true, "schema": { "type": "string" }, "example": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." }, { "name": "platform", "in": "header", "description": "客户端标识，固定 H5", "required": false, "schema": { "type": "string", "default": "H5" }, "example": "H5" }, { "name": "student_id", "in": "query", "description": "学生 ID，当前实现可不传，后端按当前登录用户过滤", "required": false, "schema": { "type": "string" }, "example": "" }, { "name": "status", "in": "query", "description": "缴费状态筛选。可传中文状态或状态别名：待缴费/已缴费/超时未缴费，或 wait/waiting/paid/expired。", "required": false, "schema": { "type": "string", "enum": [ "", "待缴费", "已缴费", "超时未缴费", "wait", "waiting", "paid", "expired" ] }, "example": "" }, { "name": "year", "in": "query", "description": "账单年份，格式 YYYY。移动端账单记录页默认传当前年份。", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}$" }, "example": "2026" } ], "responses": { "200": { "description": "查询成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillListResponse" }, "examples": { "success": { "summary": "成功示例", "value": { "status": 200, "message": "ok", "data": { "list": [ { "id": 12, "record_id": 12, "bill_id": "BILL260500012", "bill_no": "BILL260500012", "student_name": "test12", "student_no": "RH20260112", "dept_name": "一年级1班", "bill_month": "2026-05", "payable_amount": 186.5, "status": "待缴费", "expire_time": "2026-06-10 23:59:59", "paid_time": "", "detail_count": 24, "details": [ { "meal_type": 1, "fee_type": "早餐", "adjusted_count": 8, "subtotal": "48.80" }, { "meal_type": 2, "fee_type": "午餐", "adjusted_count": 11, "subtotal": "96.20" }, { "meal_type": 3, "fee_type": "晚餐", "adjusted_count": 5, "subtotal": "41.50" } ] } ] } } } } } } } } } }, "/aizhct/api/h5/bills/{billId}": { "get": { "tags": [ "账单记录" ], "x-apifox-folder": "账单记录", "summary": "移动端账单详情", "description": "查询单张账单详情。详情页只展示基础信息和早餐、午餐、晚餐汇总，不展示逐笔消费明细。", "operationId": "h5BillingDetail", "parameters": [ { "name": "billId", "in": "path", "description": "账单 ID 或账单编号。移动端一般传 bill_id 字段，即账单编号。", "required": true, "schema": { "type": "string" }, "example": "BILL260500012" }, { "name": "Access-Token", "in": "header", "description": "登录 token", "required": true, "schema": { "type": "string" }, "example": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." }, { "name": "platform", "in": "header", "description": "客户端标识，固定 H5", "required": false, "schema": { "type": "string", "default": "H5" }, "example": "H5" } ], "responses": { "200": { "description": "查询成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillDetailResponse" }, "examples": { "success": { "summary": "成功示例", "value": { "status": 200, "message": "ok", "data": { "id": 12, "record_id": 12, "bill_id": "BILL260500012", "bill_no": "BILL260500012", "student_name": "test12", "student_no": "RH20260112", "dept_name": "一年级1班", "bill_month": "2026-05", "payable_amount": 186.5, "status": "待缴费", "expire_time": "2026-06-10 23:59:59", "paid_time": "", "detail_count": 24, "details": [ { "meal_type": 1, "fee_type": "早餐", "adjusted_count": 8, "subtotal": "48.80" }, { "meal_type": 2, "fee_type": "午餐", "adjusted_count": 11, "subtotal": "96.20" }, { "meal_type": 3, "fee_type": "晚餐", "adjusted_count": 5, "subtotal": "41.50" } ] } } } } } } } } } }, "/aizhct/api/h5/bills/{billId}/recharge-pay": { "post": { "tags": [ "账单记录" ], "x-apifox-folder": "账单记录", "summary": "生成账单支付链接", "description": "点击立即支付时调用。后端先校验账单归属、状态、有效期和金额；如果该账单已有待支付充值订单则复用，没有则新建。该订单只借用充值支付链路，不增加余额。", "operationId": "h5BillingRechargePay", "parameters": [ { "name": "billId", "in": "path", "description": "账单 ID 或账单编号。移动端一般传 bill_id 字段，即账单编号。", "required": true, "schema": { "type": "string" }, "example": "BILL260500012" }, { "name": "Access-Token", "in": "header", "description": "登录 token", "required": true, "schema": { "type": "string" }, "example": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." }, { "name": "platform", "in": "header", "description": "客户端标识，固定 H5", "required": false, "schema": { "type": "string", "default": "H5" }, "example": "H5" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/BillingPayRequest" }, "examples": { "default": { "summary": "请求示例", "value": { "userId": "1779341267281", "token": "xxx-token", "amount": "186.50" } } } }, "application/json": { "schema": { "$ref": "#/components/schemas/BillingPayRequest" } } } }, "responses": { "200": { "description": "返回邮储支付链接", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPayUrlResponse" }, "examples": { "success": { "summary": "成功示例", "value": { "status": 200, "message": "ok", "data": { "url": "https://static.mobile-bank.psbc.com/static/back/jump.html?...", "orderNo": "26060100018", "out_trade_no": "26060100018", "trade_id": 1024, "recharge_order_id": 987, "recharge_order_no": "RE26060100018", "bill_id": 12, "bill_no": "BILL260500012" } } } } } } } } } }, "/aizhct/api/h5/bills/{billId}/pay": { "post": { "tags": [ "账单记录" ], "x-apifox-folder": "账单记录", "summary": "账单支付链接兼容入口", "description": "旧入口兼容。当前内部逻辑等同于 /h5/bills/{billId}/recharge-pay。", "operationId": "h5BillingPayCompat", "parameters": [ { "name": "billId", "in": "path", "description": "账单 ID 或账单编号", "required": true, "schema": { "type": "string" }, "example": "BILL260500012" }, { "name": "Access-Token", "in": "header", "description": "登录 token", "required": true, "schema": { "type": "string" }, "example": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." }, { "name": "platform", "in": "header", "description": "客户端标识，固定 H5", "required": false, "schema": { "type": "string", "default": "H5" }, "example": "H5" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/BillingPayRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/BillingPayRequest" } } } }, "responses": { "200": { "description": "返回邮储支付链接", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPayUrlResponse" } } } } } } }, "/aizhct/api/h5/bills/pay-result": { "post": { "tags": [ "账单记录" ], "x-apifox-folder": "账单记录", "summary": "账单支付结果反查", "description": "支付回跳首页后，移动端根据 out_trade_no 反查账单支付结果。账单缴费订单会回写账单状态为已缴费，并返回账单信息用于展示缴费成功弹框。", "operationId": "h5BillingPayResult", "parameters": [ { "name": "Access-Token", "in": "header", "description": "登录 token", "required": true, "schema": { "type": "string" }, "example": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." }, { "name": "platform", "in": "header", "description": "客户端标识，固定 H5", "required": false, "schema": { "type": "string", "default": "H5" }, "example": "H5" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/BillingPayResultRequest" }, "examples": { "default": { "summary": "请求示例", "value": { "out_trade_no": "26060100018" } } } }, "application/json": { "schema": { "$ref": "#/components/schemas/BillingPayResultRequest" } } } }, "responses": { "200": { "description": "账单缴费成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPayResultResponse" }, "examples": { "success": { "summary": "成功示例", "value": { "status": 200, "message": "账单缴费成功", "data": { "isPay": true, "bill_id": 12, "bill_no": "BILL260500012", "out_trade_no": "26060100018", "recharge_order_id": 987, "recharge_order_no": "RE26060100018", "amount": "186.50", "pay_time": "2026-06-01 10:22:00", "bill": { "id": 12, "record_id": 12, "bill_id": "BILL260500012", "bill_no": "BILL260500012", "student_name": "test12", "student_no": "RH20260112", "dept_name": "一年级1班", "bill_month": "2026-05", "payable_amount": 186.5, "status": "已缴费", "expire_time": "2026-06-10 23:59:59", "paid_time": "2026-06-01 10:22:00", "detail_count": 24, "details": [ { "meal_type": 1, "fee_type": "早餐", "adjusted_count": 8, "subtotal": "48.80" }, { "meal_type": 2, "fee_type": "午餐", "adjusted_count": 11, "subtotal": "96.20" }, { "meal_type": 3, "fee_type": "晚餐", "adjusted_count": 5, "subtotal": "41.50" } ] } } } } } } } } } } } }, "components": { "schemas": { "ApiResponseBase": { "type": "object", "properties": { "status": { "type": "integer", "description": "业务状态码，200 表示成功", "example": 200 }, "message": { "type": "string", "example": "ok" } }, "required": [ "status", "message" ] }, "BillRecord": { "type": "object", "properties": { "id": { "type": "integer", "example": 12 }, "record_id": { "type": "integer", "example": 12 }, "bill_id": { "type": "string", "description": "账单编号，移动端详情和支付时传该值", "example": "BILL260500012" }, "bill_no": { "type": "string", "example": "BILL260500012" }, "student_name": { "type": "string", "example": "test12" }, "student_no": { "type": "string", "example": "RH20260112" }, "dept_name": { "type": "string", "example": "一年级1班" }, "bill_month": { "type": "string", "description": "账单月份，格式 YYYY-MM", "example": "2026-05" }, "payable_amount": { "type": "number", "format": "float", "example": 186.5 }, "status": { "type": "string", "enum": [ "待缴费", "已缴费", "超时未缴费" ], "example": "待缴费" }, "expire_time": { "type": "string", "example": "2026-06-10 23:59:59" }, "paid_time": { "type": "string", "example": "" }, "detail_count": { "type": "integer", "example": 24 }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/BillMealDetail" } } } }, "BillMealDetail": { "type": "object", "properties": { "meal_type": { "type": "integer", "description": "餐次：1 早餐，2 午餐，3 晚餐", "example": 1 }, "fee_type": { "type": "string", "example": "早餐" }, "adjusted_count": { "type": "integer", "description": "调整后明细数", "example": 8 }, "subtotal": { "type": "string", "description": "调整后小计金额", "example": "48.80" } } }, "BillListResponse": { "allOf": [ { "$ref": "#/components/schemas/ApiResponseBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/BillRecord" } } } } } } ] }, "BillDetailResponse": { "allOf": [ { "$ref": "#/components/schemas/ApiResponseBase" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BillRecord" } } } ] }, "BillingPayRequest": { "type": "object", "properties": { "userId": { "type": "string", "description": "邮储/认证返回的用户 ID", "example": "1779341267281" }, "token": { "type": "string", "description": "登录 token", "example": "xxx-token" }, "amount": { "type": "string", "description": "账单金额。后端会校验该金额必须与账单当前金额一致。", "example": "186.50" } }, "required": [ "userId", "token", "amount" ] }, "BillingPayUrlResponse": { "allOf": [ { "$ref": "#/components/schemas/ApiResponseBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "description": "邮储支付跳转地址", "example": "https://static.mobile-bank.psbc.com/static/back/jump.html?..." }, "orderNo": { "type": "string", "example": "26060100018" }, "out_trade_no": { "type": "string", "example": "26060100018" }, "trade_id": { "type": "integer", "example": 1024 }, "recharge_order_id": { "type": "integer", "example": 987 }, "recharge_order_no": { "type": "string", "example": "RE26060100018" }, "bill_id": { "type": "integer", "example": 12 }, "bill_no": { "type": "string", "example": "BILL260500012" } } } } } ] }, "BillingPayResultRequest": { "type": "object", "properties": { "out_trade_no": { "type": "string", "description": "支付回跳携带的商户订单号", "example": "26060100018" } }, "required": [ "out_trade_no" ] }, "BillingPayResultResponse": { "allOf": [ { "$ref": "#/components/schemas/ApiResponseBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "isPay": { "type": "boolean", "example": true }, "bill_id": { "type": "integer", "example": 12 }, "bill_no": { "type": "string", "example": "BILL260500012" }, "out_trade_no": { "type": "string", "example": "26060100018" }, "recharge_order_id": { "type": "integer", "example": 987 }, "recharge_order_no": { "type": "string", "example": "RE26060100018" }, "amount": { "type": "string", "example": "186.50" }, "pay_time": { "type": "string", "example": "2026-06-01 10:22:00" }, "bill": { "$ref": "#/components/schemas/BillRecord" } } } } } ] } } } }