{ "openapi": "3.0.3", "info": { "title": "星火跃迁总部机器 OpenAPI", "version": "1.7.0", "description": "已实现的总部机器接口。使用独立应用密钥，门店所有者逐店确认权限和期限。营销数据新增 marketing:read；本文件不提供机器代付、自动同意费用或结算权限。" }, "servers": [ { "url": "/", "description": "使用目标业务网关根地址；路径已包含 /api。" } ], "security": [ { "ChainAppKey": [] } ], "tags": [ { "name": "总部机器 API" } ], "paths": { "/api/openapi/chain/v1/stores": { "get": { "operationId": "listAuthorizedChainStores", "summary": "分页读取应用获授权门店", "description": "只返回具备有效 stores:read 授权的门店。应用、授权、门店所有者及总部关系实时核验。 电商目录附带 ecommerceIdentity：主体、店铺类型、类目、品牌授权摘要及到期状态。历史材料不完整时返回 unverified，不自动认定为旗舰店。", "tags": [ "总部机器 API" ], "x-required-scopes": [ "stores:read" ], "parameters": [ { "name": "afterId", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0, "default": 0 }, "description": "上一页 nextCursor，首屏省略或传 0；按门店 ID 升序。" }, { "name": "limit", "in": "query", "required": false, "description": "每页数量，默认 100。", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 200, "default": 100 } } ], "responses": { "200": { "description": "业务成功。先检查 success，再读取 data。", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoresResponse" }, "example": { "success": true, "message": "success", "data": { "stores": [ { "merchantId": 18, "name": "示例分店", "businessType": "waimai", "scopes": [ "stores:read", "catalog:read" ], "expiresAt": "2026-11-11T00:00:00Z" } ], "nextCursor": null } } } } }, "400": { "description": "参数、业务类型或模板版本不符合要求。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "应用密钥缺失、无效、撤销，或创建者权限已失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "门店范围、scope、有效期、所有者身份或内容同意不满足要求。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "业务服务内部错误；写入结果不明时先核对状态。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/openapi/chain/v1/stores/{id}/catalog": { "get": { "operationId": "getAuthorizedStoreCatalog", "summary": "分页读取指定门店商品目录", "description": "需要 catalog:read。外卖及即时零售与邮寄电商返回不同商品字段，金额使用人民币分。目录不包含客户资料或资金权限。", "tags": [ "总部机器 API" ], "x-required-scopes": [ "catalog:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "当前应用在相应 scope 下获授权的门店 ID。", "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, { "name": "afterId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 }, "description": "上一页 nextCursor 字符串。首屏省略；电商值必须能解析为 int64，省略按 0；其他业务按产品字符串 ID 排序。" }, { "name": "limit", "in": "query", "required": false, "description": "每页数量，默认 100。", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 200, "default": 100 } } ], "responses": { "200": { "description": "业务成功。先检查 success，再读取 data。", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogResponse" }, "example": { "success": true, "message": "success", "data": { "merchantId": 18, "products": [ { "id": "item-18-1", "name": "示例菜品", "description": null, "priceFen": 1800, "packagingFeeFen": 100, "images": null, "status": "unavailable", "stock": 0, "updatedAt": "2026-10-12T00:00:00Z" } ], "nextCursor": null } } } } }, "400": { "description": "参数、业务类型或模板版本不符合要求。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "应用密钥缺失、无效、撤销，或创建者权限已失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "门店范围、scope、有效期、所有者身份或内容同意不满足要求。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "业务服务内部错误；写入结果不明时先核对状态。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/openapi/chain/v1/stores/{id}/content": { "post": { "operationId": "applyHeadquartersContentVersion", "summary": "已停用：由店长在模板库确认选用", "description": "此接口不再修改门店内容，返回错误。总部发布不覆盖本店价格。", "tags": [ "总部机器 API" ], "x-required-scopes": [ "content:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "当前应用在相应 scope 下获授权的门店 ID。", "schema": { "type": "integer", "format": "int64", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyContentRequest" }, "example": { "templateVersion": 1 } } } }, "responses": { "400": { "description": "批量覆盖已停用，请由店长确认选用模板" }, "401": { "description": "应用密钥缺失、无效、撤销，或创建者权限已失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "门店范围、scope、有效期、所有者身份或内容同意不满足要求。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "业务服务内部错误；写入结果不明时先核对状态。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "deprecated": true } }, "/api/openapi/chain/v1/marketing/plans": { "get": { "operationId": "listChainMarketingPlans", "summary": "读取授权门店涉及的总部计划", "description": "仅返回当前有效 marketing:read 门店授权范围。summary 包含本店与总部全部推广，金额字段以 Fen 或 Micros 指明单位；计划计数不泄露范围外门店。完整口径见 chain-marketing.md。", "tags": [ "总部机器 API" ], "x-required-scopes": [ "marketing:read" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 80 } }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "promotion", "activity" ] } } ], "responses": { "200": { "description": "成功，success=true。无事件的汇总为0，sourceUpdatedAt 为 null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChainMarketingPlansResponse" }, "example": { "success": true, "message": "success", "data": { "items": [], "total": 0, "page": 1, "pageSize": 20, "scopeStoreCount": 1, "canManage": false, "updatedAt": "2026-10-12T00:00:00Z" } } } } }, "400": { "description": "参数无效" }, "401": { "description": "密钥或应用身份无效" }, "403": { "description": "业务不支持，或没有有效营销读取授权" } } } }, "/api/openapi/chain/v1/marketing/plans/{id}/stores": { "get": { "operationId": "listChainMarketingTargets", "summary": "读取授权门店的计划执行状态", "description": "仅返回当前有效 marketing:read 门店授权范围。summary 包含本店与总部全部推广，金额字段以 Fen 或 Micros 指明单位；计划计数不泄露范围外门店。完整口径见 chain-marketing.md。", "tags": [ "总部机器 API" ], "x-required-scopes": [ "marketing:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 80 } } ], "responses": { "200": { "description": "成功，success=true。无事件的汇总为0，sourceUpdatedAt 为 null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChainMarketingTargetsResponse" }, "example": { "success": true, "message": "success", "data": { "planId": 1, "items": [], "total": 0, "page": 1, "pageSize": 20 } } } } }, "400": { "description": "参数无效" }, "401": { "description": "密钥或应用身份无效" }, "403": { "description": "业务不支持，或没有有效营销读取授权" } } } }, "/api/openapi/chain/v1/marketing/summary": { "get": { "operationId": "readChainMarketingSummary", "summary": "读取授权门店推广汇总", "description": "仅返回当前有效 marketing:read 门店授权范围。summary 包含本店与总部全部推广，金额字段以 Fen 或 Micros 指明单位；计划计数不泄露范围外门店。完整口径见 chain-marketing.md。", "tags": [ "总部机器 API" ], "x-required-scopes": [ "marketing:read" ], "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 7 } } ], "responses": { "200": { "description": "成功，success=true。无事件的汇总为0，sourceUpdatedAt 为 null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChainMarketingSummaryResponse" }, "example": { "success": true, "message": "success", "data": { "scope": "authorized_store_all_promotions", "scopeStoreCount": 1, "storesWithReport": 0, "days": 7, "timezone": "Asia/Shanghai", "exposures": 0, "clicks": 0, "attributedOrders": 0, "spendFen": 0, "attributedRevenueFen": 0, "clickThroughRate": null, "sourceUpdatedAt": null, "generatedAt": "2026-10-12T00:00:00Z" } } } } }, "400": { "description": "参数无效" }, "401": { "description": "密钥或应用身份无效" }, "403": { "description": "业务不支持，或没有有效营销读取授权" } } } }, "/api/openapi/chain/v1/stores/{id}/ecommerce/orders": { "get": { "operationId": "ecommerceOrders", "summary": "游标读取已付款电商订单", "description": "需要逐店授权 ecommerce:orders:read，仅支持电商。应用共享每分钟1200次读取额度，遵守 Retry-After；不含客户收件资料或发货写入。变化接口是最新状态投影，按门店和分区保存字符串游标；visible=false 时移除本地可操作记录，不作为逐次事件或账务流水。", "tags": [ "电商订单" ], "x-required-scopes": [ "ecommerce:orders:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "afterId", "in": "query", "schema": { "type": "string", "pattern": "^[0-9]{1,19}$", "default": "0" } } ], "responses": { "200": { "description": "读取成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EcommerceOrdersResponse" }, "example": { "success": true, "message": "success", "data": { "merchantId": "183", "orders": [ { "orderId": "100001", "orderNo": "EC09316P4G01", "merchantId": "183", "status": "paid", "payStatus": "paid", "fulfillmentStatus": "pending_ship", "payAmountFen": 5900, "createdAt": "2026-10-18T00:00:00Z", "paidAt": "2026-10-18T00:01:00Z", "updatedAt": "2026-10-18T00:01:00Z" } ], "hasMore": false, "nextAfterId": null } } } } }, "400": { "description": "参数、游标或批次无效" }, "401": { "description": "应用无效或已撤销" }, "403": { "description": "行业、门店范围或订单权限不符" }, "404": { "description": "订单不可用" }, "429": { "description": "超过应用或网关额度", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "等待秒数" } } }, "503": { "description": "共享限流或服务暂不可用" } } } }, "/api/openapi/chain/v1/stores/{id}/ecommerce/orders/sync-state": { "get": { "operationId": "ecommerceSyncState", "summary": "读取电商订单分区版本", "description": "需要逐店授权 ecommerce:orders:read，仅支持电商。应用共享每分钟1200次读取额度，遵守 Retry-After；不含客户收件资料或发货写入。变化接口是最新状态投影，按门店和分区保存字符串游标；visible=false 时移除本地可操作记录，不作为逐次事件或账务流水。", "tags": [ "电商订单" ], "x-required-scopes": [ "ecommerce:orders:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "读取成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EcommerceSyncStateResponse" }, "example": { "success": true, "message": "success", "data": { "schemaVersion": 1, "merchantId": "183", "partitionCount": 64, "partitions": [ { "partition": 0, "revision": "0" }, { "partition": 1, "revision": "0" }, { "partition": 2, "revision": "0" }, { "partition": 3, "revision": "0" }, { "partition": 4, "revision": "0" }, { "partition": 5, "revision": "0" }, { "partition": 6, "revision": "0" }, { "partition": 7, "revision": "0" }, { "partition": 8, "revision": "0" }, { "partition": 9, "revision": "0" }, { "partition": 10, "revision": "0" }, { "partition": 11, "revision": "0" }, { "partition": 12, "revision": "0" }, { "partition": 13, "revision": "0" }, { "partition": 14, "revision": "0" }, { "partition": 15, "revision": "0" }, { "partition": 16, "revision": "0" }, { "partition": 17, "revision": "0" }, { "partition": 18, "revision": "0" }, { "partition": 19, "revision": "0" }, { "partition": 20, "revision": "0" }, { "partition": 21, "revision": "0" }, { "partition": 22, "revision": "0" }, { "partition": 23, "revision": "0" }, { "partition": 24, "revision": "0" }, { "partition": 25, "revision": "0" }, { "partition": 26, "revision": "0" }, { "partition": 27, "revision": "0" }, { "partition": 28, "revision": "0" }, { "partition": 29, "revision": "0" }, { "partition": 30, "revision": "0" }, { "partition": 31, "revision": "0" }, { "partition": 32, "revision": "0" }, { "partition": 33, "revision": "1" }, { "partition": 34, "revision": "0" }, { "partition": 35, "revision": "0" }, { "partition": 36, "revision": "0" }, { "partition": 37, "revision": "0" }, { "partition": 38, "revision": "0" }, { "partition": 39, "revision": "0" }, { "partition": 40, "revision": "0" }, { "partition": 41, "revision": "0" }, { "partition": 42, "revision": "0" }, { "partition": 43, "revision": "0" }, { "partition": 44, "revision": "0" }, { "partition": 45, "revision": "0" }, { "partition": 46, "revision": "0" }, { "partition": 47, "revision": "0" }, { "partition": 48, "revision": "0" }, { "partition": 49, "revision": "0" }, { "partition": 50, "revision": "0" }, { "partition": 51, "revision": "0" }, { "partition": 52, "revision": "0" }, { "partition": 53, "revision": "0" }, { "partition": 54, "revision": "0" }, { "partition": 55, "revision": "0" }, { "partition": 56, "revision": "0" }, { "partition": 57, "revision": "0" }, { "partition": 58, "revision": "0" }, { "partition": 59, "revision": "0" }, { "partition": 60, "revision": "0" }, { "partition": 61, "revision": "0" }, { "partition": 62, "revision": "0" }, { "partition": 63, "revision": "0" } ] } } } } }, "400": { "description": "参数、游标或批次无效" }, "401": { "description": "应用无效或已撤销" }, "403": { "description": "行业、门店范围或订单权限不符" }, "404": { "description": "订单不可用" }, "429": { "description": "超过应用或网关额度", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "等待秒数" } } }, "503": { "description": "共享限流或服务暂不可用" } } } }, "/api/openapi/chain/v1/stores/{id}/ecommerce/orders/changes": { "get": { "operationId": "ecommerceOrderChanges", "summary": "增量读取分区最新订单状态", "description": "需要逐店授权 ecommerce:orders:read，仅支持电商。应用共享每分钟1200次读取额度，遵守 Retry-After；不含客户收件资料或发货写入。变化接口是最新状态投影，按门店和分区保存字符串游标；visible=false 时移除本地可操作记录，不作为逐次事件或账务流水。", "tags": [ "电商订单" ], "x-required-scopes": [ "ecommerce:orders:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "partition", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 0, "maximum": 63 } }, { "name": "afterRevision", "in": "query", "schema": { "type": "string", "pattern": "^[0-9]{1,19}$", "default": "0" } } ], "responses": { "200": { "description": "读取成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EcommerceOrderChangesResponse" }, "example": { "success": true, "message": "success", "data": { "merchantId": "183", "partition": 33, "afterRevision": "0", "highWatermark": "1", "nextAfterRevision": "1", "hasMore": false, "items": [ { "revision": "1", "visible": true, "order": { "orderId": "100001", "orderNo": "EC09316P4G01", "merchantId": "183", "status": "paid", "payStatus": "paid", "fulfillmentStatus": "pending_ship", "payAmountFen": 5900, "createdAt": "2026-10-18T00:00:00Z", "paidAt": "2026-10-18T00:01:00Z", "updatedAt": "2026-10-18T00:01:00Z" } } ] } } } } }, "400": { "description": "参数、游标或批次无效" }, "401": { "description": "应用无效或已撤销" }, "403": { "description": "行业、门店范围或订单权限不符" }, "404": { "description": "订单不可用" }, "429": { "description": "超过应用或网关额度", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "等待秒数" } } }, "503": { "description": "共享限流或服务暂不可用" } } } }, "/api/openapi/chain/v1/stores/{id}/ecommerce/orders/batch-query": { "post": { "operationId": "ecommerceOrderBatch", "summary": "批量查询电商订单状态", "description": "需要逐店授权 ecommerce:orders:read，仅支持电商。应用共享每分钟1200次读取额度，遵守 Retry-After；不含客户收件资料或发货写入。变化接口是最新状态投影，按门店和分区保存字符串游标；visible=false 时移除本地可操作记录，不作为逐次事件或账务流水。", "tags": [ "电商订单" ], "x-required-scopes": [ "ecommerce:orders:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "读取成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EcommerceOrderBatchResponse" }, "example": { "success": true, "message": "success", "data": { "merchantId": "183", "orders": [ { "orderId": "100001", "orderNo": "EC09316P4G01", "merchantId": "183", "status": "paid", "payStatus": "paid", "fulfillmentStatus": "pending_ship", "payAmountFen": 5900, "createdAt": "2026-10-18T00:00:00Z", "paidAt": "2026-10-18T00:01:00Z", "updatedAt": "2026-10-18T00:01:00Z" } ], "unavailableOrderNos": [] } } } } }, "400": { "description": "参数、游标或批次无效" }, "401": { "description": "应用无效或已撤销" }, "403": { "description": "行业、门店范围或订单权限不符" }, "404": { "description": "订单不可用" }, "429": { "description": "超过应用或网关额度", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "等待秒数" } } }, "503": { "description": "共享限流或服务暂不可用" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "orderNos" ], "properties": { "orderNos": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 128 } } } }, "example": { "orderNos": [ "EC09316P4G01" ] } } } } } }, "/api/openapi/chain/v1/stores/{id}/ecommerce/orders/detail": { "get": { "operationId": "ecommerceOrderDetailRead", "summary": "读取电商订单商品明细", "description": "需要逐店授权 ecommerce:orders:read，仅支持电商。应用共享每分钟1200次读取额度，遵守 Retry-After；不含客户收件资料或发货写入。变化接口是最新状态投影，按门店和分区保存字符串游标；visible=false 时移除本地可操作记录，不作为逐次事件或账务流水。", "tags": [ "电商订单" ], "x-required-scopes": [ "ecommerce:orders:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, { "name": "orderNo", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "读取成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EcommerceOrderDetailReadResponse" }, "example": { "success": true, "message": "success", "data": { "order": { "orderId": "100001", "orderNo": "EC09316P4G01", "merchantId": "183", "status": "paid", "payStatus": "paid", "fulfillmentStatus": "pending_ship", "payAmountFen": 5900, "createdAt": "2026-10-18T00:00:00Z", "paidAt": "2026-10-18T00:01:00Z", "updatedAt": "2026-10-18T00:01:00Z", "items": [ { "itemId": "901", "productId": "71", "skuId": "81", "title": "棉质短袖", "quantity": 1, "payAmountFen": 5900 } ] } } } } } }, "400": { "description": "参数、游标或批次无效" }, "401": { "description": "应用无效或已撤销" }, "403": { "description": "行业、门店范围或订单权限不符" }, "404": { "description": "订单不可用" }, "429": { "description": "超过应用或网关额度", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "等待秒数" } } }, "503": { "description": "共享限流或服务暂不可用" } } } } }, "components": { "securitySchemes": { "ChainAppKey": { "type": "apiKey", "in": "header", "name": "X-Chain-App-Key", "description": "总部应用密钥。它不是人员登录 JWT，不能放到查询参数或浏览器代码。" } }, "schemas": { "ErrorResponse": { "type": "object", "required": [ "success", "message", "data" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "message": { "type": "string" }, "data": { "type": "object", "nullable": true, "enum": [ null ] } }, "description": "业务错误使用 ApiResponse 包装；data 为 null。" }, "Store": { "type": "object", "required": [ "merchantId", "name", "businessType", "scopes", "expiresAt" ], "properties": { "merchantId": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "businessType": { "type": "string", "enum": [ "waimai", "supermarket", "ecommerce" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "stores:read", "catalog:read", "content:write", "marketing:read", "ecommerce:orders:read" ], "description": "当前可申请 stores:read、catalog:read，外卖另支持 marketing:read；content:write 仅可能存在于历史授权记录，已停用且不可新增。 电商另支持独立授权 ecommerce:orders:read。" } }, "expiresAt": { "type": "string", "format": "date-time" }, "ecommerceIdentity": { "$ref": "#/components/schemas/EcommerceIdentity" } } }, "StoresData": { "type": "object", "required": [ "stores", "nextCursor" ], "properties": { "stores": { "type": "array", "items": { "$ref": "#/components/schemas/Store" }, "maxItems": 200 }, "nextCursor": { "type": "integer", "nullable": true, "format": "int64", "description": "后续仍有记录时返回本页最后一个门店 ID；结束时为 null。下一页作为 afterId。" } } }, "FoodProduct": { "type": "object", "required": [ "id", "name", "description", "priceFen", "status", "updatedAt", "packagingFeeFen", "images", "stock" ], "properties": { "id": { "type": "string", "description": "产品标识；电商为整数 ID 的字符串形式。" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "priceFen": { "type": "integer", "format": "int64", "description": "售价，人民币分。" }, "status": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "packagingFeeFen": { "type": "integer", "nullable": true, "format": "int64", "description": "包装费，人民币分。" }, "images": { "type": "string", "nullable": true, "description": "现有 image_url 字段；字段名虽为 images，值仍是单个字符串或 null，不是数组。" }, "stock": { "type": "integer", "nullable": true, "format": "int32" } }, "description": "外卖及即时零售目录。过滤 status=deleted 的记录。" }, "EcommerceProduct": { "type": "object", "required": [ "id", "name", "description", "priceFen", "status", "updatedAt", "image" ], "properties": { "id": { "type": "string", "description": "产品标识；电商为整数 ID 的字符串形式。" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "priceFen": { "type": "integer", "format": "int64", "description": "售价，人民币分。" }, "status": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "image": { "type": "string", "nullable": true, "description": "电商 main_image 字段。" } }, "description": "邮寄电商目录；包含门店商品的实际状态，不能把目录记录等同于可售商品。" }, "CatalogData": { "type": "object", "required": [ "merchantId", "products", "nextCursor" ], "properties": { "merchantId": { "type": "integer", "format": "int64" }, "products": { "type": "array", "maxItems": 200, "items": { "oneOf": [ { "$ref": "#/components/schemas/FoodProduct" }, { "$ref": "#/components/schemas/EcommerceProduct" } ] } }, "nextCursor": { "type": "string", "nullable": true, "description": "后续仍有记录时返回本页最后一个产品字符串 ID；结束时为 null。下一页作为 afterId。" } } }, "ApplyContentRequest": { "type": "object", "required": [ "templateVersion" ], "properties": { "templateVersion": { "type": "integer", "format": "int64", "minimum": 1, "description": "总部当前已保存模板版本，必须与服务端版本相同。" } }, "additionalProperties": false }, "ApplyContentData": { "type": "object", "required": [ "merchantId", "status", "createdProducts", "updatedProducts" ], "properties": { "merchantId": { "type": "integer", "format": "int64" }, "status": { "type": "string", "enum": [ "applied" ] }, "createdProducts": { "type": "integer", "minimum": 0 }, "updatedProducts": { "type": "integer", "minimum": 0 }, "alreadyApplied": { "type": "boolean", "enum": [ true ], "description": "仅该门店已经应用同一版本时出现；本次创建及更新数均为 0。" } } }, "StoresResponse": { "type": "object", "required": [ "success", "message", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/StoresData" } } }, "CatalogResponse": { "type": "object", "required": [ "success", "message", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/CatalogData" } } }, "ApplyContentResponse": { "type": "object", "required": [ "success", "message", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/ApplyContentData" } } }, "ChainMarketingCounts": { "type": "object", "required": [ "stores", "pending", "accepted", "declined", "stopped", "spendMicros" ], "properties": { "stores": { "type": "integer", "format": "int64" }, "pending": { "type": "integer", "format": "int64" }, "accepted": { "type": "integer", "format": "int64" }, "declined": { "type": "integer", "format": "int64" }, "stopped": { "type": "integer", "format": "int64" }, "spendMicros": { "type": "integer", "format": "int64" }, "stopFailed": { "type": "integer", "minimum": 0, "description": "等待重试停止的门店数" } } }, "ChainMarketingPlan": { "type": "object", "required": [ "id", "name", "kind", "moduleType", "status", "startsAt", "endsAt", "payer", "terms", "counts" ], "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "promotion", "activity" ] }, "moduleType": { "type": "string", "enum": [ "gold", "full-reduction", "coupon" ] }, "status": { "type": "string", "enum": [ "published", "stopping", "ended" ] }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "payer": { "type": "string", "enum": [ "store" ] }, "terms": { "type": "object", "additionalProperties": true }, "counts": { "$ref": "#/components/schemas/ChainMarketingCounts" } } }, "ChainMarketingTarget": { "type": "object", "required": [ "merchantId", "name", "status", "adCampaignId", "activityId", "deliveryStatus", "spendMicros", "decidedAt" ], "properties": { "merchantId": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "declined", "stopped", "stop_failed" ] }, "adCampaignId": { "type": "integer", "format": "int64", "nullable": true }, "activityId": { "type": "integer", "format": "int64", "nullable": true }, "deliveryStatus": { "type": "string", "nullable": true }, "spendMicros": { "type": "integer", "format": "int64", "nullable": true }, "decidedAt": { "type": "string", "format": "date-time", "nullable": true }, "stopError": { "type": "string", "nullable": true, "description": "停止失败原因，后台独立重试" } } }, "ChainMarketingPlansData": { "type": "object", "required": [ "items", "total", "page", "pageSize", "scopeStoreCount", "canManage", "updatedAt" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ChainMarketingPlan" } }, "total": { "type": "integer", "format": "int64" }, "page": { "type": "integer", "format": "int64" }, "pageSize": { "type": "integer", "format": "int64" }, "scopeStoreCount": { "type": "integer", "format": "int64" }, "canManage": { "type": "boolean" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "ChainMarketingTargetsData": { "type": "object", "required": [ "planId", "items", "total", "page", "pageSize" ], "properties": { "planId": { "type": "integer", "format": "int64" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ChainMarketingTarget" } }, "total": { "type": "integer", "format": "int64" }, "page": { "type": "integer", "format": "int64" }, "pageSize": { "type": "integer", "format": "int64" } } }, "ChainMarketingSummaryData": { "type": "object", "required": [ "scope", "scopeStoreCount", "storesWithReport", "days", "timezone", "exposures", "clicks", "attributedOrders", "spendFen", "attributedRevenueFen", "clickThroughRate", "sourceUpdatedAt", "generatedAt" ], "properties": { "scope": { "type": "string", "enum": [ "authorized_store_all_promotions" ] }, "scopeStoreCount": { "type": "integer", "format": "int64" }, "storesWithReport": { "type": "integer", "format": "int64" }, "days": { "type": "integer", "format": "int64" }, "timezone": { "type": "string", "enum": [ "Asia/Shanghai" ] }, "exposures": { "type": "integer", "format": "int64" }, "clicks": { "type": "integer", "format": "int64" }, "attributedOrders": { "type": "integer", "format": "int64" }, "spendFen": { "type": "integer", "format": "int64" }, "attributedRevenueFen": { "type": "integer", "format": "int64" }, "clickThroughRate": { "type": "number", "nullable": true }, "sourceUpdatedAt": { "type": "string", "format": "date-time", "nullable": true }, "generatedAt": { "type": "string", "format": "date-time" } } }, "ChainMarketingPlansResponse": { "type": "object", "required": [ "success", "message", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/ChainMarketingPlansData" } } }, "ChainMarketingTargetsResponse": { "type": "object", "required": [ "success", "message", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/ChainMarketingTargetsData" } } }, "ChainMarketingSummaryResponse": { "type": "object", "required": [ "success", "message", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/ChainMarketingSummaryData" } } }, "EcommerceOrderSnapshot": { "type": "object", "required": [ "orderId", "orderNo", "merchantId", "status", "payStatus", "fulfillmentStatus", "payAmountFen", "createdAt", "paidAt", "updatedAt" ], "properties": { "orderId": { "type": "string" }, "orderNo": { "type": "string" }, "merchantId": { "type": "string" }, "status": { "type": "string" }, "payStatus": { "type": "string", "enum": [ "paid", "partially_refunded", "refunded" ] }, "fulfillmentStatus": { "type": "string" }, "payAmountFen": { "type": "integer", "format": "int64" }, "createdAt": { "type": "string", "format": "date-time" }, "paidAt": { "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time" } } }, "EcommerceSyncPartition": { "type": "object", "required": [ "partition", "revision" ], "properties": { "partition": { "type": "integer", "minimum": 0, "maximum": 63 }, "revision": { "type": "string", "pattern": "^[0-9]{1,19}$" } } }, "EcommerceSyncChange": { "type": "object", "required": [ "revision", "visible", "order" ], "properties": { "revision": { "type": "string" }, "visible": { "type": "boolean" }, "order": { "$ref": "#/components/schemas/EcommerceOrderSnapshot" } } }, "EcommerceOrderLine": { "type": "object", "required": [ "itemId", "productId", "skuId", "title", "quantity", "payAmountFen" ], "properties": { "itemId": { "type": "string" }, "productId": { "type": "string" }, "skuId": { "type": "string" }, "title": { "type": "string" }, "quantity": { "type": "integer", "format": "int64" }, "payAmountFen": { "type": "integer", "format": "int64" } } }, "EcommerceOrderDetail": { "allOf": [ { "$ref": "#/components/schemas/EcommerceOrderSnapshot" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/EcommerceOrderLine" } } } } ] }, "EcommerceOrdersData": { "type": "object", "required": [ "merchantId", "orders", "hasMore", "nextAfterId" ], "properties": { "merchantId": { "type": "string" }, "orders": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/EcommerceOrderSnapshot" } }, "hasMore": { "type": "boolean" }, "nextAfterId": { "type": "string", "nullable": true } } }, "EcommerceOrdersResponse": { "type": "object", "required": [ "success", "message", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/EcommerceOrdersData" } } }, "EcommerceSyncStateData": { "type": "object", "required": [ "schemaVersion", "merchantId", "partitionCount", "partitions" ], "properties": { "schemaVersion": { "type": "integer", "enum": [ 1 ] }, "merchantId": { "type": "string" }, "partitionCount": { "type": "integer", "enum": [ 64 ] }, "partitions": { "type": "array", "minItems": 64, "maxItems": 64, "items": { "$ref": "#/components/schemas/EcommerceSyncPartition" } } } }, "EcommerceSyncStateResponse": { "type": "object", "required": [ "success", "message", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/EcommerceSyncStateData" } } }, "EcommerceOrderChangesData": { "type": "object", "required": [ "merchantId", "partition", "afterRevision", "highWatermark", "nextAfterRevision", "hasMore", "items" ], "properties": { "merchantId": { "type": "string" }, "partition": { "type": "integer", "minimum": 0, "maximum": 63 }, "afterRevision": { "type": "string" }, "highWatermark": { "type": "string" }, "nextAfterRevision": { "type": "string" }, "hasMore": { "type": "boolean" }, "items": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/EcommerceSyncChange" } } } }, "EcommerceOrderChangesResponse": { "type": "object", "required": [ "success", "message", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/EcommerceOrderChangesData" } } }, "EcommerceOrderBatchData": { "type": "object", "required": [ "merchantId", "orders", "unavailableOrderNos" ], "properties": { "merchantId": { "type": "string" }, "orders": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/EcommerceOrderSnapshot" } }, "unavailableOrderNos": { "type": "array", "items": { "type": "string" } } } }, "EcommerceOrderBatchResponse": { "type": "object", "required": [ "success", "message", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/EcommerceOrderBatchData" } } }, "EcommerceOrderDetailReadData": { "type": "object", "required": [ "order" ], "properties": { "order": { "$ref": "#/components/schemas/EcommerceOrderDetail" } } }, "EcommerceOrderDetailReadResponse": { "type": "object", "required": [ "success", "message", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/EcommerceOrderDetailReadData" } } }, "EcommerceIdentity": { "type": "object", "description": "仅电商店铺返回。来自平台批准且绑定本店现任所有者的申请，不包含身份证、证照图片、申请访问凭据；不改变 API 授权范围。", "required": [ "scope", "id", "status", "certified", "classification", "validity" ], "properties": { "scope": { "type": "string", "enum": [ "store" ] }, "id": { "type": "integer", "format": "int64" }, "status": { "type": "string", "enum": [ "valid", "expiring", "expired", "unverified", "review_required" ] }, "certified": { "type": "boolean", "description": "存在通过审核且未过期的分类资质；不代表交易、人员或资金授权。" }, "classification": { "type": "object", "properties": { "subjectType": { "type": "string", "enum": [ "personal", "individual", "enterprise" ] }, "entryType": { "type": "string", "enum": [ "normal", "general_trade" ] }, "shopType": { "type": "string", "enum": [ "enterprise", "flagship", "specialty", "franchise", "mall_flagship" ] }, "category": { "type": "string" }, "brandName": { "type": "string" }, "tradeRoute": { "type": "string", "enum": [ "trademark", "procurement" ] } } }, "brandAuthorization": { "type": "object", "nullable": true, "properties": { "relation": { "type": "string", "enum": [ "none", "own", "authorized", "procurement", "exempt" ] }, "level": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 4 }, "expiresOn": { "type": "string", "nullable": true } } }, "validity": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "expiresOn": { "type": "string" }, "status": { "type": "string", "enum": [ "valid", "expiring", "expired", "long_term" ] } } } }, "approvedAt": { "type": "string", "format": "date-time", "nullable": true } } } } } }