쇼핑몰 택배API 연동 가이드

지원 플랫폼

구현 시나리오

시나리오 1: 마이페이지 배송조회

고객이 주문 내역에서 "배송조회" 버튼을 클릭하면 실시간 배송 상태를 표시합니다.

<!-- 주문 목록 페이지 -->
<button onclick="trackDelivery('lotte', '1234567890')">
  배송조회
</button>

<div id="tracking-result"></div>

// Node.js Express 예시
app.get('/api/tracking', async (req, res) => {
  const { courier, trackingNumber } = req.query;

  const response = await axios.post(
    'https://api.deliveryapi.co.kr/v1/tracking/trace',
    {
      items: [{ courierCode: courier, trackingNumber }]
    },
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}:${SECRET_KEY}`,
        'Content-Type': 'application/json'
      }
    }
  );

  res.json(response.data);
});

async function trackDelivery(courier, trackingNumber) {
  const res = await fetch(
    `/api/tracking?courier=${courier}&trackingNumber=${trackingNumber}`
  );
  const result = await res.json();

  // API 응답의 results 배열에서 첫 번째 항목 가져오기
  const data = result.data.results[0].data;

  const html = `
    <div class="tracking-status">
      <h4>${data.deliveryStatusText}</h4>
      <ul>
        ${data.progresses.map(p => `
          <li>${p.dateTime} - ${p.description}</li>
        `).join('')}
      </ul>
    </div>
  `;

  document.getElementById('tracking-result').innerHTML = html;
}

시나리오 2: 주문 상태 자동 업데이트

웹훅을 사용하여 배송 상태가 변경되면 자동으로 주문 상태를 업데이트합니다.

// 웹훅 수신 서버
app.post('/webhook/delivery', (req, res) => {
  const { event, items } = req.body;

  for (const item of items) {
    if (event === 'tracking.polled') {
      // 주문 상태 업데이트
      updateOrderStatus(item.trackingNumber, item.currentStatus);
    }

    if (event === 'tracking.completed' || item.isDelivered) {
      // 배송 완료 처리
      completeOrder(item.trackingNumber);
      // 리뷰 요청 이메일 발송
      sendReviewRequestEmail(item.trackingNumber);
    }
  }

  res.json({ received: true });
});

async function updateOrderStatus(trackingNumber, status) {
  const statusMap = {
    'IN_TRANSIT': '배송중',
    'OUT_FOR_DELIVERY': '배송출발',
    'DELIVERED': '배송완료'
  };

  await Order.update(
    { status: statusMap[status] || status },
    { where: { trackingNumber } }
  );
}

시나리오 3: 배송 완료 자동 구매확정

// 배송 완료 후 7일 뒤 자동 구매확정
// items 루프 내에서 사용
if (event === 'tracking.completed' || item.isDelivered) {
  const order = await Order.findOne({
    where: { trackingNumber: item.trackingNumber }
  });

  // 7일 후 자동 구매확정 스케줄링
  scheduleAutoConfirm(order.id, 7 * 24 * 60 * 60 * 1000);
}

카페24 연동 예시

<!-- 카페24 주문상세 페이지에 삽입 -->
<script>
  // 카페24 주문 정보에서 송장번호 가져오기
  const trackingNumber = '{$order_tracking_no}';
  const carrier = '{$order_carrier_code}';

  if (trackingNumber) {
    // 서버 프록시를 통해 API 호출 (API 키 보호)
    fetch(`https://your-server.com/api/tracking?courier=${carrier}&trackingNumber=${trackingNumber}`)
      .then(res => res.json())
      .then(result => {
        const data = result.data.results[0].data;
        document.getElementById('delivery-status').innerHTML = `
          <strong>${data.deliveryStatusText}</strong>
        `;
      });
  }
</script>

예상 효과

다른 유스케이스

• WMS/물류 시스템 연동
• 배송 알림 서비스 구축