SCAPI 接入文档

TRY

接口测试与 cURL 生成

选择接口和参数，页面会自动完成需要的 session 与 ticket 流程。

额度模式接口资源正在载入可用资源关键词页码每页数量

完整测试预计消耗 6 CostGET /api/ships?page=1&page_size=20

匿名测试会在当前页面内存中复用 session；首次调用包含 session 与 ticket 成本，后续调用只需 ticket。

等待请求

-- ms

Limit --Remaining --Cost --Reset --

选择接口后点击“运行测试”，响应 JSON 将显示在这里。

可执行 cURL 脚本 · curl + jq

B2B

合作商与用户接入

API key 只负责分配身份，identity 才是读取 SCAPI 数据的凭据。

首次开通 API key

API key 由 SCAPI 管理方离线签发，不存在公开的“创建 API key”端口。明文 key 只交付合作商一次；SCAPI 配置只保存 SHA-256。

SCAPI 管理方 · PowerShell 生成 key 与哈希

$key = [Convert]::ToBase64String(
  [Security.Cryptography.RandomNumberGenerator]::GetBytes(32)
)
$hash = [Convert]::ToHexString(
  [Security.Cryptography.SHA256]::HashData(
    [Text.Encoding]::UTF8.GetBytes($key)
  )
).ToLowerInvariant()

"API key: $key"
"SHA-256: $hash"

SCAPI/Partners.json · 只写入 SHA-256

{
  "partners": [{
    "id": "partner-a",
    "api_key_sha256": "<64-character-sha256>",
    "quota_30m": 3600,
    "identity_quota_per_minute": 120,
    "identity_max_ttl_seconds": 86400,
    "enabled": true
  }]
}

交付规则将明文 API key 通过安全渠道交给合作商后端负责人；将 SHA-256 写入 SCAPI 配置。合作商遗失 key 时应重新签发并替换哈希，无法从 SCAPI 状态中恢复明文。

01

用户

先访问合作商网站并完成登录。用户不接触合作商 API key，只接收属于自己的 identity 与一次性返回的 token。

02

合作商后端

验证用户后决定有效期和额度，使用保存在服务端的 API key 创建或撤销 identity。API key 不能读取数据。

03

SCAPI

从合作商 30 分钟额度窗口预留 grant，校验用户 identity，并按每次数据请求的 Cost 消耗用户额度。

从用户访问合作商网站开始

