whereparcel

궁금한 게 있으세요? 편하게 물어보세요. WhereParcel을 만든 개발자가 직접 읽고 답장드립니다.

튜토리얼 7 분 소요

배송 추적 데이터를 활용한 실시간 배송 예상일 구현 방법

택배조회 이벤트를 분석하여 정확한 배송 예상일을 계산하고 표시하는 방법을 알아보세요. 고객 만족도를 높이는 실용적인 구현 가이드입니다.

WhereParcel Team

고객이 가장 자주 묻는 질문은 “내 택배가 언제 도착하나요?”입니다. 택배사에서 제공하는 예상 배송일은 대개 모호하거나 부정확합니다. 실시간 추적 이벤트를 분석하면 더 스마트하고 정확한 배송 예상일을 제공하여 고객의 문의를 줄이고 만족도를 높일 수 있습니다.

기존 배송 예상일의 한계

대부분의 택배사가 제공하는 예상 배송일은 발송 시점에 설정된 후 거의 갱신되지 않습니다. 다음과 같은 변수를 반영하지 못합니다:

  • 국제 배송의 통관 지연
  • 기상 악화로 인한 배송 차질
  • 택배사 분류 시설의 물량 적체
  • 라스트마일 배송 과정의 돌발 상황

실시간 추적 이벤트를 처리하면 택배가 배송 네트워크를 거치는 동안 예상일을 동적으로 조정할 수 있습니다.

추적 이벤트 수집 설정

먼저 WhereParcel webhook을 사용하여 추적 업데이트를 구독합니다. 구독한 송장은 폴링 주기마다(몇 시간 간격) 다시 조회됩니다. 고객이 배송 조회 화면을 열었을 때는 POST /v2/track 을 호출하면 가장 최신 데이터를 받을 수 있습니다:

const headers = {
  'Authorization': 'Bearer YOUR_API_KEY:YOUR_SECRET_KEY',
  'Content-Type': 'application/json',
};

// 1. Create a webhook endpoint once (free). Keep endpointId, and store the
//    returned secret to verify X-WhereParcel-Signature on incoming webhooks.
const endpoint = await fetch('https://api.whereparcel.com/v2/webhook-endpoints', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'Delivery estimates',
    url: 'https://your-app.com/webhooks/tracking',
    description: '배송 상태 업데이트',
  }),
}).then((r) => r.json());

// 2. Subscribe each shipment (billed once per parcel, up to 100 per call).
//    recurring: true keeps re-checking it until it is delivered.
await fetch('https://api.whereparcel.com/v2/webhooks/register', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    webhookEndpointId: endpoint.data.endpointId,
    recurring: true,
    trackingItems: [{ carrier: 'kr.cj', trackingNumber: '123456789012' }],
  }),
});

이벤트 기반 배송 예상일 계산

각 추적 이벤트에는 상태 정보와 타임스탬프가 포함되어 있어 배송 예상일 계산에 활용할 수 있습니다. 택배사가 자체 도착 예정일을 공개하면 WhereParcel 은 그것을 estimatedDelivery 로 그대로 전달합니다. 모든 택배사가 주는 값은 아니므로 정답이 아니라 판단 재료의 하나로 쓰세요:

// trackingData = item.trackingData from a webhook, or data[0].data from POST /v2/track
function calculateEstimatedDelivery(trackingData, carrier, destination) {
  const { events, estimatedDelivery } = trackingData;
  const latestEvent = events[events.length - 1];   // events are oldest first

  // Base estimates by standardized status
  // (there is no picked_up or customs status: the first scan after
  //  the label is created already reports in_transit)
  const estimateMap = {
    'pending': { minDays: 2, maxDays: 6 },          // label created, not scanned yet
    'in_transit': { minDays: 1, maxDays: 3 },
    'out_for_delivery': { minDays: 0, maxDays: 0 },
  };

  const estimate = estimateMap[latestEvent.status] || { minDays: 2, maxDays: 7 };

  const now = new Date();
  return {
    earliest: addBusinessDays(now, estimate.minDays),
    latest: addBusinessDays(now, estimate.maxDays),
    confidence: calculateConfidence(events),
    // The carrier's own date, when it publishes one (optional field)
    carrierDate: estimatedDelivery ? new Date(estimatedDelivery) : null,
  };
}

적응형 예측 모델 구축

더 정확한 예상일을 위해 택배사별, 경로별 과거 배송 시간을 추적합니다:

// Store delivery times for completed shipments
async function recordDeliveryTime(shipment) {
  // First scan after the label was created (there is no picked_up status)
  const pickupDate = shipment.events.find(e => e.status !== 'pending')?.timestamp;
  const deliveryDate = shipment.events.find(e => e.status === 'delivered')?.timestamp;

  if (pickupDate && deliveryDate) {
    await db.deliveryTimes.insert({
      carrier: shipment.carrier,
      originCountry: shipment.origin.country,
      destinationCountry: shipment.destination.country,
      transitDays: daysBetween(pickupDate, deliveryDate),
      recordedAt: new Date(),
    });
  }
}

