邀请了多少人、赚了多少佣金？怡途Claw 代理分销业绩 API 查询实战 - Blog

邀请了多少人、赚了多少佣金？本文用怡途Claw 的 /api/app/agents 接口，把代理身份、邀请码、被邀请人消费明细查清楚，附 summary 里 totalInvitedUsers 和 filteredInvitedUsers 对不上的原因，以及佣金费率不在响应里的坑。

邀请了多少人、赚了多少佣金？本文用怡途Claw 的 /api/app/agents 这组接口，把"自己是不是代理、邀请码多少、邀了几个人、被邀请人消费了多少"查清楚，附 summary 里 totalInvitedUsers 和 filteredInvitedUsers 对不上的原因。

前面讲的都是"花钱"和"用"的接口--301 计费查询、306 实例启停、309 支付下单。但 /api/app/* 里还有一类反过来的：代理分销，你邀请别人来用怡途Claw，别人消费你拿佣金。这套查询挂在 app/agents 下，就两个接口：一个看自己的代理身份，一个看业绩明细。代码在 src/users/services/agent.service.ts，controller 是 app-agents.controller.ts。

实际接进来你会碰到这些问题

我是不是代理？我的邀请码是多少？已经邀了几个人？
我邀请的人这月消费了多少、我能拿多少佣金？
想看某个具体被邀请人的消费明细，怎么按人筛？
业绩能按时间段筛吗？上个月和这个月怎么对比？
我不是代理，调业绩接口会怎样？代理身份被停用了呢？
邀请我的人是谁？我挂在哪个代理下面？
summary 里的 totalInvitedUsers 和 filteredInvitedUsers 为啥对不上？

两个接口都要带 Authorization: Bearer <token>（307 讲过怎么拿）。

先查代理身份：GET /api/app/agents/me

调任何业绩接口之前，先确认自己是不是代理、邀请码是什么。这个接口对所有人开放（只要登录），不是代理也能调，只是返回 isAgent: false。

curl "https://www.yitukeji.cn/api/app/agents/me" \
  -H "Authorization: Bearer <你的token>"

{
  "success": true,
  "data": {
    "isAgent": true,
    "isAgentEnabled": true,
    "inviteCode": "YT8K2A",
    "invitedUsersCount": 17,
    "invitedBy": {
      "agentUserId": "u_xxx",
      "inviteCodeUsed": "YT3F9B",
      "agentName": "张三",
      "agentPhone": "138****0512",
      "boundAt": "2026-06-10T03:20:00.000Z"
    }
  }
}

几个要点：

isAgent 是"有没有代理档案"（Boolean(profile)），isAgentEnabled 是"档案在没在用"（profile.isEnabled）。两个都为 true 才是生效代理。被管理员停用的代理 isAgent=true, isAgentEnabled=false，这时调业绩接口会 403。
inviteCode 是你的专属邀请码，别人注册时填这个码就绑到你名下。不是代理时为 null。
invitedUsersCount 是你已经绑定成功的被邀请人数（按 agentUserId = 自己 数 binding 记录）。不是代理时为 0。
invitedBy 是"谁邀请的我"。如果你是被人邀请来的，这里返回上家代理的 userId、你当时用的邀请码、上家名字、脱敏后的手机号（maskPhone，中间四位打星）和绑定时间。你不是被邀请来的就是 null。
注意 invitedBy 里的 agentPhone 是脱敏的，但下面业绩接口里被邀请人的手机号是明文返回的--因为代理要看自己下线的联系方式。两个接口策略不同，别混。

业绩总览+明细：GET /api/app/agents/performance

代理身份确认了，就调这个看业绩。支持按人、按时间段筛，分页。

curl "https://www.yitukeji.cn/api/app/agents/performance?page=1&pageSize=20&startDate=2026-07-01&endDate=2026-07-31" \
  -H "Authorization: Bearer <你的token>"

参数：

参数	默认	说明
`page`	1	页码，最小 1
`pageSize`	20	每页条数，最小 1，上限 100
`invitedUserId`	-	按某个被邀请人筛
`startDate`	-	起始日期（按支付时间 paidAt 筛）
`endDate`	-	结束日期（自动按当天末尾 23:59:59）

返回（结构较大，分三块看）：

{
  "success": true,
  "data": {
    "agent": {
      "userId": "u_me",
      "inviteCode": "YT8K2A",
      "isEnabled": true
    },
    "summary": {
      "totalInvitedUsers": 17,
      "filteredInvitedUsers": 17,
      "paidInvitedUsers": 9,
      "totalInstancePurchaseAmount": 2380.00,
      "totalRechargeAmount": 1500.00,
      "totalAmount": 3880.00,
      "instancePurchaseCount": 14,
      "rechargeCount": 11
    },
    "invitees": {
      "items": [
        {
          "userId": "u_a1",
          "phone": "13900001111",
          "name": "李四",
          "registeredAt": "2026-06-12T01:00:00.000Z",
          "boundAt": "2026-06-12T01:05:00.000Z",
          "instancePurchaseAmount": 299.00,
          "rechargeAmount": 100.00,
          "totalAmount": 399.00,
          "instancePurchaseCount": 1,
          "rechargeCount": 1,
          "lastPaidAt": "2026-07-18T08:00:00.000Z"
        }
      ],
      "pagination": {
        "page": 1,
        "pageSize": 20,
        "total": 17,
        "totalPages": 1
      }
    },
    "filters": {
      "startDate": "2026-07-01T00:00:00.000Z",
      "endDate": "2026-07-31T23:59:59.999Z"
    }
  }
}

summary 字段怎么看

summary 是业绩总览，但里头有个容易踩的坑：不是所有字段都受筛选影响。

totalInvitedUsers：你名下的全部被邀请人数，不受 startDate/endDate/invitedUserId 筛选影响。不管你怎么筛，这个数始终是总邀请数。
filteredInvitedUsers：受筛选影响的被邀请人数。不传任何筛选时等于 totalInvitedUsers；传了日期段或 invitedUserId，就只数符合条件的。
paidInvitedUsers：在筛选范围内有消费（totalAmount > 0）的被邀请人数。这是衡量"有效下线"的关键数。
totalInstancePurchaseAmount：筛选范围内，被邀请人购买套餐/实例的累计金额。
totalRechargeAmount：筛选范围内，被邀请人充值余额的累计金额。
totalAmount：上面两者之和，筛选范围内的总消费。
instancePurchaseCount / rechargeCount：对应的笔数。

所以开头那个问题--"totalInvitedUsers 和 filteredInvitedUsers 为啥对不上"--答案就是：前者是历史总邀请数（不筛），后者是当前筛选条件下的邀请数。你传了 startDate=2026-07-01，7 月之后才绑定的下线会进 filteredInvitedUsers，但 7 月之前绑定的老下线只算进 totalInvitedUsers。想看"这个月新邀了多少人"，看 filteredInvitedUsers；想看"一共邀了多少人"，看 totalInvitedUsers。

金额只统计已支付订单

aggregatePaymentsByUsers 里有个硬条件：payment.status = PAID。也就是说：

创建了订单但没付的（pending）-- 不算。
付了又退款的 -- 退款金额没有从总额里扣（只看 paidAt 时点的 PAID 订单）。如果业务上有退款，这里看到的金额可能偏高，需要拿退款记录单独对。
订单类型 RECHARGE（充值）算进 rechargeAmount，其余类型（套餐/实例购买）算进 instancePurchaseAmount。totalAmount 是两类之和。

lastPaidAt 是这个被邀请人最近一次支付时间（MAX(paidAt)），用来判断下线还活不活跃。

佣金怎么算

注意：这个接口返回的是被邀请人的消费金额，不是你的佣金。响应里没有 commission 或 rate 字段。佣金 = 平台配置的费率 × 对应金额，费率在管理后台按代理或按全局配置，不在这个查询接口里暴露。所以你拿到 totalAmount=3880 后，要知道实际到手多少，得乘以你那档费率（比如 10% 就是 388）。接前端时别直接把 totalAmount 当佣金显示给代理看，会被投诉。

错误情况

不是代理调 /performance：403 当前用户不是代理商。
是代理但被停用：403 代理商已停用。
startDate 晚于 endDate：400 开始时间不能晚于结束时间。
/me 不会报错，非代理也返回 isAgent: false。

串一条排查线

先调 /me 确认 isAgent && isAgentEnabled，拿到 inviteCode 和 invitedUsersCount。
不带筛选调 /performance，看 summary.totalAmount 总量级和 paidInvitedUsers 有效下线数。
想看某个下线贡献多少，传 invitedUserId 精确到人，看 invitees.items 里他的 totalAmount 和 lastPaidAt。
想看某月业绩，传 startDate/endDate，看 filteredInvitedUsers 和筛选后的 totalAmount--别拿 totalInvitedUsers 当月度数。
算实际佣金，拿 totalAmount × 你那档费率，别把响应里的金额直接当佣金。

这套和 309 那篇支付下单是同一条钱链的两头：309 讲被邀请人怎么下单付钱，这篇讲代理怎么查这些钱汇总到自己名下。