택배 등록 API란? — 조회를 넘어 등록까지

대부분의 택배 API는 송장번호를 입력하면 배송 현황을 조회하는 기능만 제공합니다. 하지만 쇼핑몰이나 물류 시스템을 운영하다 보면, 택배를 직접 등록하고, 대량으로 발송하고, 송장을 출력하는 기능이 필요합니다.

택배API(Delivery API)는 택배사 계정을 등록하면 배송 등록·대량발송·송장출력까지 모두 REST API로 제공하는 국내 유일의 서비스입니다.

택배 조회 API vs 택배 등록 API

왜 다른 서비스는 등록 API를 제공하지 않나?

택배 조회는 상대적으로 간단합니다. 송장번호만 있으면 택배사 시스템에서 배송 정보를 가져올 수 있습니다. 하지만 택배 등록은 완전히 다른 차원의 문제입니다.

기술적 난이도

• 택배사별 인증 방식이 다름 — 롯데택배와 CJ대한통운은 로그인 방식, 토큰 관리, 세션 처리가 모두 다릅니다.
• 비표준 내부 시스템 — 택배사 내부 시스템은 외부 API용으로 설계되지 않았습니다. 각 택배사의 내부 프로토콜을 분석하고 안정적으로 연동해야 합니다.
• 이중 로그인 제한 — 택배사 계정은 동시 로그인에 제한이 있어, 토큰 갱신과 세션 관리를 정교하게 처리해야 합니다.
• 송장 출력 연동 — 택배 라벨 출력은 택배사별 전용 리포트 서버와의 연동이 필요합니다.

경쟁 서비스 현황

한국에서 택배 관련 서비스를 제공하는 곳은 크게 두 가지 유형으로 나뉩니다.

송장번호 조회 전용 API — 스마트택배(Sweet Tracker), Tracker(배송조회 API) 등은 송장번호를 입력하면 배송 현황을 조회해주는 API를 제공합니다. 택배사 계정 연동이나 배송 등록 기능은 제공하지 않습니다.

물류 솔루션 (자체 시스템 내부용) — 굿스플로(Goodsflow), 샵링커(Shoplinker) 등은 자사 솔루션 내부에서 택배사 연동을 하지만, 외부 개발자가 직접 호출할 수 있는 공개 REST API로 제공하지 않습니다. 이 서비스를 이용하려면 해당 솔루션(SaaS)에 가입하여 그 시스템 안에서 사용해야 합니다.

택배API가 제공하는 계정 기반 기능

• 택배사 계정 등록 — 롯데택배, CJ대한통운 계정을 API로 등록. AES-256 암호화로 안전하게 저장.
• 배송 등록 — 수하인 정보, 상품명, 배송 메시지 등을 입력하여 택배 등록.
• 대량 발송 — JSON API로 최대 1,000건을 한 번에 등록. 엑셀/CSV 업로드도 지원.
• 배송 조회 — 등록한 배송 건의 현황을 실시간으로 조회.
• 송장 출력 — API로 출력 세션을 생성하여 택배 라벨을 출력.

5단계 연동 흐름

코드 예제

1. 택배사 계정 등록 (cURL)

curl -X POST https://api.deliveryapi.co.kr/v1/courier/accounts/register \
  -H "Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "lotte",
    "accountId": "your_lotte_id",
    "accountPassword": "your_lotte_password",
    "accountName": "본사 계정"
  }'

2. 대량 배송 등록 (cURL)

curl -X POST https://api.deliveryapi.co.kr/v1/courier/deliveries/bulk-upload \
  -H "Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "courierAccountKey": "your-courier-account-key",
    "items": [
      {
        "receiverName": "홍길동",
        "receiverPhone1": "01012345678",
        "receiverAddress": "서울특별시 중구 세종대로 110",
        "receiverDetailAddress": "1층",
        "receiverZipCode": "04524",
        "productName": "테스트 상품",
        "quantity": 1,
        "deliveryMessage": "부재시 경비실에 맡겨주세요"
      }
    ]
  }'

3. 대량 배송 등록 (JavaScript)

const response = await fetch('https://api.deliveryapi.co.kr/v1/courier/deliveries/bulk-upload', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}:${SECRET_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    courierAccountKey: 'your-courier-account-key',
    items: [
      {
        receiverName: '홍길동',
        receiverPhone1: '01012345678',
        receiverAddress: '서울특별시 중구 세종대로 110',
        receiverDetailAddress: '1층',
        receiverZipCode: '04524',
        productName: '테스트 상품',
        quantity: 1,
        deliveryMessage: '부재시 경비실에 맡겨주세요'
      }
    ]
  })
});

const data = await response.json();
console.log(data); // { isSuccess: true, data: { ... } }

더 자세한 API 사양은 API 문서를 참고하세요.