// Calculate average delivery time for a route
async function getHistoricalAverage(carrier, origin, destination) {
  const records = await db.deliveryTimes
    .find({ carrier, originCountry: origin, destinationCountry: destination })
    .sort({ recordedAt: -1 })
    .limit(100);

  if (records.length < 10) return null; // Not enough data

  const times = records.map(r => r.transitDays);
  return {
    average: Math.round(times.reduce((a, b) => a + b) / times.length),
    p90: percentile(times, 90),
    sampleSize: records.length,
  };
}

UI에 배송 예상일 표시하기

적절한 신뢰도와 함께 배송 예상일을 명확하게 표시합니다:

function DeliveryEstimate({ estimate }) {
  const { earliest, latest, confidence } = estimate;

  if (confidence === 'high') {
    return (
      <div className="estimate high-confidence">
        <span>Expected delivery: {formatDate(earliest)}</span>
      </div>
    );
  }

  return (
    <div className="estimate">
      <span>
        Estimated delivery: {formatDate(earliest)} – {formatDate(latest)}
      </span>
      {confidence === 'low' && (
        <small>Estimate may change based on customs processing</small>
      )}
    </div>
  );
}

엣지 케이스 처리

통관이 필요한 국제 배송

통관 절차는 배송 예상일에서 가장 큰 변수입니다. 택배가 세관에 진입하면 예상 범위를 넓혀야 합니다:

// No customs status exists: customs scans arrive as in_transit
// with the carrier's wording in description
if (latestEvent.status === 'in_transit' && /customs|clearance/i.test(latestEvent.description)) {
  // Customs can take 1-14 days depending on country
  estimate.latest = addBusinessDays(now, getCustomsEstimate(destination.country));
  estimate.confidence = 'low';
}

배송 예외 상황

배송 실패나 예외 상황이 추적에 표시되면 예상일을 그에 맞게 업데이트합니다:

// A missed attempt the carrier will retry usually stays in_transit (USPS: "Notice Left")
if (/notice left|attempted|redelivery/i.test(latestEvent.description)) {
  estimate.earliest = addBusinessDays(now, 1); // Next business day retry
  estimate.latest = addBusinessDays(now, 3);
  estimate.note = 'Delivery was attempted. The carrier will retry.';
}

// failed, returned and lost mean it will not arrive without action
if (['failed', 'returned', 'lost'].includes(latestEvent.status)) {
  estimate.earliest = estimate.latest = null;
  estimate.note = 'This delivery needs attention. Contact support.';
}

추적해야 할 핵심 지표

다음 지표를 모니터링하여 예측 정확도를 지속적으로 개선하세요:

지표목표설명
정시 정확도> 85%예상 범위 내 배송 완료 비율
평균 오차< 1일일 단위 평균 절대 오차
고객 문의감소 추세배송 시점 관련 WISMO 문의
신뢰도 보정일치높은 신뢰도 예측의 95% 이상이 정확해야 함

전체 구현 정리

실시간 추적 이벤트와 과거 데이터를 결합하면 강력한 예측 시스템을 구축할 수 있습니다:

  1. 수집 — 모든 배송 건에 대해 추적 webhook 구독
  2. 분석 — 이벤트를 처리하고 상태 + 과거 데이터를 활용하여 예상일 계산
  3. 표시 — 적절한 신뢰도 수준과 함께 예상일 표시
  4. 학습 — 실제 배송 시간을 기록하여 향후 예측 정확도 향상
  5. 알림 — 예상일이 크게 변경되면 고객에게 통보

WhereParcel의 멀티 택배사 추적 API를 기반으로 이 시스템을 구축하면 39개 이상의 택배사에 걸쳐 일관된 추적 이벤트를 받을 수 있어 글로벌 규모의 정확한 배송 예측이 가능합니다. 플레이그라운드에서 직접 테스트해 보세요.

Webhook 설정에 대한 자세한 내용은 Webhook 모범 사례 가이드를 참고하세요.

원하는 택배사가 없으신가요? 요청해 주시면 빠르게 연동해 드립니다.

택배사 요청하기 →

궁금한 게 있으세요? 편하게 물어보세요. Discord에 들어오시면 WhereParcel을 만든 개발자가 직접 읽고 답장드립니다. 봇도 없고 티켓도 없어요. 그냥 편하게 대화하세요.

Discord 참여하기 → Slack 참여하기 →

태그: #delivery-estimates #tracking #ux #tutorial #customer-experience