KARDS Decker API

主题

调用备卡 ​

备卡是卡组攻略中的推荐替换候选，字段路径为：

text
guide.reserve_recommendations

它与卡背不同：card_back_id 控制卡组展示使用的卡背图片，不表示备卡。

字段规则 ​

规则说明
类型card_id[]
数量最多 30 项；重复 ID 会被去重
卡牌来源ID 必须来自 GET /api/v1/cards
衍生卡不允许使用衍生卡（is_derived: true）
是否必须在主卡组内不需要；备卡本来就可以是卡组外候选
读取位置卡组响应的 data.guide.reserve_recommendations

1. 先找到 card_id ​

bash
curl "https://1939.giaory.xyz/api/v1/cards?q=虎式&limit=10"

从响应的 data[].card_id 取值。不要使用中文名、import_id 或图片路径代替 card_id。

2. 创建卡组时写入备卡 ​

POST /api/v1/users/:user_id/decks

bash
curl -X POST \
  "https://1939.giaory.xyz/api/v1/users/<user_id>/decks" \
  -H "Authorization: Bearer <kd_api_key>" \
  -H "Content-Type: application/json" \
  --data '{
    "deck_code": "%%1...|...;...;...;...",
    "guide": {
      "system": "装甲控制",
      "description": "以重型单位完成后期压制。",
      "reserve_recommendations": [
        "f13c7ef5-a012-4ce3-9593-cd21f4f3ee02",
        "另一张真实的-card_id"
      ]
    },
    "visibility": "private"
  }'

guide.system 是必填项。prefix、variant、description、core_cards、substitutions 与 otk_components 可按需增加。

3. 更新已有卡组的备卡 ​

PATCH /api/v1/users/:user_id/decks/:deck_id

先读取现有卡组，再修改完整的 guide 对象后提交：

bash
curl -X PATCH \
  "https://1939.giaory.xyz/api/v1/users/<user_id>/decks/<deck_id>" \
  -H "Authorization: Bearer <kd_api_key>" \
  -H "Content-Type: application/json" \
  --data '{
    "guide": {
      "prefix": "天梯",
      "system": "装甲控制",
      "variant": "低费版",
      "description": "保留原有攻略内容。",
      "core_cards": ["主卡组内的-card_id"],
      "reserve_recommendations": [
        "新的备卡-card_id"
      ],
      "substitutions": [],
      "otk_components": []
    }
  }'

PATCH 中的 guide 是完整替换

服务端不会只合并 reserve_recommendations。如果只发送 system 和备卡，其余攻略字段会恢复为空值。稳妥流程是先 GET，修改返回的 guide，再提交完整对象。

4. 读取备卡 ​

GET /api/v1/users/:user_id/decks/:deck_id

bash
curl \
  "https://1939.giaory.xyz/api/v1/users/<user_id>/decks/<deck_id>" \
  -H "Authorization: Bearer <kd_api_key>"

响应节选：

json
{
  "data": {
    "id": "<deck_id>",
    "guide": {
      "schema_version": 1,
      "system": "装甲控制",
      "reserve_recommendations": [
        "新的备卡-card_id"
      ]
    }
  },
  "meta": {
    "api_version": "v1"
  }
}

公开卡组也会在 GET /api/v1/decks/:share_slug 的相同位置返回备卡。

常见错误 ​

HTTPerror.code原因
400invalid_card_reference不是数组、超过 30 项或 ID 为空
422unknown_card_idID 不存在，或指向衍生卡
401missing_token / invalid_token缺少或使用了无效 API Key
403insufficient_scopeAPI Key 缺少 decks:write