面向旅行平台的电池合规 API。

公共 verifier 端点无需账号即可测试。Partner key 只改变限额、允许来源和支持条款，不改变判定合同。

curl -s https://certiwatt.app/api/verify \
  -H 'content-type: application/json' \
  -d '{
    "model_id": "anker-737",
    "ccc_mark": "present",
    "trip": {
      "origin": "CN",
      "destination": "CN",
      "airline": "CA",
      "compartment_intent": "carry_on"
    },
    "options": { "language": "en" }
  }'

端点

POST /api/verify

认证

匿名调用可用。Partner 流量使用已签发的 x-certiwatt-key 或 Authorization: Bearer。

限流

公共流量会限流，返回 429 与 Retry-After；Partner 限额随 key 签发。

合同

OpenAPI 合同: /openapi.yaml

{
  "verdict": "conditional",
  "verdict_id": "vdt_01JZ8EXAMPLETRIP00000001",
  "ruleset_version": "2026-05-15",
  "generated_at": "2026-06-06T08:40:12.000Z",
  "expires_at": "2026-06-13T08:40:12.000Z",
  "summary": "Carry-on only. Airline approval may be required.",
  "device_resolved": {
    "model_id": "anker-737",
    "brand": "Anker",
    "model_name": "737 Power Bank",
    "watt_hour": 86.4,
    "recall_status": "not_affected",
    "recall_check_method": "model_match"
  },
  "constraints": [
    { "code": "carry_on_only", "message": "Carry-on only — never in checked baggage." },
    { "code": "max_units_2", "message": "Maximum 2 power banks per passenger." }
  ],
  "warnings": [
    { "code": "airline_approval_review", "severity": "advisory", "message": "Confirm airline handling before departure." }
  ],
  "citations": [
    { "kind": "regulator", "authority": "CAAC", "jurisdiction": "CN", "url": "https://...", "pulled_at": "2026-05-29" },
    { "kind": "airline", "authority": "Singapore Airlines", "jurisdiction": "SG", "url": "https://...", "pulled_at": "2026-05-29" }
  ],
  "verdict_path": ["iata_spare_lithium_battery", "cn_3c_screening", "sq_power_bank_policy"]
}

当产品流程需要判断完整行程，而不是单一路线时，使用 POST /api/trips/verify。CertiWatt 会把 origin、transit、destination 展开成逐段 verdict，再返回可嵌入订票、行李、保险、客服或 agent workflow 的 aggregate verdict。

POST /api/trips/verify

{
  "device": { "model_id": "anker-737" },
  "trip": {
    "origin": "CN",
    "transit": ["SG"],
    "destination": "US",
    "airline": "SQ",
    "compartment_intent": "carry_on"
  },
  "options": { "language": "en" }
}

{
  "public_name": "Trip Battery Pass",
  "trip_verdict_id": "trip_lx5t9d3a_q8z1r2p4",
  "verdict": "conditional",
  "summary": "Trip requires conditions or approval on at least one of 2 segments.",
  "segments": [
    {
      "index": 1,
      "origin": "CN",
      "destination": "SG",
      "airline": "SQ",
      "verdict": { "verdict": "conditional", "ruleset_version": "2026-05-15", "verdict_id": "vdt_..." }
    },
    {
      "index": 2,
      "origin": "SG",
      "destination": "US",
      "airline": "SQ",
      "verdict": { "verdict": "allowed", "ruleset_version": "2026-05-15", "verdict_id": "vdt_..." }
    }
  ],
  "device_resolved": { "model_id": "anker-737", "watt_hour": 86.4 },
  "citation_count": 4,
  "ruleset_version": "2026-05-15",
  "generated_at": "2026-06-06T08:40:12.000Z",
  "expires_at": "2026-06-13T08:40:12.000Z"
}

verdict

allowed、conditional、banned 或 insufficient。

verdict_id

用于客服复核、合作伙伴日志和后续 audit export 的稳定句柄。

ruleset_version

生成该答案时使用的规则库。公开 API 目前只接受当前 ruleset_version；不支持的 pin 会返回 400。

device_resolved

规范型号、Wh、认证、recall_status、recall_check_method，以及适用时的 exact-model recall records。

constraints

可直接渲染到产品 UI 的随身携带、审批、数量、标签、认证、机上使用或召回限制。

