---
title: "HTTP 接口"
description: "了解 QiCore 的 HTTP 响应、后台认证、消费者作用域和常用公共接口。"
canonical_url: "https://docs.mcent.cn/qicore/http-api"
---
# HTTP 接口

> 了解 QiCore 的 HTTP 响应、后台认证、消费者作用域和常用公共接口。

本页说明应用接入会使用的 HTTP 约定与公共入口。普通 API 使用 `/api/v1` 前缀；业务应用在自己的作用域下扩展接口。目标宿主和所用 SDK kit 必须匹配。

## 响应与请求追踪

普通成功响应包含 `data`；`dataMode`、`integrationMode`、`mock` 等附加字段按接口出现，不能作为权限依据。

```json
{
  "data": {
    "applicationKey": "notes-app",
    "ready": true
  }
}
```

经统一异常处理器返回的错误使用语义 HTTP 状态：

```json
{
  "error": {
    "code": "CONFIG_CONFLICT",
    "message": "配置已变更，请刷新",
    "requestId": "<request-id>"
  }
}
```

响应头 `X-Request-Id` 用于问题定位。维护期间的提前拒绝可能只包含 `error.code/message`，客户端应兼容缺少错误体 `requestId`，保留响应头供核查。

文件、流、渠道回调、重定向和 `/health` 使用各自协议，不强制包装成 `{ data }`。不要把错误统一改成 HTTP 200。

## 身份与请求头

<table>
<thead>
  <tr>
    <th>
      场景
    </th>
    
    <th>
      使用方式
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      平台后台
    </td>
    
    <td>
      登录后的后台 Cookie 会话；<code>
        X-Console-Portal: admin
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      租户后台
    </td>
    
    <td>
      登录后的后台 Cookie 会话；<code>
        X-Console-Portal: tenant
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      后台写操作
    </td>
    
    <td>
      在有效会话基础上提交 <code>
        X-CSRF-Token
      </code>
      
      ，并通过服务端 Origin 校验
    </td>
  </tr>
  
  <tr>
    <td>
      消费者
    </td>
    
    <td>
      <code>
        Authorization: Bearer <登录返回的 token>
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      JSON 请求
    </td>
    
    <td>
      <code>
        Content-Type: application/json
      </code>
      
      ；字段按接口白名单提交
    </td>
  </tr>
</tbody>
</table>

应用后台优先使用 `useApi('tenant')`，由 SDK 处理 Cookie、入口标识、CSRF 和错误。SSR 与客户端请求使用各自配置的 API 基址，应用不另建后台登录。

路径中的 `tenantId`、`applicationKey` 和资源编号表示目标。服务端会重新检查会话、租户成员关系、当前应用、应用权益及数据归属。

## 后台会话与应用配置

以下路径均相对 `/api/v1`：

<table>
<thead>
  <tr>
    <th>
      方法
    </th>
    
    <th>
      路径
    </th>
    
    <th>
      用途
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      POST
    </td>
    
    <td>
      <code>
        /admin/auth/login
      </code>
    </td>
    
    <td>
      使用 <code>
        username/password/portal
      </code>
      
       登录，<code>
        portal
      </code>
      
       为 <code>
        admin
      </code>
      
       或 <code>
        tenant
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        /admin/auth/me
      </code>
    </td>
    
    <td>
      读取当前后台会话、权限及 CSRF 信息
    </td>
  </tr>
  
  <tr>
    <td>
      POST
    </td>
    
    <td>
      <code>
        /admin/auth/logout
      </code>
    </td>
    
    <td>
      退出当前后台会话
    </td>
  </tr>
  
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        /admin/tenant-entry?tenantId=<tenant-id>
      </code>
    </td>
    
    <td>
      读取服务端核验后的租户入口和可访问应用
    </td>
  </tr>
  
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        /admin/tenants/:tenantId/apps/:applicationKey/config
      </code>
    </td>
    
    <td>
      读取应用配置与配置版本
    </td>
  </tr>
  
  <tr>
    <td>
      PUT
    </td>
    
    <td>
      <code>
        /admin/tenants/:tenantId/apps/:applicationKey/config
      </code>
    </td>
    
    <td>
      保存应用配置，输入 <code>
        { config, version }
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      按应用声明
    </td>
    
    <td>
      <code>
        /admin/tenants/:tenantId/apps/:applicationKey/<path>
      </code>
    </td>
    
    <td>
      分发到应用后台处理器
    </td>
  </tr>
