배송조회 API

{
  "tracking_number": "12345678901",
  "carrier":  { "code": "cj", "name": "CJ대한통운", "detected": true },
  "status":   { "code": "linehaul", "label": "간선 이동 중", "is_final": false },
  "last_event_at": "2026-07-26T09:12:00+09:00",
  "last_event_at_raw": "2026-07-26 09:12:00",
  "last_event_at_precision": "exact",
  "events": [
    {
      "occurred_at": "2026-07-26T09:12:00+09:00",
      "occurred_at_raw": "2026-07-26 09:12:00",
      "time_precision": "exact",
      "location": "대전HUB",
      "status_text": "간선상차",
      "stage": "linehaul"
    }
  ],
  "as_of": "2026-07-26T18:06:00+09:00"
}

curl "https://taekbae.net/v1/tracking/12345678901?eta=true" \
  -H "Authorization: Bearer $TAEKBAE_API_KEY"

{
  "tracking_number": "12345678901",
  "carrier":  { "code": "cj", "name": "CJ대한통운", "detected": true },
  "status":   { "code": "linehaul", "label": "간선 이동 중", "is_final": false },
  "last_event_at": "2026-07-26T09:12:00+09:00",
  "last_event_at_raw": "2026-07-26 09:12:00",
  "last_event_at_precision": "exact",
  "eta": {
    "status": "available",
    "estimated_delivery_from": "2026-07-26T19:33:00+09:00",
    "estimated_delivery_to":   "2026-07-28T20:59:00+09:00",
    "p50_remaining_minutes": 1313,
    "p90_remaining_minutes": 3053,
    "confidence": "low",
    "support_count": 535,
    "fallback_level": "community_prior",
    "model_version": "empirical-quantile-2026-07-18.1",
    "as_of": "2026-07-26T18:06:00+09:00"
  },
  "events": [
    {
      "occurred_at": "2026-07-26T09:12:00+09:00",
      "occurred_at_raw": "2026-07-26 09:12:00",
      "time_precision": "exact",
      "location": "대전HUB",
      "status_text": "간선상차",
      "stage": "linehaul"
    }
  ],
  "as_of": "2026-07-26T18:06:00+09:00"
}

# macOS · Linux · WSL
export TAEKBAE_API_KEY="tb_xxxxxxxxxxxxxxxxxxxx"

# 기본 조회 (택배사 자동 감지, ETA 없음)
curl -s "https://taekbae.net/v1/tracking/12345678901" \
  -H "Authorization: Bearer $TAEKBAE_API_KEY" | jq

# 택배사를 지정하고 최신 이벤트만
curl -s "https://taekbae.net/v1/tracking/12345678901?carrier=cj&events=latest" \
  -H "Authorization: Bearer $TAEKBAE_API_KEY" | jq

# 도착 예측까지 (기본은 오지 않습니다)
curl -s "https://taekbae.net/v1/tracking/12345678901?eta=true" \
  -H "Authorization: Bearer $TAEKBAE_API_KEY" | jq '.eta'

# 내 쪽 주문번호를 실어 보내면 응답에 그대로 돌아옵니다 (client_id)
curl -s "https://taekbae.net/v1/tracking/12345678901?client_id=order-1001" \
  -H "Authorization: Bearer $TAEKBAE_API_KEY" | jq '.client_id'

# 상태코드와 헤더까지 보기: ETag·RateLimit-Remaining을 확인할 때
curl -i -s "https://taekbae.net/v1/tracking/12345678901" \
  -H "Authorization: Bearer $TAEKBAE_API_KEY" | head -20

# Windows PowerShell 5.1 / PowerShell 7+
$env:TAEKBAE_API_KEY = "tb_xxxxxxxxxxxxxxxxxxxx"
$headers = @{ Authorization = "Bearer $env:TAEKBAE_API_KEY" }

# 기본 조회
Invoke-RestMethod -Uri "https://taekbae.net/v1/tracking/12345678901" `
  -Headers $headers | ConvertTo-Json -Depth 6

# 택배사 지정 + 최신 이벤트만
Invoke-RestMethod -Uri "https://taekbae.net/v1/tracking/12345678901?carrier=cj&events=latest" `
  -Headers $headers | ConvertTo-Json -Depth 6

