여행 플랫폼용 배터리 컴플라이언스 API.

공개 verifier 엔드포인트는 계정 없이 테스트할 수 있습니다. 파트너 키는 한도, 허용 origin, 지원 조건만 바꾸며 판정 계약은 바꾸지 않습니다.

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

Auth

익명 호출이 허용됩니다. 파트너 트래픽은 발급된 x-certiwatt-key 또는 Authorization: Bearer를 사용합니다.

Rate limit

공개 트래픽은 제한되며 429와 Retry-After를 반환합니다. 파트너 한도는 키와 함께 발급됩니다.

Contract

OpenAPI contract: /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을 세그먼트별 판정으로 확장한 뒤 임베디드 워크플로용 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

지원 및 파트너 로그를 위한 안정적 감사 핸들.

ruleset_version

답변에 사용된 규칙 말뭉치. 공개 API는 현재 ruleset_version만 허용하며 지원하지 않는 pin은 400을 반환합니다.

citations

규제기관, 항공사, 제조사, 리콜 근거 출처 링크.

conditions

휴대, 승인, 수량, 라벨, 인증, 리콜 제약.

Public answers can summarize policy. Platform integrations need freshness, request preservation, source-change visibility, and reviewable evidence for support and operations.

Freshness window

Verdicts carry generated_at and expires_at; source monitoring keeps regulator, airline, manufacturer, and recall evidence reviewable.

Audit trail

파트너는 verdict_id, request payload, ruleset_version, citations를 저장해 support review와 audit export에 사용할 수 있습니다. 지원하지 않는 historical ruleset pin은 명시적 400을 반환합니다.

Change intelligence

Partner policy-change access exposes change history, source-watch rows, fingerprints, and review queue signals.

Serial responsibility

Pattern-backed recalls resolve locally; manufacturer-list recalls return external_list_required and an official lookup URL instead of guessed clearance.

Pilot scope

응답 목표, 지원 시간대, 허용 origin, rate limit, escalation path는 파트너 파일럿 범위에서 정합니다.

The public API surface is useful for discovery and testing. Partner traffic uses an agreed pilot scope, credential setup, and failure-mode review.

Partner auth

Partner traffic uses issued partner API keys; anonymous public calls do not carry pilot support terms.

Allowed origins

Allowed origins, rate limits, Retry-After behavior, production response targets, and support windows are agreement terms.

Failure modes

conditional, banned, insufficient, MODEL_NOT_FOUND, AIRLINE_NOT_COVERED, external_list_required, 429, 5xx, and stale expires_at cannot be converted into allowed.

Ruleset pins

The public API accepts the current ruleset_version only; historical replay requires the stored request payload and a controlled audit export.

Data boundary

No PII is required by default. Use serial_hash unless signed data-flow terms permit raw serial transit.

이 공개 엔드포인트는 OpenAPI 계약으로 보호되며 에이전트가 /developers, /mcp, llms.txt, AEO manifest에서 발견할 수 있습니다.

POST /api/verify

여정별 배터리 판정을 반환하며 인용, 노선 요소, 리콜 근거, 항공사 정책 맥락, ruleset_version, verdict_id를 포함합니다. Transit stop이 있는 요청은 POST /api/trips/verify를 사용해야 합니다.

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 프리뷰만 공개합니다. 전체 항공사 정책 필드, 규칙 로직, 변경 이력, 파트너급 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" }
      ]
    }
  ]
}