</tbody>
</table>

应用配置读写分别要求 `settings.read`、`settings.write`。配置 `version` 与应用开通状态的版本不同；发生 `CONFIG_CONFLICT` 后重新读取，不覆盖其他操作者的修改。

平台身份、租户身份和代登录有各自限制。代登录不能修改目标账号的个人资料或凭据，不把平台登录 Cookie 当成消费者 token。

## 消费者认证

<table>
<thead>
  <tr>
    <th>
      方法
    </th>
    
    <th>
      路径
    </th>
    
    <th>
      主要输入
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        /consumer/auth/settings
      </code>
    </td>
    
    <td>
      查询参数 <code>
        tenantId/applicationKey
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      POST
    </td>
    
    <td>
      <code>
        /consumer/auth/login
      </code>
    </td>
    
    <td>
      <code>
        tenantId/applicationKey/account/password
      </code>
      
      ，可选 <code>
        loginType/consent
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      POST
    </td>
    
    <td>
      <code>
        /consumer/auth/register
      </code>
    </td>
    
    <td>
      <code>
        tenantId/applicationKey/account/password
      </code>
      
      ，按要求提供 <code>
        consent
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        /consumer/auth/wechat/settings
      </code>
    </td>
    
    <td>
      查询参数 <code>
        tenantId/applicationKey
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      POST
    </td>
    
    <td>
      <code>
        /consumer/auth/wechat/login
      </code>
    </td>
    
    <td>
      <code>
        tenantId/applicationKey/code
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      POST
    </td>
    
    <td>
      <code>
        /consumer/auth/sms/send
      </code>
    </td>
    
    <td>
      由短信认证流程提交站点、应用、手机号及用途
    </td>
  </tr>
  
  <tr>
    <td>
      POST
    </td>
    
    <td>
      <code>
        /consumer/auth/sms/login
      </code>
    </td>
    
    <td>
      由短信认证流程提交站点、应用、手机号和验证码
    </td>
  </tr>
</tbody>
</table>

账号登录的 `loginType` 为 `account`、`phone` 或 `auto`，默认 `auto`。密码注册账号为 3–64 位英文字母或数字，密码为 6–128 字符；登录的具体可用方式由站点配置决定。

`consent` 可包含 `terms/privacy` 的正整数版本号，值来自当前站点公布的协议。不要提交随意版本或自动替用户同意协议。