citations

监管、航司、厂商或召回证据的一手来源链路。

expires_at

嵌入机票、行李、保险或客服流程时，用于说明该判定的新鲜度边界。

公开答案层可以概括政策；平台集成需要的是可嵌入的判定服务，并且能说明新鲜度、请求留存、来源变更和责任链，让客服、法务和运营团队都能复核。

新鲜度窗口

Verdict 携带 generated_at 与 expires_at；来源监控和 ingest dry-run 让监管、航司、厂商与召回证据在伙伴依赖前可被复核。

审计链路

保存 verdict_id、请求 payload、ruleset_version 与 citations，用于客服复核和后续 audit export。不支持的历史 ruleset pin 会明确返回 400，不会静默回退。

变更情报

Partner policy-change access 暴露 change history、source-watch rows、fingerprints 和 review queue signals，而不是静态规则摘要。

序列号责任

有 pattern 的召回可本地判定 affected/not_affected；需要厂商名单的召回会返回 external_list_required 和官方查询 URL，而不是猜测放行。

试点范围

响应目标、支持窗口、allowed origins、rate limits 与升级路径按 partner pilot scope 设置，不由匿名公开 API 承诺。

公开 API surface 可用于发现和试跑；partner traffic 使用约定的试点范围、credential setup 和 failure-mode review。

Partner auth

Partner traffic 使用已签发的合作伙伴 API key；匿名公开调用不附带试点支持条款。

Allowed origins

Allowed origins、rate limits、Retry-After behavior、production response targets 与 support windows 都属于 agreement terms。

Failure modes

conditional、banned、insufficient、MODEL_NOT_FOUND、AIRLINE_NOT_COVERED、external_list_required、429、5xx 和 stale expires_at 不能被转成 allowed。

Ruleset pins

公开 API 只接受当前 ruleset_version；历史回放需要 stored request payload 和受控 audit export。

Data boundary

默认不需要 PII。除非 signed data-flow terms 允许 raw serial transit，否则使用 serial_hash。

这些端点是公开验证器背后的集成 surface。匿名响应可用于发现和试跑；partner 或 authenticated access 解锁更深的政策字段、变更历史和运营支持。

POST /api/verify

返回行程级电池判定，包含引用来源、路线因素、召回证据、航司政策上下文、ruleset_version 与 verdict_id。含 transit 的请求必须使用 POST /api/trips/verify。

POST /api/trips/verify

返回多段行程 Trip Battery Pass，包含 aggregate verdict、逐段 verdict、citation_count、device_resolved、ruleset_version、generated_at、expires_at，以及覆盖缺口时的 segment-level errors。

GET /api/devices

搜索已覆盖的充电宝型号。支持 q、limit 与 recent。

GET /api/devices/[modelId]

返回规范型号事实。可选 serial 会在适用时加入型号级召回 serial_evaluation。

GET /api/devices/[modelId]/recalls

返回精确型号的 Battery Recall Intelligence，可选序列号评估。

GET /api/recalls

列出型号级召回记录。支持 model_id、status 与 serial。

GET /api/airlines

列出 Airline Policy Intelligence 记录。支持 q、confidence 与 limit。

GET /api/airlines/[code]

匿名请求返回公开预览；partner/authenticated 请求返回有效规则、引用来源、policy_fields 与 change_log。

GET /api/policy-changes

匿名请求返回变更/监控计数；partner/authenticated 请求返回变更历史、来源监控行、指纹和复核队列信号。

GET /api/rules

搜索有效监管与航司规则。

GET /api/sources

返回型号或规则的规范化引用证据。

为了透明度与机器发现，CertiWatt 只发布有限的静态 JSON 预览。完整航司政策字段、规则逻辑、变更历史、audit export 与合作伙伴级导出仍保留在产品/API 层。

{
  "long_tail_verdicts": [
    {
      "route_factors": [
        "capacity check is tied to this exact catalog model",
        "Citation sources: CAAC (regulator, CN, 2026-05-29)"
      ],
      "article_body": "Summary plus route factors. Citation sources: CAAC (regulator, CN, 2026-05-29).",
      "ruleset_version": "2026-05-15",
      "citation_count": 3,
      "sources": [
        { "authority": "CAAC", "url": "https://...", "pulled_at": "2026-05-29" }
      ]
    }
  ]
}