# 헤더까지 보려면 Invoke-WebRequest: ETag는 여기서만 읽힙니다
$res = Invoke-WebRequest -Uri "https://taekbae.net/v1/tracking/12345678901" -Headers $headers
$res.Headers["ETag"]
$res.Headers["RateLimit-Remaining"]

# 조건부 요청: 내용이 그대로면 304, 쿼터도 차감되지 않습니다.
# PowerShell은 304를 오류로 던지므로 잡아서 처리합니다.
try {
    $headers["If-None-Match"] = $res.Headers["ETag"]
    Invoke-WebRequest -Uri "https://taekbae.net/v1/tracking/12345678901" -Headers $headers
} catch [System.Net.WebException] {
    if ($_.Exception.Response.StatusCode.value__ -eq 304) { "변화 없음" }
    else { throw }
}

# pip install httpie
export TAEKBAE_API_KEY="tb_xxxxxxxxxxxxxxxxxxxx"

# 기본 조회: 헤더와 본문을 함께 보여줍니다
http GET https://taekbae.net/v1/tracking/12345678901 \
  "Authorization: Bearer $TAEKBAE_API_KEY"

# 쿼리 파라미터는 == 로 붙입니다
http GET https://taekbae.net/v1/tracking/12345678901 \
  carrier==cj events==latest eta==true \
  "Authorization: Bearer $TAEKBAE_API_KEY"

# pip install requests==2.34.2   (표준 라이브러리만으로는 돌지 않습니다)
import os, requests

BASE = "https://taekbae.net/v1"
SESSION = requests.Session()
SESSION.headers["Authorization"] = f"Bearer {os.environ['TAEKBAE_API_KEY']}"


class TrackError(Exception):
    """API 오류의 뿌리. retry_after는 429·503에서만 채워진다."""
    def __init__(self, message, retry_after=None):
        super().__init__(message)
        self.retry_after = retry_after


class NotFound(TrackError): """404. 그 운송장이 택배사에 없다(304와 다르다)."""
class CarrierNotDetected(TrackError): """422. 후보가 없다. carrier를 지정해야 한다."""
class QuotaExceeded(TrackError): """429. retry_after만큼 기다린다."""
class CarrierUnavailable(TrackError): """503. 택배사 장애(운송장이 없는 것과 다르다)."""
class CarrierError(TrackError): """502. 상류 실패. 재시도 가능하고 차감도 없다."""


def track(number, carrier=None, etag=None):
    """(결과, ETag)를 돌려준다. 내용이 그대로면 결과는 None이고 ETag는 유지된다."""
    r = SESSION.get(f"{BASE}/tracking/{number}",
                    params={"carrier": carrier} if carrier else {},
                    headers={"If-None-Match": etag} if etag else {},
                    timeout=15)

    if r.status_code == 304:               # 변화 없음. 쿼터 차감 없음
        return None, etag
    if r.status_code == 200:
        return r.json(), r.headers.get("ETag")

    problem = r.json()
    code, title, rid = problem["code"], problem["title"], problem["request_id"]
    retry_after = r.headers.get("Retry-After")
    retry_after = int(retry_after) if retry_after else None

    if code == "tracking_number_not_found":
        raise NotFound(title)                                    # 차감된다. 폴링을 멈춘다
    if code == "carrier_not_detected":
        # candidates에는 **아직 시도하지 않은** 후보만 온다. 비어 있으면
        # 더 해볼 게 없으니 사용자에게 택배사를 물어야 한다.
        candidates = problem.get("candidates") or []
        if not candidates:
            return None, None
        return track(tracking_number, carrier=candidates[0]["code"])
    if code == "quota_exceeded":
        raise QuotaExceeded(title, retry_after)
    if code == "carrier_unavailable":
        raise CarrierUnavailable(title, retry_after)
    if code == "carrier_error":
        raise CarrierError(f"{title} (request_id={rid})")         # 재시도 가능
    raise TrackError(f"{code}: {title} (request_id={rid})")


try:
    result, etag = track("12345678901", carrier="cj")
    if result is None:
        print("변화 없음")                    # 304. 가지고 있던 결과를 그대로 쓴다
    else:
        print(result["status"]["label"], result["status"]["is_final"])
except NotFound:
    print("아직 등록되지 않은 운송장입니다")   # 404를 '변화 없음'으로 읽지 않는다