登录成功的共同 `data` 字段为 `token/tenantId/applicationKey/userId/expiresAt`。`role` 不保证所有登录方式都返回，`authProvider/authAppId` 是渠道相关字段。消费者把原始 token 作为 Bearer 值发送，存储与恢复会话须同时限定租户和应用。微信、短信、公众号流程优先使用[客户端 SDK](https://docs.mcent.cn/qicore/client-sdk)。

## 消费者公共接口

下表以 `C = /api/v1/apps/:applicationKey` 表示已绑定应用的消费者基址。除认证入口外，以下调用需要有效消费者 token。

<table>
<thead>
  <tr>
    <th>
      方法
    </th>
    
    <th>
      路径
    </th>
    
    <th>
      用途
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      DELETE
    </td>
    
    <td>
      <code>
        C/session
      </code>
    </td>
    
    <td>
      退出当前消费者会话
    </td>
  </tr>
  
  <tr>
    <td>
      GET / PUT
    </td>
    
    <td>
      <code>
        C/profile
      </code>
    </td>
    
    <td>
      读取或保存本人公共资料
    </td>
  </tr>
  
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        C/wallet
      </code>
    </td>
    
    <td>
      读取积分、余额、版本及单位
    </td>
  </tr>
  
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        C/wallet/:asset/records
      </code>
    </td>
    
    <td>
      分页读取资产流水
    </td>
  </tr>
  
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        C/wallet/:asset/records/:id
      </code>
    </td>
    
    <td>
      读取本人资产流水详情
    </td>
  </tr>
  
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        C/member-levels
      </code>
    </td>
    
    <td>
      读取本人会员等级展示
    </td>
  </tr>
  
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        C/growth-records
      </code>
    </td>
    
    <td>
      分页读取本人成长记录
    </td>
  </tr>
  
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        C/decoration
      </code>
    </td>
    
    <td>
      读取当前应用已发布装修
    </td>
  </tr>
  
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        C/recharge/catalog
      </code>
    </td>
    
    <td>
      读取可用充值方案
    </td>
  </tr>
  
  <tr>
    <td>
      POST / GET
    </td>
    
    <td>
      <code>
        C/recharge/orders
      </code>
    </td>
    
    <td>
      创建或查询本人的充值订单
    </td>
  </tr>
  
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        C/recharge/orders/by-request/:requestKey
      </code>
    </td>
    
    <td>
      按原请求键核查充值创建结果
    </td>
  </tr>
  
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        C/orders
      </code>
    </td>
    
    <td>
      查询本人订单
    </td>
  </tr>
  
  <tr>
    <td>
      POST
    </td>
    
    <td>
      <code>
        C/orders/:id/pay
      </code>
    </td>
    
    <td>
      发起服务端核验的支付
    </td>
  </tr>
  
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        C/orders/:id/payment
      </code>
    </td>
    
    <td>
      查询支付状态
    </td>
  </tr>
  
  <tr>
    <td>
      POST
    </td>
    
    <td>
      <code>
        C/orders/:id/reconcile
      </code>
    </td>
    
    <td>
      请求服务端核查支付结果
    </td>
  </tr>
</tbody>
</table>

`asset` 当前为 `points` 或 `balance`。钱包流水查询支持 `page`、`pageSize` 和 `type`；默认每页 20 条，上限 50 条，服务端可能将页码夹到有效范围。筛选类型为 `all/recharge/spend/return/gift/adjust/refund`。

资料保存输入为 `version/nickname/avatar`，可选 `phone/email/gender`；`gender` 为 `unknown/male/female`。头像由公共服务规范化，`avatar` 可为合法头像输入或 `null`。资料版本冲突返回 `PROFILE_CONFLICT`。

```http
GET /api/v1/apps/notes-app/wallet HTTP/1.1
Authorization: Bearer <consumer-token>
Accept: application/json
```

不要为新应用使用无应用前缀的旧兼容地址，也不要把另一个应用的 token 放进当前路径。

## 公开读取与扩展接口

`/public/site` 提供站点品牌信息；`/public/client/decoration`、`/public/client/member-levels` 等提供面向客户端的已发布内容。公开读取仍按对应接口核验租户、应用及可用状态，不返回私有钱包、密钥或后台会话。

新业务 API 在应用声明的 `consumerPaths` 下分发。两类处理器的路径段都已先去掉 `/api/v1`：后台收到如 `['admin', 'tenants', tenantId, 'apps', applicationKey, 'summary']`；消费者继续移除 `apps/:applicationKey`，收到如 `['notes', id]`。插件有独立路由与权限规则，见[插件开发](https://docs.mcent.cn/qicore/plugin-development)。

## 充值创建请求

先读取 `C/recharge/catalog`，从实际响应取得配置 version 和可用方案 ID。`POST C/recharge/orders` 接受三种互斥请求体：

<table>
<thead>
  <tr>
    <th>
      kind
    </th>
    
    <th>
      此类型的业务字段
    </th>
    
    <th>
      共同字段
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        points_recharge
      </code>
    </td>
    
    <td>
      packageId：目录中的积分套餐 UUID
    </td>
    
    <td>
      version：正整数配置版本；requestKey：稳定 UUID
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        balance_recharge
      </code>
    </td>
    
    <td>
      tierId：目录中的余额档位 UUID
    </td>
    
    <td>
      同上
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        balance_custom
      </code>
    </td>
    
    <td>
      amountCents：整数分金额
    </td>
    
    <td>
      同上
    </td>
  </tr>
</tbody>
</table>

```json
{
  "kind": "points_recharge",
  "packageId": "11111111-1111-4111-8111-111111111111",
  "version": 3,
  "requestKey": "22222222-2222-4222-8222-222222222222"
}
```

这些 ID 和版本仅展示类型，调用时使用当前目录返回的真实方案及版本。requestKey 为同次用户确认生成一次，网络重试沿用，不每次重新生成。

自定义余额请求如下，示例 `1000` 表示 10 元：

```json
{
  "kind": "balance_custom",
  "amountCents": 1000,
  "version": 3,
  "requestKey": "33333333-3333-4333-8333-333333333333"
}
```

自定义充值还须满足当前目录的 customEnabled/minCents/maxCents，后端总金额范围为 1—100000000 分。未配置目录或没有可用方案时不构造订单。响应返回订单 DTO，含编号、类型、名称、金额、币种、状态、时间和购买快照；balance_custom 请求生成的订单类型为 balance_recharge。

同键异内容返回 `RECHARGE_REQUEST_CONFLICT`，目录版本变化返回 `RECHARGE_CONFLICT`。结果未知时先按原 requestKey 查询 `C/recharge/orders/by-request/:requestKey`；已有订单继续使用，返回 null 后才按原请求体和原键决定重试。

## 支付请求体

先读取 `GET C/orders/:id/methods?client=mini`，client 可为 mini/official/h5，缺省为 h5，按实际终端选择。`POST C/orders/:id/pay` 的最小请求体如下，金额和商户身份均由服务端从原订单核对：

<table>
<thead>
  <tr>
    <th>
      方式
    </th>
    
    <th>
      请求体
    </th>
    
    <th>
      前置
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      默认微信 JSAPI
    </td>
    
    <td>
      <code>
        {}
      </code>
    </td>
    
    <td>
      当前小程序或公众号微信身份，AppID 相符
    </td>
  </tr>
  
  <tr>
    <td>
      微信 H5
    </td>
    
    <td>
      <code>
        { "channel": "h5" }
      </code>
    </td>
    
    <td>
      已绑定的 HTTPS H5 入口与合法请求上下文；微信内浏览器使用公众号方式
    </td>
  </tr>
  
  <tr>
    <td>
      余额
    </td>
    
    <td>
      <code>
        { "provider": "balance" }
      </code>
    </td>
    
    <td>
      当前端允许、余额足够且订单满足应用限制
    </td>
  </tr>
  
  <tr>
    <td>
      支付宝 H5
    </td>
    
    <td>
      <code>
        { "provider": "alipay", "channel": "h5" }
      </code>
    </td>
    
    <td>
      普通 H5 浏览器和已配置的支付宝收银台
    </td>
  </tr>
  
  <tr>
    <td>
      微信虚拟支付
    </td>
    
    <td>
      <code>
        { "provider": "wechat-virtual" }
      </code>
    </td>
    
    <td>
      受支持的小程序身份、公共充值订单及已发布商品配置
    </td>
  </tr>
</tbody>
</table>

默认微信分支只允许可选 channel，不发送 `{ "provider": "wechat" }`。各分支严格校验字段，不能追加客户端金额、用户、商户或伪造支付结果。

响应按状态和渠道提供 orderId/state 及相关 paymentId、支付调用参数或跳转地址，不把全部渠道当成同一 DTO。优先使用客户端 SDK 的 payOrder/queryOrder，继续核对原订单和当前身份。

客户端调用结束后查询服务端结果；到账、退款和权益发放由可信服务端状态决定。

## 冲突、幂等与未知结果

<table>
<thead>
  <tr>
    <th>
      状态
    </th>
    
    <th>
      客户端处理
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      401
    </td>
    
    <td>
      会话缺失或失效，回到对应身份的登录流程
    </td>
  </tr>
  
  <tr>
    <td>
      403
    </td>
    
    <td>
      当前范围或权限不可用，重新核验入口和授权
    </td>
  </tr>
  
  <tr>
    <td>
      404
    </td>
    
    <td>
      路径或当前范围内资源不存在
    </td>
  </tr>
  
  <tr>
    <td>
      409
    </td>
    
    <td>
      版本、状态或请求键冲突，先读取原结果
    </td>
  </tr>
  
  <tr>
    <td>
      429
    </td>
    
    <td>
      按接口提示等待后重试
    </td>
  </tr>
  
  <tr>
    <td>
      5xx / 网络超时
    </td>
    
    <td>
      结果可能未知，先查询任务、订单或原请求状态
    </td>
  </tr>
</tbody>
</table>

业务幂等字段可能叫 `requestId` 或 `requestKey`，以具体接口为准；它们与用于诊断的响应请求编号用途不同。重试保留原业务键和原输入；同键异内容不能当作新操作。

支付、退款及资产写入必须遵守[存储与事务](https://docs.mcent.cn/qicore/storage-and-transactions)中的持久状态、共享事务和原来源规则。


## Sitemap

See the full [sitemap](https://docs.mcent.cn/sitemap.md) for all pages.