WMS/물류 시스템에 택배 조회 API 연동하기

WMS(Warehouse Management System)나 물류 관리 시스템을 운영하면서 가장 번거로운 작업 중 하나는 여러 택배사의 배송 현황을 수동으로 확인하는 것입니다. 택배 조회 API를 연동하면 배송 현황을 자동으로 추적하고, 주문 상태를 실시간으로 동기화하여 물류 운영 효율을 크게 높일 수 있습니다.

 WMS 연동 시 핵심 이점

• 통합 조회 - 여러 택배사 배송 현황을 하나의 API로 통합 조회

• 실시간 알림 - 웹훅으로 실시간 상태 변경 알림 수신

• 자동 감지 - 배송 완료/미배달/반송 자동 감지로 운영 효율화

1. WMS 연동 아키텍처

WMS 시스템에 택배 조회 API를 연동하는 아키텍처는 배치 스케줄러를 통한 주기적 조회와 웹훅을 통한 실시간 수신, 두 가지 경로로 구성됩니다.

┌─────────┐          ┌────────────────┐          ┌──────────────────────┐
│  WMS DB  │──────▶│ Batch Scheduler │──────▶│    택배조회 API     │
└─────────┘          └────────────────┘          └──────────────────────┘
                                                             │
                                              CJ대한통운 / 롯데택배 / 한진택배 ...

┌──────────────────────┐          ┌────────────┐          ┌─────────┐
│    택배조회 API     │──Webhook──▶│ WMS Server  │──────▶│  WMS DB  │
└──────────────────────┘          └────────────┘          └─────────┘
                                          (status update)

배치 스케줄러는 WMS DB에서 미배송 주문을 조회하여 택배 조회 API를 주기적으로 호출하고, 웹훅은 배송 상태가 변경될 때 택배 조회 API가 WMS 서버로 실시간 알림을 보내는 구조입니다.

2. 배치 조회 (Polling 방식)

미배송 상태인 주문을 WMS DB에서 조회한 뒤, 최대 20건씩 묶어서 API를 호출합니다. 대량 주문을 효율적으로 처리할 수 있는 패턴입니다.

// Node.js example - batch tracking for WMS
const { DeliveryAPIClient } = require('deliveryapi');
const client = new DeliveryAPIClient({ apiKey, secretKey });

async function batchTrackUndelivered(orders) {
  // Get undelivered orders from WMS DB
  const items = orders.map(order => ({
    courierCode: order.courierCode,
    trackingNumber: order.trackingNumber,
    clientId: order.orderId,
  }));

  // Process in batches of 20
  const BATCH_SIZE = 20;
  for (let i = 0; i < items.length; i += BATCH_SIZE) {
    const batch = items.slice(i, i + BATCH_SIZE);
    const { results } = await client.tracking.trace({ items: batch });

    for (const result of results) {
      if (result.success) {
        await updateOrderStatus(result.clientId, result.data);
      }
    }
  }
}

clientId를 주문 ID로 매핑해두면, 응답에서 어떤 주문에 대한 결과인지 쉽게 식별할 수 있습니다. 배치 사이즈는 API 제한에 맞춰 20건 이하로 설정하세요.

3. 웹훅 방식 (실시간 알림)

배치 조회만으로는 배송 상태 변경을 즉시 반영하기 어렵습니다. 웹훅 구독을 등록하면 택배 조회 API가 배송 상태 변경 시 WMS 서버로 POST 요청을 보내주므로, 실시간으로 주문 상태를 업데이트할 수 있습니다.

// Express.js - Webhook endpoint for WMS
const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook/delivery', async (req, res) => {
  const { event, items } = req.body;

  for (const item of items) {
    const { trackingNumber, courierCode, currentStatus } = item;

    // Update order status in WMS DB
    await db.query(
      'UPDATE orders SET delivery_status = ?, updated_at = NOW() WHERE tracking_number = ? AND courier_code = ?',
      [currentStatus, trackingNumber, courierCode]
    );

    // Trigger WMS workflow based on status
    switch (currentStatus) {
      case 'DELIVERED':
        await confirmInventoryDeduction(trackingNumber);
        await notifyCustomer(trackingNumber, 'delivered');
        break;
      case 'FAILED':
      case 'RETURNED':
        await createReturnInbound(trackingNumber);
        await alertOperationsTeam(trackingNumber);
        break;
    }
  }

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

웹훅 엔드포인트에서는 배송 상태에 따라 WMS 워크플로우를 트리거합니다. 배송 완료 시 재고 차감을 확정하고, 반송/실패 시 반품 입고 태스크를 생성하는 등의 자동화가 가능합니다. 자세한 웹훅 설정 방법은 웹훅 구독 가이드를 참고하세요.