// Node.js 18+ (전역 fetch 필요). 브라우저에서 직접 부르지 마세요.
// 클라이언트 코드에 API 키를 심으면 그대로 유출됩니다. 반드시 서버를 거치세요.
const BASE = "https://taekbae.net/v1";
const HEADERS = { Authorization: `Bearer ${process.env.TAEKBAE_API_KEY}` };

// retryAfter는 429·503에서만 채워진다.
class TrackError extends Error {
  constructor(message, retryAfter = null) {
    super(message);
    this.retryAfter = retryAfter;
  }
}
class NotFound extends TrackError {}           // 404. 그 운송장이 택배사에 없다(304와 다르다).
class CarrierNotDetected extends TrackError {} // 422. 후보가 없다. carrier를 지정해야 한다.
class QuotaExceeded extends TrackError {}      // 429. retryAfter만큼 기다린다.
class CarrierUnavailable extends TrackError {} // 503. 택배사 장애(운송장이 없는 것과 다르다).
class CarrierError extends TrackError {}       // 502. 상류 실패. 재시도 가능하고 차감도 없다.

// { result, etag }를 돌려준다. 내용이 그대로면 result는 null이고 etag는 유지된다.
async function track(number, { carrier, etag } = {}) {
  const url = new URL(`${BASE}/tracking/${number}`);
  if (carrier) url.searchParams.set("carrier", carrier);

  const res = await fetch(url, {
    headers: { ...HEADERS, ...(etag ? { "If-None-Match": etag } : {}) },
  });

  if (res.status === 304) return { result: null, etag };  // 변화 없음. 쿼터 차감 없음
  if (res.status === 200) {
    return { result: await res.json(), etag: res.headers.get("ETag") };
  }

  const problem = await res.json();
  const { code, title, request_id: requestId } = problem;
  const retryAfterHeader = res.headers.get("Retry-After");
  const retryAfter = retryAfterHeader ? Number(retryAfterHeader) : null;

  if (code === "tracking_number_not_found") throw new NotFound(title); // 차감된다. 폴링을 멈춘다
  if (code === "carrier_not_detected") {
    // candidates에는 아직 시도하지 않은 후보만 온다. 비어 있으면
    // 더 해볼 게 없으니 사용자에게 택배사를 물어야 한다.
    const candidates = problem.candidates || [];
    if (candidates.length === 0) return { result: null, etag: null };
    return track(number, { carrier: candidates[0].code });
  }
  if (code === "quota_exceeded") throw new QuotaExceeded(title, retryAfter);
  if (code === "carrier_unavailable") throw new CarrierUnavailable(title, retryAfter);
  if (code === "carrier_error") throw new CarrierError(`${title} (request_id=${requestId})`); // 재시도 가능
  throw new TrackError(`${code}: ${title} (request_id=${requestId})`);
}

// 최상위 await는 파일이 모듈일 때만 허용됩니다(import/export가 없으면
// 일반 스크립트로 취급됩니다). import/export를 안 쓰는 프로젝트에서도
// 그대로 동작하도록 즉시실행 비동기 함수로 감쌉니다.
(async () => {
  try {
    const { result, etag } = await track("12345678901", { carrier: "cj" });
    if (result === null) {
      console.log("변화 없음");                       // 304. 가지고 있던 결과를 그대로 쓴다
    } else {
      console.log(result.status.label, result.status.is_final);
    }
  } catch (err) {
    if (err instanceof NotFound) {
      console.log("아직 등록되지 않은 운송장입니다");   // 404를 '변화 없음'으로 읽지 않는다
    } else {
      throw err;
    }
  }
})();

// Node.js 18+ (전역 fetch 필요) 또는 최신 브라우저. tsc 5.x 기준.
// 브라우저에서 직접 부르지 마세요. 키는 반드시 서버를 거쳐 넘기세요.
const BASE = "https://taekbae.net/v1";
const HEADERS = { Authorization: `Bearer ${process.env.TAEKBAE_API_KEY}` };

interface TrackingStatus {
  code: string;
  label: string;
  is_final: boolean;
}

