API로 1,000건 배송 한 번에 등록하기

매일 수백 건의 주문을 처리하시나요? 대량 등록 API를 사용하면 JSON items 배열로 최대 1,000건을 한 번의 요청으로 등록할 수 있습니다.

대량 등록 API 사용

JavaScript 예제

const axios = require('axios');

async function uploadBulkDeliveries(courierAccountKey, items) {
  try {
    const response = await axios.post(
      'https://api.deliveryapi.co.kr/v1/courier/deliveries/bulk-upload',
      { courierAccountKey, items },
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}:${SECRET_KEY}`,
        }
      }
    );

    const { historyId, totalUploaded, totalFailed, results } = response.data.data;
    console.log(`업로드 완료: ${totalUploaded}건 성공, ${totalFailed}건 실패 (historyId: ${historyId})`);
    return results;
  } catch (error) {
    console.error('업로드 실패:', error.response?.data || error.message);
  }
}

// items 배열: 계정에 등록된 택배사 기준으로 최대 1,000건까지 한 번의 요청으로 처리
uploadBulkDeliveries('ca_xxx', [
  {
    clientOrderId: 'ORD-0001',
    receiverName: '홍길동',
    receiverPhone1: '01012345678',
    receiverAddress: '서울시 강남구...',
    productName: '노트북',
    quantity: 1,
  },
  // ...
]);

응답 예시

요청 하나로 전체 결과가 동기 응답으로 즉시 반환됩니다. 별도로 진행 상황을 폴링할 필요가 없습니다.

{
  "isSuccess": true,
  "data": {
    "success": true,
    "historyId": "hist_20260113_103000_a1b2c3d4",
    "totalRequested": 100,
    "totalUploaded": 95,
    "totalSkipped": 0,
    "totalFailed": 5,
    "results": [
      {
        "requestIndex": 0,
        "success": true,
        "message": "등록 완료",
        "trackingNumber": "123456789012"
      },
      {
        "requestIndex": 2,
        "success": false,
        "message": "필수 필드 누락: receiverPhone1"
      }
    ]
  }
}

필수 필드

아래 필드는 비어 있으면 400으로 거부됩니다. 나머지 필드(발송인 정보, 우편번호, 상세주소 등)는 생략 시 계정에 등록된 기본값이 사용됩니다.

• clientOrderId — 클라이언트 주문 ID (결과 매핑용)
• receiverName — 수령인명
• receiverPhone1 — 수령인 연락처
• receiverAddress — 수령인 주소
• productName — 상품명