4. 배송 상태별 WMS 처리

택배 조회 API는 통일된 상태 코드를 제공합니다. 각 상태에 따라 WMS에서 수행해야 할 작업을 매핑하면 자동화된 물류 워크플로우를 구축할 수 있습니다.

// Map API status to WMS internal status
function mapToWmsAction(deliveryStatus) {
  const actionMap = {
    'PICKED_UP': {
      wmsStatus: 'SHIPPED',
      action: 'Confirm shipment, start tracking',
    },
    'IN_TRANSIT': {
      wmsStatus: 'IN_TRANSIT',
      action: 'Display tracking progress',
    },
    'OUT_FOR_DELIVERY': {
      wmsStatus: 'DELIVERING',
      action: 'Notify customer of imminent delivery',
    },
    'DELIVERED': {
      wmsStatus: 'COMPLETED',
      action: 'Finalize inventory deduction, close order',
    },
    'FAILED': {
      wmsStatus: 'EXCEPTION',
      action: 'Create return inbound task',
    },
    'RETURNED': {
      wmsStatus: 'RETURN_PENDING',
      action: 'Prepare return inbound receiving',
    },
  };
  return actionMap[deliveryStatus] || { wmsStatus: 'UNKNOWN', action: 'Manual review required' };
}

PICKED_UP - 출고 확정 처리. 택배사가 물건을 수거했음을 기록
IN_TRANSIT - 배송 추적 중 표시. 고객 문의 시 현재 위치 안내 가능
DELIVERED - 배송 완료 처리. 재고 차감 확정, 주문 마감
FAILED / RETURNED - 반품 입고 대기 처리. CS팀 알림 및 재발송 판단

5. 대시보드 데이터 집계

택배 조회 API로 수집한 배송 데이터를 집계하면 WMS 대시보드에서 물류 현황을 한눈에 파악할 수 있습니다.

// Aggregate delivery metrics for WMS dashboard
async function getDashboardMetrics() {
  const metrics = await db.query(`
    SELECT
      delivery_status,
      COUNT(*) as count,
      AVG(TIMESTAMPDIFF(HOUR, shipped_at, delivered_at)) as avg_hours
    FROM orders
    WHERE shipped_at >= DATE_SUB(NOW(), INTERVAL 30 DAY)
    GROUP BY delivery_status
  `);

  return {
    totalShipped: metrics.reduce((sum, m) => sum + m.count, 0),
    delivered: metrics.find(m => m.delivery_status === 'DELIVERED')?.count || 0,
    inTransit: metrics.find(m => m.delivery_status === 'IN_TRANSIT')?.count || 0,
    exceptions: metrics.find(m => m.delivery_status === 'EXCEPTION')?.count || 0,
    avgDeliveryHours: metrics.find(m => m.delivery_status === 'DELIVERED')?.avg_hours || 0,
  };
}

배송 현황 요약 - 배송 중, 배송 완료, 반송 건수를 실시간으로 집계
택배사별 배송 소요 시간 - 평균 배송일을 택배사별로 비교하여 최적의 택배사 선정
배송 지연 알림 - 일정 기간 이상 미배송 건을 자동으로 감지하여 CS팀에 알림
지역별 배송 분석 - 배송 목적지별 소요 시간 분석으로 물류 전략 수립

6. 운영 팁

운영 환경에서 꼭 확인하세요

• 배치 조회 주기는 2~4시간 권장 - 너무 잦은 호출은 불필요한 과금을 발생시킵니다. 비즈니스 긴급도에 따라 조절하세요
• 웹훅과 배치를 병행하면 누락 방지 - 웹훅이 일시적으로 실패해도 배치 조회가 보완하여 데이터 정합성을 유지합니다
• 배송 완료 후에는 조회 중단하여 API 사용량 절약 - 이미 배송 완료/반송 처리된 건은 배치 조회 대상에서 제외하세요
• 에러 핸들링 필수 - API 호출 실패 시 재시도 로직을 구현하고, 반복 실패 건은 별도 관리하세요

다음 단계

웹훅 구독 가이드 - 웹훅 설정 및 수신 처리 방법 상세 안내
대량 송장 업로드 가이드 - CSV/엑셀 파일로 대량 송장 등록
전체 API 문서 - 상세한 API 레퍼런스

WMS에 택배 조회 API를 연동해보세요

무료 회원가입 후 API 키를 발급받고 바로 시작할 수 있습니다

무료로 시작하기 →