1
用户请求合作商网站
合作商自行完成登录、订阅状态或权限检查。
2
合作商决定 grant
为该用户选择 identity 名称、有效秒数和独立额度。
3
合作商创建 identity
合作商后端使用 x-scapi-api-key 调用 POST /identity。
4
安全交付用户凭据
合作商把返回的完整 identity 与 token 交给用户；token 只在创建响应中出现一次。
5
用户直连 SCAPI
用户携带两个 identity headers 请求 /api/*，不再需要 API key、session 或 ticket。
6
续留、到期或撤销
跨窗口自动续留剩余额度；到期自动失效，合作商也可提前撤销并回收当前窗口预留。

运行时边界x-scapi-api-key 只能保存在合作商后端。不得写入网页 JavaScript、移动端包、桌面客户端或返回给终端用户。

1 · 合作商后端创建 identity

curl --request POST "$SCAPI_BASE/identity" \
  --header "x-scapi-api-key: $SCAPI_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "identity": "ABC123",
    "expires_in_seconds": 3600,
    "quota": 1000
  }'

创建响应 · token 仅返回一次

{
  "ok": true,
  "data": {
    "identity": "partner-a:ABC123",
    "token": "<identity-token>",
    "expires_at": 2000003600,
    "expires_in_seconds": 3600,
    "quota": 1000
  }
}

2 · 用户使用 identity 读取数据

curl "$SCAPI_BASE/api/components?page_size=10" \
  --header "x-scapi-identity: partner-a:ABC123" \
  --header "x-scapi-identity-token: <identity-token>"

3 · 合作商提前撤销用户

curl --request DELETE "$SCAPI_BASE/identity/ABC123" \
  --header "x-scapi-api-key: $SCAPI_API_KEY"

0–30 min发放 1000

用户使用 400，identity 剩余 600；合作商当前窗口已为它预留 1000。

30–60 min自动续留 600

新窗口从合作商额度先扣 600。用户继续消费这 600，不会再次扣合作商额度。

quota 与 expires_in_seconds 相互独立。不传 quota 时才使用 ceil(expires_in_seconds / 60) × identity_quota_per_minute 计算默认 grant。

API

可选接口

每个公开资源都支持列表、搜索和详情三种读取方式。

GET/api/health

0 Cost · 服务健康状态，无需 ticket。

GET/api/resources

0 Cost · 当前可用资源键与中文标签。

GET/api/session

1 Cost · 创建匿名会话，返回 nonce 与 sequence。

POST/api/ticket

1 Cost · 签发绑定 intent 和参数的短期 Bearer ticket。

POST/identity

合作商 API key 创建用户 identity，独立指定有效期与额度。

DELETE/identity/{name}

合作商撤销自己的 identity，并返还当前窗口内未使用预留。

GET/api/{resource}

普通资源每 10 个 1 Cost；ships 每 5 个 1 Cost，向上取整。

GET/api/{resource}/search

普通资源每 8 个 1 Cost；ships 每 4 个 1 Cost，向上取整。

GET/api/search

全局搜索每 4 个结果容量 1 Cost，向上取整。

GET/api/{resource}/{id}

普通详情 1 Cost；ships 为 2/4，star_systems 为 1/2，terminals 为 1/4 Cost。

公开资源

载入中

01

公共客户端认证

不使用合作商 identity 的客户端通过会话、票据和实际请求完成一次受保护读取。

创建会话GET /api/session保存 HTTP-only cookie，并取得 nonce 与 sequence。
申请票据POST /api/ticket票据必须绑定实际请求的资源、ID 和参数。
读取资源GET /api/...发送 Bearer ticket；详情还需发送轮换后的 replay headers。

载具默认详情票据

POST /api/ticket
Content-Type: application/json
x-scapi-fingerprint: your-browser-fingerprint

{
  "resource": "ships",
  "id": "Ship.anvl-ballista",
  "intent": "detail",
  "UncommonData": 0,
  "nonce": "<session nonce>",
  "sequence": 1,
  "behavior": {"dwell_ms": 500, "has_interaction": true}
}

使用票据

GET /api/ships/Ship.anvl-ballista?UncommonData=0
Authorization: Bearer <ticket>
x-scapi-fingerprint: your-browser-fingerprint
x-scapi-nonce: <next_nonce>
x-scapi-sequence: <next_sequence>

票据中的 UncommonData 必须与 GET 查询参数完全一致。省略参数等价于 0。

合作商用户不需要执行本节流程，直接使用 x-scapi-identity 与 x-scapi-identity-token。API key 只允许调用 identity 管理端口，直接读取数据会返回 403 partner_identity_required。

02

详情数据模式

UncommonData 适用于载具、星系和终端详情接口。

0

默认汇总

保留状态、尺寸、装甲、飞行性能和现有 overview，并追加型号数量汇总。

不返回真实 components
不返回 PortName、Children 或挂点拓扑
不公开 VehicleTrusters 引擎节点

1

完整公共数据

返回经过公共字段过滤的完整 components 节点结构，适合配装或结构分析。

每次请求消耗 4 点详情额度
票据与 GET 均需指定值 1
来源路径、调试字段和私有字段仍被过滤

默认装备摘要

{
  "overview": {
    "EquipmentSummary": {
      "Weapons": [{
        "ItemID": "VehicleWeapon.example",
        "ItemType": "VehicleWeapon",
        "NameCN": "示例火炮",
        "Size": 3,
        "Count": 4
      }]
    }
  }
}

星系默认结构

{
  "ID": "StarSystem.Stanton",
  "Stars": [{
    "ID": "Star.StantonStar",
    "StarNameCN": "斯坦顿",
    "StarNameEN": "Stanton",
    "StarmapSize": 696000000,
    "BodyRadius": null,
    "Material": "Texture/StantonStar.mtl",
    "Orbit": {"ParentID": null},
    "Planets": [{
      "ID": "Planet.Stanton3",
      "PlanetNameCN": "弧光星",
      "PlanetNameEN": "ArcCorp",
      "StarmapSize": 800000,
      "BodyRadius": 800000,
      "Material": "Texture/Stanton3.mtl",
      "Orbit": {"ParentID": "Star.StantonStar"}
    }]
  }]
}

star_systems/{id} 返回直属轨道对象：行星详情包含直属次级行星、自然卫星及作为人造卫星的轨道空间站，空间站摘要不会展开站内地点、终端或市场。locations/{planet-or-moon-id} 则只在 locations 数组中返回该天体内的直属地点。标准详情包含完整 Orbit 与 Rotation，UncommonData=1 额外增加描述、QuantumTravel 和 AtmosphereHeight。

terminals/{MarketTerminal.id} 默认返回终端位置与当前 Prices；UncommonData=1 在 PriceHistory15Days 中追加 UEX 各商品最近 15 日价格记录，消耗 4 Cost。UEX 响应按终端与商品对缓存 12 小时。

03

IP 额度

匿名认证链的每一步都消耗同一个 30 分钟共享额度，最终响应显示完整调用链成本。

接口Cost 规则

/api/health · /api/resources0，不扣除额度

/api/session · /api/ticket每次 1

/api/{resource}普通资源 ⌈page_size / 10⌉；ships ⌈page_size / 5⌉

/api/{resource}/search普通资源 ⌈limit / 8⌉；ships ⌈limit / 4⌉

/api/search⌈limit / 4⌉

/api/{resource}/{id}普通资源 1；ships 为 2/4；star_systems 为 1/2；terminals 为 1/4

额度响应头

响应头含义

X-RateLimit-Limit当前生效额度桶的上限；匿名成功请求显示共享总额度

X-RateLimit-Remaining本次扣费后的剩余额度

X-RateLimit-Reset当前窗口重置的 Unix 时间

X-RateLimit-Cost匿名首次调用显示 session 1 + ticket 1 + 数据 Cost；复用 session 后显示 ticket 1 + 数据 Cost

X-SCAPI-Next-Nonce · X-SCAPI-Next-Sequence详情请求返回下一次复用 session 所需的防重放状态

Retry-After仅 429 返回，距离窗口重置的秒数

匿名共享总额度默认每 IP 每 30 分钟 30 Cost。例如全局搜索 limit=20 的数据 Cost 为 5，首次调用报告并实际消耗 7 Cost；同一页面复用 session 后为 6 Cost。合作商可在接口测试区输入自己的 API key，创建短期测试 identity 后按 identity grant 调用；凭据只保留在当前页面内存。

04

错误契约

所有 API 错误使用相同 envelope，并返回 request ID 与额度响应头。

{
  "ok": false,
  "error": {
    "code": "ticket_scope_mismatch",
    "message": "Ticket scope does not match.",
    "detail": null
  },
  "meta": {"request_id": "..."}
}

401: 缺少或无效的 session、ticket、identity、token、nonce 或 sequence。
403: API key 尝试读取数据，或票据 intent、资源、参数、fingerprint 不匹配。
409: 合作商创建了同名且仍处于活跃状态的 identity。
422: 请求参数格式无效，例如 identity 名称、有效期、额度或 UncommonData 不合法。
429: 用户 identity 额度耗尽，或合作商当前窗口没有足够额度继续分配。