// 전체 필드는 위 "응답 필드" 표 또는 OpenAPI 스펙을 참고하세요. 자주 쓰는
// 필드만 타입을 달았습니다.
interface Tracking {
  tracking_number: string;
  carrier: { code: string; name: string; detected: boolean };
  status: TrackingStatus;
  last_event_at?: string;            // exact일 때만 옵니다
  last_event_at_raw?: string;        // 원문(날짜만 아는 이벤트면 여기서 날짜를 꺼내세요)
  last_event_at_precision?: "exact" | "date_only";
  events: unknown[];
  eta?: Record; // ?eta=true로 요청했을 때만 옵니다(BETA)
  as_of: string;
}

interface Problem {
  code: string;
  title: string;
  request_id: string;
  candidates?: { code: string; name: string }[];
}

interface TrackResult {
  result: Tracking | null;
  etag: string | null;
}

// retryAfter는 429·503에서만 채워진다.
class TrackError extends Error {
  constructor(message: string, public retryAfter: number | null = null) {
    super(message);
  }
}
class NotFound extends TrackError {}           // 404. 그 운송장이 택배사에 없다(304와 다르다).
class CarrierNotDetected extends TrackError {} // 422. 후보가 없다. carrier를 지정해야 한다.
class QuotaExceeded extends TrackError {}      // 429. retryAfter만큼 기다린다.
class CarrierUnavailable extends TrackError {} // 503. 택배사 장애(운송장이 없는 것과 다르다).
class CarrierError extends TrackError {}       // 502. 상류 실패. 재시도 가능하고 차감도 없다.

// result·etag를 돌려준다. 내용이 그대로면 result는 null이고 etag는 유지된다.
async function track(
  number: string,
  { carrier, etag }: { carrier?: string; etag?: string } = {}
): Promise {
  const url = new URL(`${BASE}/tracking/${number}`);
  if (carrier) url.searchParams.set("carrier", carrier);

  const res = await fetch(url, {
    headers: { ...HEADERS, ...(etag ? { "If-None-Match": etag } : {}) },
  });

  if (res.status === 304) return { result: null, etag: etag ?? null }; // 변화 없음. 쿼터 차감 없음
  if (res.status === 200) {
    return { result: (await res.json()) as Tracking, etag: res.headers.get("ETag") };
  }

  const problem = (await res.json()) as Problem;
  const { code, title, request_id: requestId } = problem;
  const retryAfterHeader = res.headers.get("Retry-After");
  const retryAfter = retryAfterHeader ? Number(retryAfterHeader) : null;

  if (code === "tracking_number_not_found") throw new NotFound(title); // 차감된다. 폴링을 멈춘다
  if (code === "carrier_not_detected") {
    // candidates에는 아직 시도하지 않은 후보만 온다. 비어 있으면
    // 더 해볼 게 없으니 사용자에게 택배사를 물어야 한다.
    const candidates = problem.candidates ?? [];
    if (candidates.length === 0) return { result: null, etag: null };
    return track(number, { carrier: candidates[0].code });
  }
  if (code === "quota_exceeded") throw new QuotaExceeded(title, retryAfter);
  if (code === "carrier_unavailable") throw new CarrierUnavailable(title, retryAfter);
  if (code === "carrier_error") throw new CarrierError(`${title} (request_id=${requestId})`); // 재시도 가능
  throw new TrackError(`${code}: ${title} (request_id=${requestId})`);
}

// 최상위 await는 파일이 모듈일 때만 허용됩니다(import/export가 없으면
// 일반 스크립트로 취급됩니다). import/export를 안 쓰는 프로젝트에서도
// 그대로 동작하도록 즉시실행 비동기 함수로 감쌉니다.
(async () => {
  try {
    const { result, etag } = await track("12345678901", { carrier: "cj" });
    if (result === null) {
      console.log("변화 없음");                       // 304. 가지고 있던 결과를 그대로 쓴다
    } else {
      console.log(result.status.label, result.status.is_final);
    }
  } catch (err) {
    if (err instanceof NotFound) {
      console.log("아직 등록되지 않은 운송장입니다");   // 404를 '변화 없음'으로 읽지 않는다
    } else {
      throw err;
    }
  }
})();

// Maven: com.fasterxml.jackson.core:jackson-databind:2.19.0 (JDK 17+, HTTP는 표준 java.net.http)
import java.io.IOException;
import java.net.URI;
import java.net.http.*;
import java.time.Duration;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

public final class TaekbaeClient {
    private static final String BASE = "https://taekbae.net/v1";

