Java로 택배 조회 API 연동하기

Java에서 택배 조회 API를 HTTP 클라이언트로 직접 연동하는 방법을 안내합니다. 별도 SDK 없이 REST API를 활용하여 택배 조회 기능을 구현할 수 있습니다.

1. 의존성 추가

Java 11+ HttpClient는 JDK에 포함되어 있으므로 HTTP 요청을 위한 별도 라이브러리는 필요 없습니다. JSON 응답 파싱을 위해 Gson만 추가합니다.

Maven (pom.xml)

<dependency>
  <groupId>com.google.code.gson</groupId>
  <artifactId>gson</artifactId>
  <version>2.11.0</version>
</dependency>

2. API 키 설정

API 키와 Secret Key를 환경 변수에서 읽어옵니다.

String apiKey = System.getenv("DELIVERY_API_KEY");
String secretKey = System.getenv("DELIVERY_SECRET_KEY");
String authHeader = "Bearer " + apiKey + ":" + secretKey;

3. 단건 조회

java.net.http.HttpClient를 사용하여 택배 조회 API를 호출합니다. Java 15+에서는 텍스트 블록(""")으로 JSON 문자열을 깔끔하게 작성할 수 있습니다.

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();

String body = """
    {
      "items": [{
        "courierCode": "cj",
        "trackingNumber": "1234567890"
      }]
    }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.deliveryapi.co.kr/v1/tracking/trace"))
    .header("Content-Type", "application/json")
    .header("Authorization", authHeader)
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

4. 응답 파싱

Gson을 사용하여 JSON 응답을 파싱합니다. results 배열의 각 항목에서 success 필드로 건별 성공 여부를 확인합니다.

import com.google.gson.*;

JsonObject json = JsonParser.parseString(response.body()).getAsJsonObject();
JsonArray results = json.getAsJsonObject("data").getAsJsonArray("results");

for (JsonElement el : results) {
    JsonObject result = el.getAsJsonObject();
    if (result.get("success").getAsBoolean()) {
        JsonObject data = result.getAsJsonObject("data");
        System.out.println("상태: " + data.get("deliveryStatusText").getAsString());
        System.out.println("택배사: " + data.get("courierName").getAsString());
    } else {
        JsonObject error = result.getAsJsonObject("error");
        System.out.println("실패: " + error.get("code").getAsString());
    }
}

주요 응답 필드:

• deliveryStatusText — 배송 상태 텍스트 (예: "배송중", "배송완료")
• courierName — 택배사 이름
• deliveryStatus — 배송 상태 코드 (DELIVERED, IN_TRANSIT 등)
• progresses — 배송 추적 이력 배열

5. 다건 조회

items 배열에 여러 운송장을 넣으면 한 번의 API 호출로 동시에 조회할 수 있습니다. clientId를 지정하면 응답에서 어떤 주문인지 쉽게 식별할 수 있습니다.

String body = """
    {
      "items": [
        { "courierCode": "cj",     "trackingNumber": "1111111111", "clientId": "order_001" },
        { "courierCode": "lotte",  "trackingNumber": "2222222222", "clientId": "order_002" },
        { "courierCode": "hanjin", "trackingNumber": "3333333333", "clientId": "order_003" }
      ]
    }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.deliveryapi.co.kr/v1/tracking/trace"))
    .header("Content-Type", "application/json")
    .header("Authorization", authHeader)
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

JsonObject json = JsonParser.parseString(response.body()).getAsJsonObject();
JsonObject data = json.getAsJsonObject("data");
JsonObject summary = data.getAsJsonObject("summary");

System.out.println("전체: " + summary.get("total").getAsInt()
    + ", 성공: " + summary.get("successful").getAsInt()
    + ", 실패: " + summary.get("failed").getAsInt());

6. OkHttp 사용 예시

Android 개발이나 Spring 프로젝트에서 널리 사용되는 OkHttp로도 연동할 수 있습니다.

Maven 의존성

<dependency>
  <groupId>com.squareup.okhttp3</groupId>
  <artifactId>okhttp</artifactId>
  <version>4.12.0</version>
</dependency>

OkHttp 코드

import okhttp3.*;

OkHttpClient client = new OkHttpClient();

String jsonBody = """
    {
      "items": [{
        "courierCode": "cj",
        "trackingNumber": "1234567890"
      }]
    }
    """;

RequestBody requestBody = RequestBody.create(
    jsonBody, MediaType.parse("application/json"));

Request request = new Request.Builder()
    .url("https://api.deliveryapi.co.kr/v1/tracking/trace")
    .addHeader("Authorization", authHeader)
    .post(requestBody)
    .build();

try (Response response = client.newCall(request).execute()) {
    System.out.println(response.body().string());
}

7. Spring Boot 연동

Spring Boot에서는 WebClient를 사용하여 비동기 방식으로 API를 호출할 수 있습니다. RestTemplate도 사용 가능하지만, Spring 6부터는 WebClient 사용을 권장합니다.

import org.springframework.web.reactive.function.client.WebClient;
import reactor.core.publisher.Mono;

@Service
public class TrackingService {

    private final WebClient webClient;

    public TrackingService() {
        this.webClient = WebClient.builder()
            .baseUrl("https://api.deliveryapi.co.kr")
            .defaultHeader("Authorization",
                "Bearer " + System.getenv("DELIVERY_API_KEY")
                + ":" + System.getenv("DELIVERY_SECRET_KEY"))
            .defaultHeader("Content-Type", "application/json")
            .build();
    }

    public Mono<String> trace(String courierCode, String trackingNumber) {
        String body = String.format("""
            {
              "items": [{
                "courierCode": "%s",
                "trackingNumber": "%s"
              }]
            }
            """, courierCode, trackingNumber);

        return webClient.post()
            .uri("/v1/tracking/trace")
            .bodyValue(body)
            .retrieve()
            .bodyToMono(String.class);
    }
}

8. 에러 처리

HTTP 상태 코드에 따라 적절한 에러 처리를 구현합니다. 건별 조회 실패는 200 응답 내 results에서 확인해야 합니다.

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

int statusCode = response.statusCode();

switch (statusCode) {
    case 200:
        // Success - parse response
        JsonObject json = JsonParser.parseString(response.body()).getAsJsonObject();
        // ... handle results
        break;
    case 401:
        System.err.println("인증 실패 — API 키를 확인하세요");
        break;
    case 429:
        System.err.println("요청 한도 초과 — 잠시 후 재시도하세요");
        break;
    case 500:
        System.err.println("서버 오류 — 잠시 후 재시도하세요");
        break;
    default:
        System.err.println("HTTP " + statusCode + ": " + response.body());
}

주요 HTTP 상태 코드:

• 200 — 성공 (건별 실패는 results 내부에서 확인)
• 401 — 인증 실패 (API 키 확인 필요)
• 429 — 요청 한도 초과 (잠시 후 재시도)
• 500 — 서버 오류 (잠시 후 재시도)

다음 단계

• PHP 연동 가이드
• C# 연동 가이드
• 전체 API 문서 보기