# deliveryapi 택배조회 호스티드 페이지 — 사용 안내 (for humans & AI)

이 문서는 코드를 작성하지 않고 "택배조회 결과 페이지 링크"를 만드는 방법을 설명한다.
사람용 대화형 콘솔: https://track.deliveryapi.co.kr/#gen
AI/기계용 문서(이 파일): https://track.deliveryapi.co.kr/llms.txt

## 개요
- deliveryapi(https://deliveryapi.co.kr)는 송장번호 기반 택배조회 API를 제공한다.
- track.deliveryapi.co.kr 는 URL 하나로 택배추적 결과를 UI로 보여주는 호스티드 페이지다. (송장 1건)
- 사용 흐름: ① deliveryapi.co.kr에서 apiKey(pk_...)·secretKey(sk_...) 발급 → ② 조회 링크 생성 → ③ 고객에게 링크 전달, 고객이 열면 추적 UI 표시.

## 기본 URL
- 페이지: https://track.deliveryapi.co.kr   (임시 도메인: https://delivery-saas-track.web.app)
- API: https://api.deliveryapi.co.kr

## 두 가지 링크 모드

### 1) 플레인 (간단하지만 secretKey가 주소에 노출 — 테스트/내부용)
https://track.deliveryapi.co.kr/?apiKey=pk_xxx&secretKey=sk_xxx&courierCode=cj&trackingNumber=1234567890

### 2) 보안 (권장 — secretKey·암호키가 URL/브라우저에 없음)
https://track.deliveryapi.co.kr/?apiKey=pk_xxx&d=<암호화토큰>
- d = apiKey별 "암호키"로 {courierCode, trackingNumber, exp}를 AES-256-GCM 암호화한 토큰
- 페이지가 {apiKey, d}를 POST /v1/tracking/secure 로 보내면, 서버가 암호키로 복호화→조회→결과 반환
- 링크가 유출돼도 그 한 건만, 만료 전까지만 노출됨

## API 엔드포인트 (Bearer 인증: Authorization: Bearer {apiKey}:{secretKey})

1) 암호키 조회/발급 (Bearer)
   GET https://api.deliveryapi.co.kr/v1/tracking/encryption-key
   → { isSuccess, data: { apiKey, encryptionKey(base64 32바이트), algorithm:"AES-256-GCM" } }

2) 암호키 교체 (Bearer) — 기존 보안 링크 전부 무효화
   POST https://api.deliveryapi.co.kr/v1/tracking/encryption-key/rotate
   → { data: { encryptionKey } }

3) 보안 링크 민트 (Bearer) — 서버가 암호화해 완성 URL 반환 (가장 쉬움)
   POST https://api.deliveryapi.co.kr/v1/tracking/secure-link
   Body: { "courierCode":"cj", "trackingNumber":"1234567890", "expiresInSec":86400 }
   → { data: { url, apiKey, d, expiresAt } }
   (expiresInSec 기본 86400=24h, 최대 2592000=30d)

4) 보안 조회 (공개, 인증 없음 — 복호화 성공이 곧 인가)
   POST https://api.deliveryapi.co.kr/v1/tracking/secure
   Body: { "apiKey":"pk_xxx", "d":"<토큰>" }
   → { isSuccess, data: { results:[{ success, data, error }], summary } }

5) 플레인 조회 (Bearer) — 다건(최대 10) 지원
   POST https://api.deliveryapi.co.kr/v1/tracking/trace
   Body: { "items":[{"courierCode":"cj","trackingNumber":"1234567890"}], "includeProgresses":true }

## 보안 토큰(d) 직접 만들기 — 암호화 사양
- 키: encryptionKey(base64)를 디코드한 32바이트
- 평문(JSON): {"c": courierCode, "t": trackingNumber, "exp": unix만료초, "v": 1}
- 알고리즘: AES-256-GCM, 랜덤 12바이트 IV, 16바이트 인증태그(GCM tag)
- 토큰 = base64url( IV[12] | authTag[16] | ciphertext )   (패딩 '=' 제거, + → -, / → _)
- 링크 = https://track.deliveryapi.co.kr/?apiKey={apiKey}&d={토큰}
- 주의: 언어 라이브러리가 tag를 ciphertext 뒤에 붙이면(Python/Java/PHP 등), 반드시 IV|tag|ciphertext 순서로 재배열할 것.

### Node.js
const crypto = require('crypto');
const key = Buffer.from('<ENCRYPTION_KEY_BASE64>', 'base64'); // 32바이트
const payload = JSON.stringify({ c: 'cj', t: '1234567890', exp: Math.floor(Date.now()/1000)+86400, v: 1 });
const iv = crypto.randomBytes(12);
const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
const ct = Buffer.concat([cipher.update(payload,'utf8'), cipher.final()]);
const tag = cipher.getAuthTag();
const token = Buffer.concat([iv, tag, ct]).toString('base64').replace(/\+/g,'-').replace(/\//g,'_').replace(/=+$/,'');
const url = 'https://track.deliveryapi.co.kr/?apiKey=<API_KEY>&d=' + token;

### Python (pip install cryptography)
import os, json, time, base64
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
key = base64.b64decode('<ENCRYPTION_KEY_BASE64>')  # 32바이트
payload = json.dumps({'c':'cj','t':'1234567890','exp':int(time.time())+86400,'v':1}).encode()
iv = os.urandom(12)
full = AESGCM(key).encrypt(iv, payload, None)  # ciphertext + 16바이트 tag
ct, tag = full[:-16], full[-16:]
token = base64.urlsafe_b64encode(iv + tag + ct).decode().rstrip('=')
url = 'https://track.deliveryapi.co.kr/?apiKey=<API_KEY>&d=' + token

### PHP
$key = base64_decode('<ENCRYPTION_KEY_BASE64>'); // 32바이트
$payload = json_encode(['c'=>'cj','t'=>'1234567890','exp'=>time()+86400,'v'=>1]);
$iv = random_bytes(12);
$tag = '';
$ct = openssl_encrypt($payload, 'aes-256-gcm', $key, OPENSSL_RAW_DATA, $iv, $tag, '', 16);
$token = rtrim(strtr(base64_encode($iv.$tag.$ct), '+/', '-_'), '=');
$url = 'https://track.deliveryapi.co.kr/?apiKey=<API_KEY>&d=' . $token;

## 지원 택배사 courierCode
cj(CJ대한통운), lotte(롯데택배), hanjin(한진택배), post(우체국택배), logen(로젠택배),
kyungdong(경동택배), daesin(대신택배), hapdong(합동택배), coupang(쿠팡택배), woori(우리택배).
국제: {country}.{carrier} 형식 — 예: us.usps, jp.yamato, intl.dhl, intl.fedex, intl.ups.

## 응답 데이터 (UnifiedTrackingResponse 주요 필드)
courierName, trackingNumber, deliveryStatusText, isDelivered,
progresses: [{ dateTime, location, status }]  // 배송 진행 이력

## 보안 주의
- 보안 링크 유출 시: 그 한 건·만료 전까지만 노출. 암호키·secretKey는 토큰에서 복원 불가, 다른 송장 위조 불가.
- apiKey+secretKey 자체 유출은 사용자 책임 — 그것으로 암호키를 재발급·위조할 수 있음. 두 키는 안전 보관.
- 암호키 교체(rotate) 시 기존 모든 보안 링크 무효화.