    /** 내용이 그대로면 body가 null이고 etag는 유지된다. 404와 섞이지 않는다. */
    public record Tracked(JsonNode body, String etag) {}

    /** retryAfter는 429·503에서만 채워진다. */
    public static class TrackException extends Exception {
        public final Integer retryAfter;
        public TrackException(String m, Integer retryAfter) { super(m); this.retryAfter = retryAfter; }
    }
    /** 404. 그 운송장이 택배사에 없다. 차감되므로 폴링을 멈춘다. */
    public static final class NotFound extends TrackException {
        public NotFound(String m) { super(m, null); }
    }
    /** 422. 후보가 없다. carrier를 지정해야 한다. */
    public static final class CarrierNotDetected extends TrackException {
        public CarrierNotDetected(String m) { super(m, null); }
    }
    /** 429. retryAfter만큼 기다린다. */
    public static final class QuotaExceeded extends TrackException {
        public QuotaExceeded(String m, Integer r) { super(m, r); }
    }
    /** 503. 택배사 장애. 운송장이 없는 것과 다르다. */
    public static final class CarrierUnavailable extends TrackException {
        public CarrierUnavailable(String m, Integer r) { super(m, r); }
    }
    /** 502. 상류 실패. 재시도 가능하고 차감도 없다. */
    public static final class CarrierError extends TrackException {
        public CarrierError(String m) { super(m, null); }
    }

    private final HttpClient http = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(5)).build();
    private final ObjectMapper json = new ObjectMapper();
    private final String apiKey;

    public TaekbaeClient(String apiKey) { this.apiKey = apiKey; }

    public Tracked track(String number, String carrier, String etag)
            throws TrackException, IOException, InterruptedException {
        String url = BASE + "/tracking/" + number
                + (carrier == null ? "" : "?carrier=" + carrier);
        HttpRequest.Builder req = HttpRequest.newBuilder(URI.create(url))
                .header("Authorization", "Bearer " + apiKey)
                .timeout(Duration.ofSeconds(15));
        if (etag != null) req.header("If-None-Match", etag);

        HttpResponse<String> res =
                http.send(req.build(), HttpResponse.BodyHandlers.ofString());
        if (res.statusCode() == 304) return new Tracked(null, etag);  // 변화 없음. 차감 없음
        if (res.statusCode() == 200)
            return new Tracked(json.readTree(res.body()),
                    res.headers().firstValue("ETag").orElse(null));

        JsonNode problem = json.readTree(res.body());
        String code = problem.path("code").asText();
        String title = problem.path("title").asText();
        String rid = problem.path("request_id").asText();
        Integer retryAfter = res.headers().firstValue("Retry-After")
                .map(Integer::parseInt).orElse(null);

        switch (code) {
            case "tracking_number_not_found":
                throw new NotFound(title);
            case "carrier_not_detected": {
                // candidates에는 아직 시도하지 않은 후보만 온다. 빌 수 있다.
                JsonNode candidates = problem.path("candidates");
                if (!candidates.isArray() || candidates.isEmpty()) return null;
                return track(number, candidates.get(0).get("code").asText(), null);
            }
            case "quota_exceeded":
                throw new QuotaExceeded(title, retryAfter);
            case "carrier_unavailable":
                throw new CarrierUnavailable(title, retryAfter);
            case "carrier_error":
                throw new CarrierError(title + " (request_id=" + rid + ")");
            default:
                throw new TrackException(code + ": " + title + " (request_id=" + rid + ")", null);
        }
    }

    // 사용 예. 호출부가 checked exception을 던지므로 여기서만 try/catch로 받는다.
    public static void main(String[] args) throws Exception {
        TaekbaeClient client = new TaekbaeClient(System.getenv("TAEKBAE_API_KEY"));
        try {
            Tracked tracked = client.track("12345678901", "cj", null);
            if (tracked.body() == null) {
                System.out.println("변화 없음"); // 304. 가지고 있던 결과를 그대로 쓴다
            } else {
                System.out.println(tracked.body().path("status").path("label").asText());
            }
        } catch (NotFound e) {
            System.out.println("아직 등록되지 않은 운송장입니다"); // 404를 '변화 없음'으로 읽지 않는다
        }
    }
}

