/api/v1/customers/list按资料、标签、套餐和状态筛选客户，使用 offset 与 limit 分页。
按资料、标签、套餐和状态筛选客户，使用 offset 与 limit 分页。
customers:readcurl -X POST "$GROOVE_BASE_URL/api/v1/customers/list" \ -H "Authorization: Bearer $GROOVE_SECRET_KEY" \ -H "X-Groove-Project: $GROOVE_PROJECT_ID" \ -H "X-Groove-Environment: sandbox" \ -H "Content-Type: application/json" \ -d '{ "limit": 20, "offset": 0}'响应选项卡列出字段类型，不是响应示例；实际值由客户状态决定。
searchstring可选本次操作的 search 值，类型和约束见字段标注。
maxLength: 200 · default: ""
tagstring可选本次操作的 tag 值，类型和约束见字段标注。
maxLength: 40 · default: ""
planIduuid | ""可选当前 App／环境内会员商品的 products.id；与 versionId 一起限定会员持有及排期。
default: ""
versionIduuid | ""可选不可变 product_versions.id，可筛选历史版本。
default: ""
holdingStatusenum可选按已验证会员周期与已确认下期排期筛选：active、scheduled、expired、unavailable；none 表示当前没有生效会员。
default: ""
"""active""scheduled""expired""unavailable""none"
membershipStatusenum可选按当前会员记录筛选：active、trial、past_due、ended；空字符串表示全部。
default: ""
"""active""trial""past_due""ended"
createdFromdate-time | ""可选本次操作的 createdFrom 值，类型和约束见字段标注。
default: ""
createdUntildate-time | ""可选本次操作的 createdUntil 值，类型和约束见字段标注。
default: ""
offsetinteger可选从第几条记录开始，初始为 0。
min: 0 · max: 100000 · default: 0
limitinteger可选一页返回的最大记录数量，受契约上限限制。
min: 1 · max: 100 · default: 50
成功响应包含 requestId 和 scope。结合实际业务状态或 accepted 判断操作结果；可选字段不可用时省略。
requestIduuid必填服务端生成的 HTTP 请求 UUID，排查请求时提供这个值。
scopeobject必填响应实际所属的 App 和环境。Header 只能核对，不能切换 Key 范围。
projectIdstring必填凭据绑定的 App ID。
minLength: 1
environmentenum必填独立数据范围：sandbox 或 live。
"sandbox""live"
customersarray必填本次操作的 customers 值，类型和约束见字段标注。
iduuid必填本次操作的 id 值，类型和约束见字段标注。
externalUserIdstring | null必填你服务端登录系统的稳定用户 ID；不是邮箱。按邮箱预建、尚未认领的客户为 null。
namestring必填客户或对象的展示名称，不作为身份唯一键。
maxLength: 80
emailemail | ""必填客户联系邮箱；不用于自动合并客户身份。
attributesobject必填最多 128 个键，每键 1–128 字符，总 JSON ≤64 KiB；值可为嵌套 JSON，单值最多 20 层和 10,000 个节点。禁止保留字段；null 是属性值，删除使用 removeAttributes。标签保存在 attributes.tags，更新使用 tagChanges。
revisioninteger必填读取资料时返回的版本号；更新使用它检测并发修改。
min: 0 · max: 9007199254740991
createdAtdate-time必填记录创建时的 ISO 8601 UTC 时间。
updatedAtdate-time必填记录最后更新时的 ISO 8601 UTC 时间。
hasMoreboolean必填是否还有下一页；使用返回游标或对应分页参数继续查询。
totalinteger | null必填本次操作的 total 值，类型和约束见字段标注。
evaluatedAtdate-time必填服务端计算这份状态的 UTC 时间。
| 错误码 | 处理方式 |
|---|---|
| UNAUTHENTICATED | 核对 Key，或将过期客户 Token 重新签发一次。 |
| FORBIDDEN | 核对当前 Key 权限与客户访问范围。 |
| INVALID_REQUEST | 检查字段类型、UUID、十进制字符串和互斥字段。 |
| SCOPE_MISMATCH | 使用凭据绑定的 App 和环境。 |
常见失败
UNAUTHENTICATED
FORBIDDEN
INVALID_REQUEST
SCOPE_MISMATCH