Python SDK로 배송 조회 자동화하기

Django, FastAPI, 배치 스크립트 등 Python 환경에서 공식 SDK를 사용하면 인증 코드나 HTTP 클라이언트를 직접 작성할 필요가 없습니다. pip install deliveryapi 한 줄로 시작해보세요.

1. 설치

Python 3.8 이상에서 동작합니다.

pip install deliveryapi

2. 환경 변수 설정

API 키는 코드에 직접 작성하지 마세요. .env 파일이나 배포 환경의 환경 변수를 사용하세요.

# .env
DELIVERY_API_KEY=pk_live_xxxxxxxxxxxxxxxx
DELIVERY_SECRET_KEY=sk_live_xxxxxxxxxxxxxxxx

3. 클라이언트 초기화

앱 시작 시 DeliveryAPIClient를 한 번 생성하여 재사용합니다. python-dotenv와 함께 사용하면 편리합니다.

환경 변수 없이 직접 지정

from deliveryapi import DeliveryAPIClient

client = DeliveryAPIClient(
    api_key="pk_live_xxxxxxxxxxxxxxxx",
    secret_key="sk_live_xxxxxxxxxxxxxxxx",
)

python-dotenv로 .env 파일 로드

import os
from dotenv import load_dotenv
from deliveryapi import DeliveryAPIClient

load_dotenv()

client = DeliveryAPIClient(
    api_key=os.environ["DELIVERY_API_KEY"],
    secret_key=os.environ["DELIVERY_SECRET_KEY"],
)

4. 택배 조회

client.tracking.trace()는 리스트를 받는 하나의 엔드포인트입니다. 1건을 조회할 때도 리스트에 넣어서 전달합니다.

result_data = client.tracking.trace(
    items=[
        {
            "courierCode": "cj",
            "trackingNumber": "1234567890",
            "clientId": "order_001",  # 내 주문번호 (선택)
        },
    ]
)

result = result_data["results"][0]

if result["success"]:
    data = result["data"]
    print("상태:", data["deliveryStatusText"])          # "배송중"
    print("최근 위치:", data["progresses"][0]["location"])  # "서울 허브"
else:
    print("조회 실패:", result["error"]["code"])        # "NOT_FOUND"

응답의 result["success"]로 건별 성공 여부를 반드시 확인하세요. 일부 조회가 실패해도 전체 요청은 실패하지 않습니다.

5. 여러 건 동시 조회

리스트에 여러 항목을 넣으면 한 번의 API 호출로 처리됩니다. clientId에 주문번호를 넣으면 응답에서 쉽게 식별할 수 있습니다.

# 여러 택배를 한 번에 조회
result_data = client.tracking.trace(
    items=[
        {"courierCode": "cj",     "trackingNumber": "1111111111", "clientId": "order_001"},
        {"courierCode": "lotte",  "trackingNumber": "2222222222", "clientId": "order_002"},
        {"courierCode": "hanjin", "trackingNumber": "3333333333", "clientId": "order_003"},
    ]
)

summary = result_data["summary"]
print(f"전체: {summary['total']}, 성공: {summary['successful']}, 실패: {summary['failed']}")

for result in result_data["results"]:
    if result["success"]:
        print(f"[{result.get('clientId')}] {result['data']['deliveryStatusText']}")

6. 지원 택배사 목록 조회

택배사 코드를 확인하거나 목록을 동적으로 표시할 때 사용합니다.

couriers_data = client.tracking.get_couriers()

for courier in couriers_data["couriers"]:
    print(f"{courier['displayName']}: {courier['trackingApiCode']}")
# CJ대한통운: cj
# 롯데택배: lotte
# 한진택배: hanjin
# ...

7. 에러 처리

인증 실패, 요청 한도 초과 등 전체 요청 수준의 오류는 ApiError로 처리합니다. 건별 실패는 result["error"]["code"]로 확인합니다.

from deliveryapi import DeliveryAPIClient, ApiError, AuthenticationError, RateLimitError

try:
    result_data = client.tracking.trace(
        items=[{"courierCode": "cj", "trackingNumber": "1234567890"}]
    )
except AuthenticationError:
    print("API 키를 확인하세요")
except RateLimitError:
    print("요청 한도 초과 — 잠시 후 재시도하세요")
except ApiError as e:
    print(f"API 오류 [{e.code}]: {e}")

8. Django 연동

클라이언트를 모듈 수준에서 한 번만 생성하면 여러 뷰에서 재사용할 수 있습니다.

# views.py
from django.http import JsonResponse
from django.views import View
from deliveryapi import DeliveryAPIClient
from django.conf import settings

client = DeliveryAPIClient(
    api_key=settings.DELIVERY_API_KEY,
    secret_key=settings.DELIVERY_SECRET_KEY,
)

class TrackingView(View):
    def get(self, request, courier, number):
        result_data = client.tracking.trace(
            items=[{"courierCode": courier, "trackingNumber": number}]
        )
        result = result_data["results"][0]

        if not result["success"]:
            return JsonResponse({"error": result["error"]["code"]}, status=404)

        return JsonResponse(result["data"])

9. FastAPI 연동

# main.py
from fastapi import FastAPI, HTTPException
from deliveryapi import DeliveryAPIClient
import os

app = FastAPI()

client = DeliveryAPIClient(
    api_key=os.environ["DELIVERY_API_KEY"],
    secret_key=os.environ["DELIVERY_SECRET_KEY"],
)

@app.get("/track/{courier}/{number}")
async def track(courier: str, number: str):
    result_data = client.tracking.trace(
        items=[{"courierCode": courier, "trackingNumber": number}]
    )
    result = result_data["results"][0]

    if not result["success"]:
        raise HTTPException(status_code=404, detail=result["error"]["code"])

    return result["data"]

10. CSV 배치 자동화

엑셀이나 CSV 파일의 주문 목록을 50건씩 나눠 자동으로 조회하는 스크립트입니다.

import csv
from deliveryapi import DeliveryAPIClient

client = DeliveryAPIClient(
    api_key=os.environ["DELIVERY_API_KEY"],
    secret_key=os.environ["DELIVERY_SECRET_KEY"],
)

def batch_track(csv_path: str, chunk_size: int = 50):
    """CSV 파일의 송장번호를 50건씩 나눠 조회합니다."""
    items = []
    with open(csv_path, newline="", encoding="utf-8") as f:
        for row in csv.DictReader(f):
            items.append({
                "courierCode": row["courier_code"],
                "trackingNumber": row["tracking_number"],
                "clientId": row["order_id"],
            })

    results = []
    for i in range(0, len(items), chunk_size):
        chunk = items[i : i + chunk_size]
        data = client.tracking.trace(items=chunk)
        results.extend(data["results"])

    return results

all_results = batch_track("orders.csv")
delivered = [r for r in all_results if r["success"] and r["data"]["isDelivered"]]
print(f"배송 완료: {len(delivered)} / {len(all_results)}")

다음 단계

• Node.js SDK 가이드
• 웹훅 구독으로 자동 알림 받기
• 전체 API 문서 보기