// Gradle: org.jetbrains.kotlinx:kotlinx-serialization-json:1.9.0 (JDK 17+, HTTP는 표준 java.net.http)
import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse
import java.time.Duration
import kotlinx.serialization.json.*

private const val BASE = "https://taekbae.net/v1"

/** 내용이 그대로면 body가 null이고 etag는 유지된다. 404와 섞이지 않는다. */
data class Tracked(val body: JsonObject?, val etag: String?)

/** retryAfterSeconds는 429·503에서만 채워진다. */
open class TrackException(message: String, val retryAfterSeconds: Long? = null) : Exception(message)
class NotFound(message: String) : TrackException(message)              // 404. 차감된다. 폴링을 멈춘다
class CarrierNotDetected(message: String) : TrackException(message)    // 422. 후보가 없다
class QuotaExceeded(message: String, retryAfter: Long?) : TrackException(message, retryAfter)
class CarrierUnavailable(message: String, retryAfter: Long?) : TrackException(message, retryAfter)
class CarrierError(message: String) : TrackException(message)          // 502. 재시도 가능

class TaekbaeClient(private val apiKey: String) {
    private val http: HttpClient = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(5)).build()

    fun track(number: String, carrier: String? = null, etag: String? = null): Tracked {
        val url = buildString {
            append("$BASE/tracking/$number")
            carrier?.let { append("?carrier=$it") }
        }
        val req = HttpRequest.newBuilder(URI.create(url))
            .header("Authorization", "Bearer $apiKey")
            .timeout(Duration.ofSeconds(15))
            .apply { etag?.let { header("If-None-Match", it) } }
            .build()

        val res = http.send(req, HttpResponse.BodyHandlers.ofString())
        if (res.statusCode() == 304) return Tracked(null, etag)      // 변화 없음. 차감 없음
        if (res.statusCode() == 200) return Tracked(
            Json.parseToJsonElement(res.body()).jsonObject,
            res.headers().firstValue("ETag").orElse(null),
        )

        val problem = Json.parseToJsonElement(res.body()).jsonObject
        val code = problem["code"]?.jsonPrimitive?.content.orEmpty()
        val title = problem["title"]?.jsonPrimitive?.content.orEmpty()
        val rid = problem["request_id"]?.jsonPrimitive?.content.orEmpty()
        val retryAfter = res.headers().firstValue("Retry-After").orElse(null)?.toLongOrNull()

        return when (code) {
            "tracking_number_not_found" -> throw NotFound(title)
            "carrier_not_detected" -> {
                // candidates에는 아직 시도하지 않은 후보만 온다. 빌 수 있다.
                val first = problem["candidates"]?.jsonArray?.firstOrNull()
                    ?.jsonObject?.get("code")?.jsonPrimitive?.content
                if (first == null) Tracked(null, null) else track(number, carrier = first)
            }
            "quota_exceeded" -> throw QuotaExceeded(title, retryAfter)
            "carrier_unavailable" -> throw CarrierUnavailable(title, retryAfter)
            "carrier_error" -> throw CarrierError("$title (request_id=$rid)")
            else -> throw TrackException("$code: $title (request_id=$rid)")
        }
    }
}

fun main() {
    val client = TaekbaeClient(System.getenv("TAEKBAE_API_KEY"))
    try {
        val (body, _) = client.track("12345678901", carrier = "cj")
        if (body == null) println("변화 없음")                       // 304
        else println(body["status"]!!.jsonObject["label"]!!.jsonPrimitive.content)
    } catch (e: NotFound) {
        println("아직 등록되지 않은 운송장입니다")                    // 404
    }
}

package taekbae

import (
	"encoding/json"
	"errors"
	"fmt"
	"net/http"
	"net/url"
	"os"
	"strconv"
	"time"
)

const base = "https://taekbae.net/v1"

var (
	ErrNotFound           = errors.New("운송장 정보 없음")     // 404. 304(변화 없음)와 다르다
	ErrNotDetected        = errors.New("택배사 미확정")        // 422. 후보가 비었다
	ErrQuotaExceeded      = errors.New("요청 한도 초과")       // 429
	ErrCarrierUnavailable = errors.New("택배사 장애")          // 503. 운송장 없음과 다르다
	ErrCarrierError       = errors.New("택배사 응답 실패")     // 502. 재시도 가능
)

