awardwallet

AwardWallet 技能

通过 AwardWallet Business Account Access API 查询忠诚度计划余额、精英等级和交易历史。

来源： business.awardwallet.com — 需要 Business 账户。

身份验证

在 .env 文件中设置以下内容：

• AWARDWALLET_API_KEY — 从 https://business.awardwallet.com/profile/api 获取
• AWARDWALLET_USER_ID — 已连接用户 ID。可通过下方的 List Connected Users 端点查找。

所有请求都使用 X-Authentication 标头。

首次设置时的注意事项： AwardWallet 会对 Business API 密钥实施 IP 允许列表限制。如果未将你的 IP 加入允许列表，每次调用都会返回 {"error": "access_denied", "code": "IP_DENIED"}。开始排查问题前，请先将 IP 加入允许列表。

• 添加允许列表的位置： https://business.awardwallet.com/profile/api
• 查找你的 IP： curl ifconfig.me
• 多个 IP： 家庭、办公室、热点、VPN 出口节点以及旅行途中的所有地点都需要分别添加。若使用稳定的住宅 ISP，最简单的做法是将 /24 网段加入允许列表。

错误特征

响应	含义	修复方法
{"error": "access_denied", "code": "IP_DENIED"}	IP 不在允许列表中	在开发者门户将当前 IP 加入允许列表
Unauthorized / 401	密钥错误	重新生成密钥
accounts 数组为空	用户 ID 错误或没有连接	验证 AWARDWALLET_USER_ID

API 基础地址

https://business.awardwallet.com/api/export/v1

快速开始：获取所有余额

curl -s -H "X-Authentication: $AWARDWALLET_API_KEY" \
  "https://business.awardwallet.com/api/export/v1/connectedUser/$AWARDWALLET_USER_ID" | jq '.accounts'

响应字段

每个账户对象包含：

字段	描述
accountId	用于深入查询的唯一 ID
code	提供方代码（例如 "united"、"chase"、"amex"）
displayName	易读名称（例如 "United Airlines (MileagePlus)"）
kind	类别：航空公司、酒店、信用卡等
balance	格式化的余额字符串
balanceRaw	数值余额
properties	包含状态、账户号码、到期时间等信息的数组
history	最近 10 笔交易（调用 /account/{id} 获取完整历史记录）
errorCode	1 = 更新成功，2 = 凭证无效等

实用的 jq 筛选器

以下所有筛选器都假设 curl 输出已通过管道传入。将 ... 替换为上方的完整 curl 命令。

# Just airline balances with status
... | jq '[.accounts[] | select(.kind == "Airlines") | {name: .displayName, balance: .balanceRaw, status: ((.properties // [])[] | select(.kind == 3) | .value) // "none"}]'

# Just hotel balances with status
... | jq '[.accounts[] | select(.kind == "Hotels") | {name: .displayName, balance: .balanceRaw, status: ((.properties // [])[] | select(.kind == 3) | .value) // "none"}]'

# Just credit card / transferable points
... | jq '[.accounts[] | select(.kind == "Credit Cards") | {name: .displayName, balance: .balanceRaw}]'

# All balances sorted by amount (descending), non-zero only
... | jq '[.accounts[] | {name: .displayName, kind: .kind, balance: .balanceRaw} | select(.balance > 0)] | sort_by(-.balance)'

# Elite status across all programs
... | jq '[.accounts[] | {name: .displayName, status: ((.properties // [])[] | select(.kind == 3) | .value) // null} | select(.status != null)]'

# Accounts with errors (need password update, etc.)
... | jq '[.accounts[] | select(.errorCode != 1) | {name: .displayName, error: .errorCode}]'

# Combined summary for trip planning (airlines + transferable points, non-zero, sorted)
... | jq '[.accounts[] | select((.kind == "Airlines" or .kind == "Credit Cards") and .balanceRaw > 0) | {name: .displayName, kind: .kind, balance: .balanceRaw, status: ((.properties // [])[] | select(.kind == 3) | .value) // null}] | sort_by(-.balance)'

深入查询：完整账户历史记录

获取完整交易历史记录（不止最近 10 笔）：

curl -s -H "X-Authentication: $AWARDWALLET_API_KEY" \
  "https://business.awardwallet.com/api/export/v1/account/{accountId}" | jq '.account[0].history'

旅行时间线

获取已连接用户保存的行程：

curl -s -H "X-Authentication: $AWARDWALLET_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"start": "2026-01-01", "end": "2027-01-01"}' \
  "https://business.awardwallet.com/api/export/v1/travel-timeline/$AWARDWALLET_USER_ID" | jq '.itineraries'

列出所有受支持的提供方

curl -s -H "X-Authentication: $AWARDWALLET_API_KEY" \
  "https://business.awardwallet.com/api/export/v1/providers/list" | jq '.'

账户属性类型

解析 properties 数组时，以下 kind 值为标准化值：

类型	含义
1	账户号码
2	到期时间
3	精英等级
4	终身积分
5	入会时间
6	即将过期的余额
7	年初至今的里程/积分
8	年初至今的航段数
9	下一精英等级
10	升至下一级所需积分
11	升至下一级所需航段数
12	姓名
13	最近活动
14	获取下一项奖励所需积分
15	状态到期时间
16	保留等级所需积分
17	保留等级所需航段数
18	联盟精英等级
19	状态里程/积分

错误代码

代码	含义
0	从未更新
1	成功
2	凭证无效
3	已锁定
4	提供方错误或需要用户操作
5	AwardWallet 已禁用该提供方
6	解析失败
7	缺少密码
8	已禁用以防止账户锁定
9	成功，但有警告
10	需要安全问题答案
11	超时

工作流：行程规划摘要

规划行程时，运行以下工作流：

1. 获取所有账户
2. 筛选航空公司和信用卡（可转让积分）
3. 清晰地显示摘要：计划名称、余额、精英等级
4. 标记可能需要更新的错误账户
5. 对照目的地的转点合作伙伴

备注

• 用户／成员详情响应中的历史记录最多显示 10 条。请使用 /account/{id} 查看完整历史记录。
• balanceRaw 是数值。balance 使用逗号分隔格式。
• 已连接的用户可以自行控制访问级别。如果数据看起来不完整，他们可能限制了共享内容。
• Capital One 等项目支持子账户，即一个登录账号对应多张卡。请检查 subAccounts 数组。