openapi: 3.0.3 info: title: Payful Structured Data & Public API version: 1.0.0 description: | Payful 官网对外公开的结构化数据与核心 API 说明。 本文档主要面向： - AI Agent / 爬虫：一次性获取官网关键信息 - 开发者：了解核心业务 API 能力（示例） 注意： - 当前为示例版本，一些业务字段为占位值（示例）； - 实际生产环境请根据后端真实接口补充 / 调整。 servers: - url: https://www.payful.com description: Production server - url: http://localhost:3000 description: Local development (Nuxt dev) paths: /api/structured-data: get: summary: 获取官网核心结构化数据 | Get Core Structured Data description: | 聚合官网「我们是谁、收多少钱、支持什么、怎么接、合规吗」等关键信息。 适用于： - AI Agent/爬虫拉取结构化数据 - 运维/运营做监控或信息校验 Supports ?lang=zh|en for localized content. tags: - StructuredData parameters: - name: lang in: query required: false schema: type: string enum: [zh, en] default: zh description: 语言，zh=中文，en=英文 responses: '200': description: 成功返回结构化数据 content: application/json: schema: $ref: '#/components/schemas/StructuredData' /api/news/top: post: summary: 获取置顶新闻列表 | Get Top News Articles description: | 对应 server/api/news/top.post.ts，useApi().news.top() 调用。 返回首页展示的置顶新闻文章。 tags: - News requestBody: required: false content: application/json: schema: type: object responses: '200': description: 成功返回置顶新闻列表 content: application/json: schema: type: object properties: code: type: string example: '0' result: type: array items: $ref: '#/components/schemas/NewsArticle' /api/news/type: get: summary: 获取新闻类型列表 description: | 官网内部使用的新闻类型接口，对应 server/api/news/type.get.ts。 tags: - News responses: '200': description: 成功返回新闻类型列表 content: application/json: schema: type: object properties: code: type: string example: '0' result: type: array items: type: object properties: newsType: type: integer example: 0 newsTypeName: type: string example: '支付攻略' /api/news/page: post: summary: 分页获取新闻列表 description: | 对应 server/api/news/page.post.ts。 支持按分类与分页查询新闻列表。 tags: - News requestBody: required: false content: application/json: schema: type: object properties: newsType: type: integer description: 新闻类型编码，可选 example: 0 currentPage: type: integer description: 当前页码，从 1 开始 example: 1 pageSize: type: integer description: 每页数量 example: 10 responses: '200': description: 成功返回新闻列表 content: application/json: schema: type: object properties: code: type: string example: '0' result: $ref: '#/components/schemas/NewsPageResult' /api/news/detail/{id}: get: summary: 获取新闻详情 description: | 对应 server/api/news/detail/[id].get.ts。 tags: - News parameters: - name: id in: path required: true schema: type: string description: 新闻唯一 ID responses: '200': description: 成功返回新闻详情 content: application/json: schema: type: object properties: code: type: string example: '0' result: $ref: '#/components/schemas/NewsArticle' /api/official-website/user/rate/query-support-ccy-pair: post: summary: 查询支持的币种对 | Query Supported Currency Pairs description: | 首页汇率组件调用，获取支持的买卖币种对映射。 返回格式 { ccyPair: Record<卖出币种, 买入币种[]>, ... } tags: - Rate parameters: - name: request-system-name in: header required: true schema: type: string example: payful-official-website description: 请求系统标识 responses: '200': description: 成功返回支持的币种对 content: application/json: schema: type: object properties: code: type: string example: '0' result: type: object properties: ccyPair: type: object additionalProperties: type: array items: type: string description: 键为卖出币种，值为可买入币种列表 /api/official-website/user/rate/real-time-query/{ccyPair}: post: summary: 实时汇率查询 | Real-time Exchange Rate Query description: | 根据币种对查询实时汇率。ccyPair 格式为 {buyCcy}{sellCcy}，如 CNHUSD、USDCNH。 首页汇率组件、全球汇市速览使用。 tags: - Rate parameters: - name: ccyPair in: path required: true schema: type: string example: CNHUSD description: 币种对，格式为买入币种+卖出币种，如 CNHUSD - name: request-system-name in: header required: true schema: type: string example: payful-official-website responses: '200': description: 成功返回实时汇率 content: application/json: schema: type: object properties: code: type: string example: '0' result: type: object properties: abroadRate: type: object properties: rate: type: number ccyPair: type: string rateDate: type: string format: date-time /api/official-website/user/rate/batch-query/{ccyPair}/{period}: post: summary: 批量汇率历史查询 | Batch Exchange Rate History description: | 用于汇率图表，按周期获取历史汇率。period 可选 hour_24、day_7、day_30。 ccyPair 格式为 {sellCcy}{buyCcy}，与 real-time-query 相反。 tags: - Rate parameters: - name: ccyPair in: path required: true schema: type: string example: USDCNH description: 币种对，格式为卖出币种+买入币种 - name: period in: path required: true schema: type: string enum: [hour_24, day_7, day_30] description: 时间周期 - name: request-system-name in: header required: true schema: type: string example: payful-official-website responses: '200': description: 成功返回历史汇率列表 content: application/json: schema: type: object properties: code: type: string example: '0' result: type: object properties: sellRate: type: array items: type: object properties: rate: type: number ccyPair: type: string rateDate: type: string sellCcy: type: string buyCcy: type: string /api/potential-user/add: post: summary: 潜在用户登记 | Add Potential User description: | 落地页/H5 注册表单提交，记录潜在用户信息。支持 UTM 等营销参数。 tags: - User parameters: - name: request-system-name in: header required: true schema: type: string example: payful-official-website requestBody: required: true content: application/json: schema: type: object required: - name - phoneNumber properties: name: type: string description: 用户姓名 phoneNumber: type: string description: 手机号或邮箱 utm_source: type: string description: UTM 来源 utm_medium: type: string utm_campaign: type: string responses: '200': description: 登记成功 content: application/json: schema: type: object properties: code: type: string example: '0' message: type: string components: schemas: StructuredData: type: object description: 官网核心结构化数据聚合 properties: organization: type: object description: 我们是谁（组织信息） properties: name: type: string example: Payful alias: type: array items: type: string description: type: string website: type: string format: uri serviceType: type: array items: type: string areaServed: type: string example: Global pricing: type: object description: 收多少钱（费用信息） properties: columns: type: array items: type: string rows: type: array items: type: object properties: businessType: type: string currencies: type: array items: type: string feeRate: type: string chargingModel: type: string note: type: string supported: type: object description: 支持什么（币种 / 产品） properties: currencies: type: array items: type: object properties: ccy: type: string example: USD country: type: string example: United States products: type: array items: type: object properties: name: type: string description: type: string integration: type: object description: 怎么接（接入方式） properties: docs: type: string format: uri example: https://www.payful.com/products/api openapi: type: string format: uri example: https://www.payful.com/api/openapi.yaml apis: type: array items: type: object properties: name: type: string method: type: string example: POST path: type: string example: /v1/payments summary: type: string requiredParams: type: array items: type: string compliance: type: object description: 合规吗（监管与牌照） properties: licenses: type: array items: type: object properties: authority: type: string type: type: string number: type: string nullable: true region: type: string level: type: string nullable: true dateModified: type: string format: date-time source: type: string description: 数据来源标记，便于调试 lang: type: string enum: [zh, en] description: 返回数据的语言 NewsPageResult: type: object properties: list: type: array items: $ref: '#/components/schemas/NewsArticle' pagination: type: object properties: current: type: integer pages: type: integer pageSize: type: integer total: type: integer NewsArticle: type: object description: 新闻文章结构（与前端 useNewsArticle 类型对齐的简化版） properties: newsId: type: string title: type: string author: type: string createAt: type: string format: date-time summary: type: string coverImgUrl: type: string format: uri content: type: string description: 富文本 HTML 内容