// RetryError는 다시 부르면 되는 오류다. 쿼터도 차감되지 않는다.
// RetryAfter가 0이면 서버가 알려주지 않은 것이다.
type RetryError struct {
	Err        error
	Title      string
	RetryAfter time.Duration
}

func (e *RetryError) Error() string { return fmt.Sprintf("%v: %s", e.Err, e.Title) }
func (e *RetryError) Unwrap() error { return e.Err }

type Client struct {
	APIKey string
	HTTP   *http.Client
}

type Problem struct {
	Code       string `json:"code"`
	Title      string `json:"title"`
	RequestID  string `json:"request_id"`
	Candidates []struct {
		Code string `json:"code"`
	} `json:"candidates"`
}

// Track은 내용이 그대로면 (nil, etag, nil)을 돌려준다. 운송장이 없으면 ErrNotFound다.
func (c *Client) Track(number, carrier, etag string) (map[string]any, string, error) {
	u := fmt.Sprintf("%s/tracking/%s", base, url.PathEscape(number))
	if carrier != "" {
		u += "?carrier=" + url.QueryEscape(carrier)
	}
	req, _ := http.NewRequest(http.MethodGet, u, nil)
	req.Header.Set("Authorization", "Bearer "+c.APIKey)
	if etag != "" {
		req.Header.Set("If-None-Match", etag)
	}

	client := c.HTTP
	if client == nil {
		client = &http.Client{Timeout: 15 * time.Second}
	}
	res, err := client.Do(req)
	if err != nil {
		return nil, "", err
	}
	defer res.Body.Close()

	switch res.StatusCode {
	case http.StatusNotModified: // 304. 쿼터 차감 없음
		return nil, etag, nil
	case http.StatusOK:
		var out map[string]any
		if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
			return nil, "", err
		}
		return out, res.Header.Get("ETag"), nil
	}

	var p Problem
	if err := json.NewDecoder(res.Body).Decode(&p); err != nil {
		return nil, "", err
	}
	var retryAfter time.Duration
	if v, err := strconv.Atoi(res.Header.Get("Retry-After")); err == nil {
		retryAfter = time.Duration(v) * time.Second
	}

	switch p.Code {
	case "tracking_number_not_found":
		return nil, "", ErrNotFound // 차감된다. 폴링을 멈춘다
	case "carrier_not_detected":
		if carrier == "" && len(p.Candidates) > 0 { // 후보로 한 번만 재시도
			return c.Track(number, p.Candidates[0].Code, etag)
		}
		return nil, "", fmt.Errorf("%w (request_id=%s)", ErrNotDetected, p.RequestID)
	case "quota_exceeded":
		return nil, "", &RetryError{ErrQuotaExceeded, p.Title, retryAfter}
	case "carrier_unavailable":
		return nil, "", &RetryError{ErrCarrierUnavailable, p.Title, retryAfter}
	case "carrier_error":
		return nil, "", &RetryError{ErrCarrierError, p.Title + " (request_id=" + p.RequestID + ")", retryAfter}
	default:
		return nil, "", fmt.Errorf("%s: %s (request_id=%s)", p.Code, p.Title, p.RequestID)
	}
}

// 사용 예. 실제로는 별도 main 패키지에서 taekbae를 import해서 쓰지만,
// 예시는 같은 파일에 둔다.
func main() {
	c := &Client{APIKey: os.Getenv("TAEKBAE_API_KEY")}
	body, etag, err := c.Track("12345678901", "cj", "")
	switch {
	case errors.Is(err, ErrNotFound):
		fmt.Println("아직 등록되지 않은 운송장입니다") // 404를 '변화 없음'으로 읽지 않는다
	case err != nil:
		panic(err)
	case body == nil:
		fmt.Println("변화 없음", etag) // 304. 가지고 있던 etag를 그대로 쓴다
	default:
		fmt.Println(body["status"])
	}
}

// Cargo.toml: reqwest = { version = "0.12", features = ["json"] }
//             serde_json = "1"  ·  tokio = { version = "1", features = ["full"] }
//             thiserror = "2"
use reqwest::{Client, StatusCode, header};
use serde_json::Value;

const BASE: &str = "https://taekbae.net/v1";

