API · WebSocket · 웹훅 계약 (IR-*)

02-requirements/api-contracts.html · LogiNippon · TRD · 2026-06-13 · 신뢰도 라벨 확인/추정/설계

이 페이지는 LogiNippon의 유선(wire) 계약을 단일 버전 진실원으로 고정한다 — REST(OpenAPI 3.1) · WebSocket(AsyncAPI) · 웹훅의 정확한 형상, 인증 스코프, 페이지네이션·레이트리밋·에러 규약, 그리고 외부 인터페이스(EDI·텔레매틱스·맵/기상)다. 계약은 @loginippon/contract 패키지로 추출되어 server·console·Flutter가 단일 소비하고, CI drift-gate가 불일치를 빌드 실패로 막는다. 본 페이지의 모든 엔드포인트는 as-built 구현 상태(DONE/STUB/ABSENT)를 정직하게 표기한다 — 계약은 고정되었으나 구현은 진입 단계로, 다수가 STUB/ABSENT다. 수치는 마스터 정규화 표(§4)에서 글자 그대로 인용하며 모두 "운영 데이터 없는 진입 단계의 초기 확정 목표(설계), 베이스라인으로 조정"임을 전제한다.

1. 단일 계약 원칙 — IR-API-001

2. REST 엔드포인트 카탈로그 — IR-REST-catalog

전 /v1 엔드포인트(techspec 21개 + as-built 누락분 GET /v1/shipments/tracking 배치 라이브 추가). 구현상태 열은 마스터 §7 as-built에 정합한다(DONE=구현+테스트 / PARTIAL=부분 / STUB=껍데기·501·500·ack-only / ABSENT=미존재). Auth scope는 보안 문서(SR-AUTHZ-001 scope→endpoint 매트릭스)를 따르며, 모든 호출은 API Key의 tenant_id로 자동 필터링되고 타 테넌트 리소스는 404(존재 비노출)다.

3. 공통 규약 — 버전 · 페이지네이션 · 레이트리밋 · 에러

3.1 버전

경로 프리픽스 /v1. 파괴적 변경은 /v2로, 비파괴적 필드 추가는 /v1 내에서. 모든 응답에 날짜 기반 마이너 버전 헤더 LogiNippon-Api-Version: 2026-05-31을 실어 클라이언트가 동작 변화를 감지하게 한다(server API_VERSION var와 정합; 웹훅 페이로드 api_version 필드와 동일 값).

3.2 커서 페이지네이션

커서 기반(offset 아님 — D1 대용량 스캔 회피). 요청 ?limit=50&cursor=…. 응답은 data[] + page 객체(next_cursor, has_more). 커서는 (occurred_at, id) 복합 키를 불투명 base64로 인코딩한다. as-built 정합: GET /v1/shipments·/v1/jobs 모두 { data, page:{ next_cursor, has_more } } 형상을 반환하며 has_more = (next_cursor != null)이다(shipments.ts·jobs.ts). 배치 GET /v1/shipments/tracking은 위치 있는 화물만 필터링한 { data }(page 없음, 지도 스냅샷 용도)를 반환한다.

3.3 레이트리밋

테넌트별(API Key 단위). 표준 헤더로 노출하고, 한도 수치는 NFR-SEC-RL-001(보안 문서가 권위)을 따른다. 모두 진입 단계 초기 확정 목표(설계), 운영 베이스라인으로 조정한다.

3.4 에러 엔벨로프

일관 형식(HTTP 상태 + 머신리더블 code + request_id + details). request_id는 로그·관측성(slo-catalog.html)과 상관(correlate)된다.

{
  "error": {
    "code": "SHIPMENT_NOT_FOUND",
    "message": "shipment SHP-2025-00456 not found in this tenant",
    "request_id": "req_01HF...",
    "details": []
  }
}

as-built 정합: ErrorCode union(server/src/types/index.ts)에 위 코드가 1:1 존재한다. NOT_IMPLEMENTED(501)는 스펙 표(401/403/404/422/429/500)에 더해 as-built에서 실재하는 스텁 코드다 — 계약에 명시한다.

4. JSON 예시 — 직렬화 계약

형상은 데이터 모델(data-model.html)의 3계층(Shipment→Stop→Event)·canonical_code와 1:1 정합한다. 캐리어 개인정보(드라이버 실명·番号板)는 화주 스코프에서 마스킹된다(SR-PII-001). eta_is_estimate는 D1의 0/1 정수를 API 계약에서 JSON boolean으로 정규화한다(shipmentJson).

4.1 Shipment 객체 — GET /v1/shipments/{id}

actual_carrier는 다단계 하청(元請→下請→孫請)에서 실시간 위치로 검증된 실운송 차량의 캐리어다(carrier.tier=PRIME/SUB1/SUB2/SUB3 + parent_carrier_id 체인). dwell_minutes: 143은 임계 120분 초과 → 荷待ち 예외(FR-ENG-EXC-002)로 잡힌다.

