agent-foundation/docs/ngp-performance-api.md

NGP 业绩合计接口

请求

POST /api/ngp/performance/total

{
  "startDate": "2026-09-01",
  "endDate": "2026-09-06",
  "storeName": "兰教练（抖店）"
}

• startDate、endDate 必填，包含首尾日期，最多 31 天。
• storeName 选填；不传或传空字符串时查询全部网点。多个网点可用逗号分隔。
• 后端通过 ngp.api.bill.getSaleOrderList 查询业绩，并固定传入 postStateList=[800]（财务核算成功）和 refundType=0（无需退款）。 调用方不需要传这两个参数，也不能覆盖。
• 该 NGP 方法需要在开放平台为当前应用开通“往来单位数据授权”。若未授权， 接口会直接返回 NGP 的授权错误，不会降级为未筛选的全量数据。
• 业绩缓存记录固定筛选规则的版本。首次部署本规则后，旧的“全部状态”缓存会自动失效并 重新拉取，无需手工清空缓存表；月度每周统计也会使用同一份已筛选缓存。
• NGP 每页最多查询 200 条；服务会读取全部页面后返回合计。

响应

{
  "success": true,
  "startDate": "2026-09-01",
  "endDate": "2026-09-06",
  "storeName": "全部网点",
  "totalAmount": 4908668.47,
  "formattedTotal": "4,908,668.47",
  "currency": "CNY"
}

缓存未准备好时返回 HTTP 202，并在后台按天汇总：

{
  "success": false,
  "status": "PROCESSING",
  "message": "后台正在汇总 6 天的数据，请稍后重试",
  "pendingDays": 6,
  "retryAfterSeconds": 10
}

调用方应按照 retryAfterSeconds 重新发送相同请求。完成后的每日各网点金额保存到 MySQL 表 ngp_performance_daily_total，日期完成状态保存到 ngp_performance_daily_status。相同日期的并发请求只触发一次后台任务。

部署配置

NGP 的 AppKey、AppSecret、access token 和 refresh token 位于 application.yml 的 foundation.ngp 节点。access token 失效时服务会使用 refresh token 自动刷新，并在当前 进程内保存新 token。配置文件含明文凭据，只能保存在私有仓库并限制读取权限。

历史日期结果默认缓存 24 小时，包含今天的结果默认缓存 10 分钟。