#[derive(Debug, thiserror::Error)]
pub enum TrackError {
    #[error("운송장 정보 없음")] // 404. 304(변화 없음)와 다르다. 차감되므로 폴링을 멈춘다
    NotFound,
    #[error("택배사 미확정 (request_id={0})")] // 422. 후보가 비었다
    CarrierNotDetected(String),
    #[error("택배사 장애: {title} ({retry_after}초 후 재시도)")] // 503. 운송장 없음과 다르다
    CarrierUnavailable { title: String, retry_after: u64 },
    #[error("택배사 응답 실패: {title} (request_id={request_id})")] // 502. 재시도 가능
    CarrierError { title: String, request_id: String },
    #[error("한도 초과, {0}초 후 재시도")]
    QuotaExceeded(u64),
    #[error("{code}: {title} (request_id={request_id})")]
    Api { code: String, title: String, request_id: String },
    #[error(transparent)]
    Http(#[from] reqwest::Error),
}

/// 내용이 그대로면 `Ok(None)`이다. 가지고 있던 ETag를 그대로 쓰면 된다.
pub async fn track(
    http: &Client,
    api_key: &str,
    number: &str,
    carrier: Option<&str>,
    etag: Option<&str>,
) -> Result<Option<(Value, Option<String>)>, TrackError> {
    let mut req = http
        .get(format!("{BASE}/tracking/{number}"))
        .bearer_auth(api_key);
    if let Some(c) = carrier {
        req = req.query(&[("carrier", c)]);
    }
    if let Some(tag) = etag {
        req = req.header(header::IF_NONE_MATCH, tag);
    }

    let res = req.send().await?;
    let tag = res
        .headers()
        .get(header::ETAG)
        .and_then(|v| v.to_str().ok())
        .map(str::to_string);

    match res.status() {
        StatusCode::NOT_MODIFIED => return Ok(None), // 쿼터 차감 없음
        StatusCode::OK => return Ok(Some((res.json().await?, tag))),
        _ => {}
    }

    let retry_after = res
        .headers()
        .get(header::RETRY_AFTER)
        .and_then(|v| v.to_str().ok())
        .and_then(|v| v.parse().ok())
        .unwrap_or(60);
    let problem: Value = res.json().await?;
    let code = problem["code"].as_str().unwrap_or_default();
    let title = problem["title"].as_str().unwrap_or_default().to_string();
    let request_id = problem["request_id"].as_str().unwrap_or_default().to_string();

    match code {
        "tracking_number_not_found" => Err(TrackError::NotFound),
        "carrier_not_detected" => {
            // 후보가 비어 있을 수 있다. 있으면 한 번만 재시도한다.
            let first = problem["candidates"]
                .get(0)
                .and_then(|c| c["code"].as_str())
                .map(str::to_string);
            match first {
                Some(c) if carrier.is_none() => {
                    Box::pin(track(http, api_key, number, Some(&c), etag)).await
                }
                _ => Err(TrackError::CarrierNotDetected(request_id)),
            }
        }
        "carrier_unavailable" => Err(TrackError::CarrierUnavailable { title, retry_after }),
        "carrier_error" => Err(TrackError::CarrierError { title, request_id }),
        "quota_exceeded" => Err(TrackError::QuotaExceeded(retry_after)),
        _ => Err(TrackError::Api {
            code: code.to_string(),
            title,
            request_id,
        }),
    }
}

#[tokio::main]
async fn main() -> Result<(), Box> {
    let http = Client::new();
    let api_key = std::env::var("TAEKBAE_API_KEY")?;

    match track(&http, &api_key, "12345678901", Some("cj"), None).await {
        Ok(Some((body, _etag))) => println!("{}", body["status"]["label"]),
        Ok(None) => println!("변화 없음"), // 304. 가지고 있던 결과를 그대로 쓴다
        Err(TrackError::NotFound) => println!("아직 등록되지 않은 운송장입니다"), // 404를 '변화 없음'으로 읽지 않는다
        Err(e) => return Err(e.into()),
    }
    Ok(())
}

curl https://taekbae.net/v1/tracking/CA123456789KR \
  -H "Authorization: Bearer tb_test_sandbox"

# Windows PowerShell 5.1 / PowerShell 7+
Invoke-RestMethod -Uri "https://taekbae.net/v1/tracking/CA123456789KR" `
  -Headers @{ Authorization = "Bearer tb_test_sandbox" } | ConvertTo-Json -Depth 6