{
  "shipment_id": "SHP-2025-00456",
  "tenant_id": "TN-SHIPPER-KAO",
  "shipper_ref": "PO-98765",
  "mode": "TRUCK",
  "current_status": "IN_TRANSIT",
  "carrier":        { "carrier_id": "CR-PRIME-001", "name": "○○運輸 (元請)",   "tier": "PRIME" },
  "actual_carrier": { "carrier_id": "CR-SUB2-077",  "name": "△△急配 (孫請·실운송)", "tier": "SUB2" },
  "vehicle": { "vehicle_id": "VH-0231", "class": "MEDIUM", "plate": "品川 1*-**" },
  "driver":  { "driver_id": "DR-1180", "display_name": "佐**" },
  "planned_pickup_at":     "2025-05-15T09:00:00+09:00",
  "planned_delivery_at":   "2025-05-15T17:00:00+09:00",
  "predicted_delivery_eta":"2025-05-15T18:45:00+09:00",
  "eta_is_estimate": true,
  "stops": [
    { "stop_id": "ST-0456-1", "sequence": 1, "type": "PICKUP",
      "geofence_id": "GF-KOTO-DC-001", "address": "東京都江東区辰巳3-2-1",
      "planned_arrival_at": "2025-05-15T09:00:00+09:00",
      "actual_arrival_at":  "2025-05-15T09:12:00+09:00",
      "actual_departure_at":"2025-05-15T11:35:00+09:00",
      "dwell_minutes": 143 },
    { "stop_id": "ST-0456-2", "sequence": 2, "type": "DROPOFF",
      "geofence_id": "GF-OSAKA-CUST-014", "address": "大阪府吹田市...",
      "planned_arrival_at": "2025-05-15T17:00:00+09:00",
      "actual_arrival_at": null, "actual_departure_at": null, "dwell_minutes": null }
  ],
  "created_at": "2025-05-14T20:10:00+09:00"
}

타임스탬프는 ISO 8601 +09:00 오프셋 명시(DM-TS-001; 荷待ち 법정 계산 의존). as-built 주의: 현재 GET /:id는 carrier/vehicle/driver join + PII 마스킹이 TODO(PARTIAL) — Shipment 행만 직렬화한다.

4.2 Tracking 스냅샷 — GET /v1/shipments/{id}/tracking

추적 링크·외부 위젯이 폴링하는 "지금 한 장면". 라이브 DO 우선, 콜드/부재 시 D1 투영 + ETA(공용 빌더 buildSnapshot; 배치 /tracking과 공유). staleness_seconds(마지막 핑 경과)·tracking_rate(추적 커버리지)를 정직하게 노출한다 — 스마트폰 GPS 한계를 숨기지 않는 원칙(KPI-TRACK-001).

{
  "shipment_id": "SHP-2025-00456",
  "status": "IN_TRANSIT",
  "as_of": "2025-05-15T14:30:05+09:00",
  "position": {
    "lat": 35.1702, "lon": 136.8816, "h3_r10": "8a4f1d2a3b07fff",
    "heading_deg": 248, "speed_kmh": 82,
    "captured_at": "2025-05-15T14:29:50+09:00",
    "staleness_seconds": 15
  },
  "next_stop": {
    "stop_id": "ST-0456-2", "type": "DROPOFF",
    "eta": "2025-05-15T18:45:00+09:00", "eta_is_estimate": true,
    "promised": "2025-05-15T17:00:00+09:00", "delay_minutes": 105
  },
  "current_dwell": null,
  "tracking_rate": 0.93
}

5. WebSocket 실시간 프로토콜 — IR-WS-001

6. 웹훅 카탈로그 — IR-WH-001

6.1 웹훅 페이로드

{
  "id": "evt_01HF8Z9Q3K7M2N",
  "type": "SHIPMENT_EXCEPTION",
  "api_version": "2026-05-31",
  "occurred_at": "2025-05-15T14:30:00+09:00",
  "shipment_id": "SHP-2025-00456",
  "data": {
    "canonical_code": "LATE_DELIVERY_PREDICTED",
    "severity": "HIGH",
    "predicted_eta": "2025-05-15T18:45:00+09:00",
    "promised_eta":  "2025-05-15T17:00:00+09:00",
    "delay_minutes": 105,
    "current_location": { "lat": 35.1702, "lon": 136.8816 }
  }
}

6.2 전달 헤더

6.3 재시도 래더 · 멱등 · 순서

지수 백오프 래더(초): [0, 60, 300, 1800, 7200, 21600, 43200, 86400] — 8회, 최대 전달수명 24h, 8연속 실패 시 auto-disable + 대시보드 재활성(FR-DLV-WH-001의 notify max_retries=8과 정합). 전달은 at-least-once(같은 id가 두 번 올 수 있음, 재시도는 같은 id·다른 X-LogiNippon-Delivery). 성공 조건: 수신자 2xx를 5초 내; 그 외(타임아웃·5xx·연결 실패)는 실패로 재시도. 순서 보장 없음 — 수신자는 occurred_at 기준으로 정렬·판단한다.

7. 외부 인터페이스 — IR-EDI-001 · IR-TELE-001 · IR-EXT-001

7.1 외부 IF 요약 — IR-EXT-001

우리가 소비하는 외부 인터페이스(아웃바운드 의존). 인증 시크릿은 server에 바인딩되어 있다(MAPS_API_KEY·JMA_API_KEY·LINE_CHANNEL_TOKEN).