REST API Documentation

배송대행 API
개발 가이드

배송대행 신청서의 등록, 수정, 조회, 삭제 및 부분 업데이트 기능을 제공하는 REST API입니다. AccessKey / SecretKey 헤더 인증 방식으로 간단하게 연동할 수 있습니다.

AccessKey / SecretKey REST API JSON v1.0

API 개요

배송대행 API는 외부 시스템에서 배송대행 신청서를 직접 생성·관리할 수 있도록 제공되는 REST API입니다.
모든 요청은 JSON 형식으로 전송하며, AccessKey / SecretKey 헤더 인증이 필요합니다.

Base URL

# 모든 API 엔드포인트의 기본 URL
HOST : smileg9.com          
https://{host}/api/v1/agency/dlvy

지원 API 목록

Method	Endpoint	기능
POST	/requests	배송대행 신청서 등록
PUT	/requests/{dlvyReqstEsntlNo}	배송대행 신청서 수정
GET	/requests/{dlvyReqstEsntlNo}	배송대행 신청서 상세 조회
DELETE	/requests/{dlvyReqstEsntlNo}	배송대행 신청서 삭제
PUT	/requests/{dlvyReqstEsntlNo}/tracking-no	해외 트래킹번호 수정
PUT	/requests/{dlvyReqstEsntlNo}/personal-no	개인통관고유부호 수정
GET	/requests/{dlvyReqstEsntlNo}/summary	신청서 요약정보 조회
GET	/requests/{dlvyReqstEsntlNo}/forward-info	운송장번호(원송장, 화물택배이관) 정보 조회

인증 (AccessKey / SecretKey)

모든 API 요청은 AccessKey / SecretKey 헤더 인증 방식으로 처리합니다. 서비스 이용 전 AccessKey와 SecretKey를 발급받아야 하며, 모든 호출은 HTTPS로만 허용됩니다.

⚠️

SecretKey 만료일시는 발급일로부터 1년입니다.(만료된 경우 재발급) 안전한 곳에 보관하고, 분실 시 반드시 재발급하세요.

키 발급 방법

서비스 로그인 후 오른쪽 상단메뉴 MY- API 인증키 관리 화면에서 AccessKey / SecretKey를 발급받을 수 있습니다. API 인증키 설정 가이드

인증 흐름

① 키 발급

AccessKey
SecretKey

→

② 헤더 전송

X-API-ACCESS-KEY
X-API-SECRET-KEY

→

③ 인증 완료

회원 식별 후
API 처리

요청 헤더

Header	필수	설명
`Content-Type`	필수	`application/json`
`X-API-ACCESS-KEY`	필수	발급받은 API AccessKey
`X-API-SECRET-KEY`	필수	발급받은 API SecretKey

Java 예시

java

String apiURL = "https://{host}/api/v1/agency/dlvy/requests/{dlvyReqstEsntlNo}/forward-info";

URL url = new URL(apiURL);
HttpURLConnection con = (HttpURLConnection) url.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("X-API-ACCESS-KEY", ACCESS_KEY);
con.setRequestProperty("X-API-SECRET-KEY", SECRET_KEY);

con.setConnectTimeout(5 * 1000);
con.setReadTimeout(5 * 1000);

cURL 예시

bash

curl -X GET "https://{host}/api/v1/agency/dlvy/requests/{dlvyReqstEsntlNo}/forward-info" \
  -H "Content-Type: application/json" \
  -H "X-API-ACCESS-KEY: {ACCESS_KEY}" \
  -H "X-API-SECRET-KEY: {SECRET_KEY}"

운영 정책

항목	정책
전송 프로토콜	HTTPS만 허용
키 보관	SecretKey 만료일시는 발급일로부터 1년입니다.(만료된 경우 재발급)
호출 제한	비정상 다량 호출은 자동 차단될 수 있음
IP 제한	회원 설정에 따라 허용 IP 목록으로 제한 가능

공통 응답 구조

필드	타입	설명
resultCd	String	`S` 성공 `F` 실패 `E` 시스템 오류
resultMsg	String	처리 결과 메시지
resultCode	String	오류 상세 코드 (오류 시) `NOT_FOUND` `FORBIDDEN` `BAD_REQUEST`
data	Object	응답 데이터 (성공 시, API별 상이)

HTTP 상태코드

HTTP Status	resultCode	설명
200 OK	—	요청 성공
401 Unauthorized	`INVALID_ACCESS_KEY`	인증 정보가 유효하지 않거나 API 사용 조건을 만족하지 않는 경우
400 Bad Request	`BAD_REQUEST`	요청 파라미터 오류 또는 비즈니스 규칙 위반
403 Forbidden	`FORBIDDEN`	접근 권한 없음 (타 회원 신청서 접근 등)
404 Not Found	`NOT_FOUND`	요청한 리소스를 찾을 수 없음
403	`HTTPS_ONLY`	HTTPS 요청만 허용됩니다.
429	`RATE_LIMIT_EXCEEDED`	호출 허용량을 초과한 경우

코드값 정의

운송방식 trnsprtMthdCode

코드	설명
`T3`	해운 기본값
`T2`	항공 운송

거래유형 tradeTyCode

코드	설명
`T1`	목록통관 기본값
`T4`	소량 사업자통관

통관방식 clearanceCode

코드	설명
`C1`	목록통관 기본값
`C2`	간이통관(수입신고)

포인트 차감방식 pointDcMthdCode

코드	설명
`P1`	검수 후 자동 차감 (빠른 출고) 기본값
`P2`	검수 확인 후 수동 차감

신청자 구분 applcntSeCode

코드	설명
`A1`	개인 기본값
`A2`	사업자
`A3`	외국인

검수방법 acptncMthCode

코드	설명
`A2`	개봉검수 기본값
`A3`	검수안함(배송비할인)

박스 제거 boxRemovCode

코드	설명
`B1`	박스 제거 안함 기본값
`B2`	박스 제거

신청 구분 reqstSeCode

코드	설명
`AD`	배송대행 기본값
`PA`	결제대행

재포장 옵션 repackCodeList 복수선택 · 콤마 구분

코드	설명
`P3`	박스 재포장
`P6`	마대포장
`P1`	뽁뽁이 포장
`F1`	발포지 포장
`P5`	에어팩(완충포장)
`U3`	우드 파레트 포장
`D1`	모서리보호대(8개)
`D2`	모서리보호대(16개)

택배사 dlvyCmpnyCode

코드	설명
`DP`	우체국
`DD`	대신택배
`DC`	CJ대한통운
`DK`	경동택배
`KY`	건영택배
`DH`	한진택배
`LT`	롯데택배

추가 옵션 addOptnCodeList 복수선택

코드	설명
`O1`	돼지코(기본) — `converterCnt` 필드에 개수 입력
`O2`	돼지코(고급) — `converterCnt` 필드에 개수 입력
`U1`	원산지 표시 작업 (+개당 50원~)

O1, O2는 둘 중 1개만 선택해주세요.

받는사람 알림 설정 smsSendCodeList 복수선택

코드	발송 시점
`A1`	신청서 저장 시 (주문완료 안내)
`E1`	중국 창고 상품 검수 완료 시
`I1`	관세청 통관 시작 시
`K1`	국내 배송 시작 시
`L1`	국내 배송 완료 시

처리진행상태 reqstProcSttusCode

코드	설명
`A1`	임시저장
`B1`	접수신청
`C1`	접수완료
`C2`	결제완료
`C3`	구매완료
`D0`	부분입고
`D1`	입고완료
`E1`	검수완료
`E9`	검수문제
`F1`	결제완료
`G1`	출고대기
`H1`	출고완료
`I1`	통관진행
`J1`	통관완료
`K1`	배송진행
`L1`	배송완료
`V1`	출고중지
`W1`	반품처리
`X1`	폐기처리
`S1`	재고전환
`Z9`	삭제(취소)

API 엔드포인트 상세

전체 엔드포인트 목록

Method	Endpoint	기능
POST	/requests	배송대행 신청서 등록
PUT	/requests/{dlvyReqstEsntlNo}	배송대행 신청서 수정
GET	/requests/{dlvyReqstEsntlNo}	배송대행 신청서 상세 조회
DELETE	/requests/{dlvyReqstEsntlNo}	배송대행 신청서 삭제
PUT	/requests/{dlvyReqstEsntlNo}/tracking-no	해외 트래킹번호 수정
PUT	/requests/{dlvyReqstEsntlNo}/personal-no	받는사람(개인통관고유부호) 정보 수정
GET	/requests/{dlvyReqstEsntlNo}/summary	신청서 요약정보 조회
GET	/requests/{dlvyReqstEsntlNo}/forward-info	운송장번호(원송장, 화물택배이관) 정보 조회

POST /api/v1/agency/dlvy/requests 배송대행 신청서 등록

배송대행 신청서를 새로 등록합니다. 신청서 기본정보와 상품 목록(1건 이상)을 함께 전송합니다.

📋 신청서 기본 필드

필드명	타입	필수	설명 / 코드값
reqstSeCode	String	필수	신청 구분. `AD` 배송대행 기본값 · `PA` 결제대행
trnsprtMthdCode	String	필수	운송방식. `T3` 해운 기본값 · `T2` 항공 ·
tradeTyCode	String	필수	거래유형. `T1` 목록통관 기본값 · `T4` 소량 사업자통관
clearanceCode	String	필수	통관방식. `C1` 목록통관 기본값 · `C2` 간이통관(수입신고)
clearanceTaxUSD	Number	필수	총 상품 금액 합계 (달러)
pointDcMthdCode	String	필수	포인트 차감. `P1` 자동 기본값 · `P2` 검수확인 후
acptncMthCode	String	필수	검수방법. `A2` 개봉검수 기본값 · `A3` 검수안함
boxRemovCode	String	필수	박스 제거. `B1` 안함 기본값 · `B2` 제거
repackCodeList	String	선택	재포장 옵션 코드 (복수 선택 시 콤마 구분, 예: `P1,P5`)
addOptnCodeList	String	선택	추가 옵션 코드 (복수 선택 시 콤마 구분, 예: `O1,O2`)
converterCnt	Number	선택	돼지코 개수 (`addOptnCodeList`에 `O1 또는 O2` 포함 시 입력, 기본 1)
largeBoxPrePcYn	String	필수	대형화물 이관 결제. `Y` 선불 기본값 · `N` 착불
originCertifiYn	String	필수	원산지증명서 발급. `N` 안함 기본값 · `Y` 발급
reqstMssage	String	선택	상품 검수 요청사항 (중국 창고 직원 전달사항)
payAgentReqstContent	String	조건부	알리페이 아이디 (결제대행 `PA` 신청 시 필수)

📦 수신자 정보 필드

필드명	타입	필수	설명
receiverKoNm	String	필수	받는 사람 한글 이름
receiverEnNm	String	선택	받는 사람 영문 이름
telno	String	필수	연락처 (숫자만, 예: `01011112222`, 최대 13자)
zip	String	필수	우편번호 (5자리 숫자)
basicAdres	String	필수	기본주소
detailAdres	String	필수	상세주소 (최대 100자)
dlvyRequstMssage	String	선택	배송 요청사항 — 택배 기사 전달 (최대 50자)
applcntSeCode	String	필수	신청자 구분. `A1` 개인 기본값 · `A2` 사업자 · `A3` 외국인
personalNoBizno	String	필수	개인통관고유부호 (`P`로 시작, 최대 15자) 또는 사업자번호
receiverSmsYn	String	필수	받는사람 알림 전송. `Y` 전송 기본값 · `N` 안함
smsSendCodeList	String	선택	받는사람 알림 설정 (콤마 구분, 예: `A1,E1,K1`) * receiverSmsYn가 'Y'인 경우 필수
repGoodsNm	String	선택	알림톡 표시 대표 상품명 (최대 50자)
taxSmsReceiveYn	String	선택	관부가세 문자 추가 수신. `N` 기본값 · `Y`

🛍️ 상품 목록 필드 goodsList Array — 1건 이상 필수

필드명	타입	필수	설명
trackingNo	String	선택	해외 트래킹 번호 — 중국 내 배송 운송장번호 (최대 30자)
orderNo	String	필수	주문번호 (최대 30자)
shopmalUrl	String	필수	쇼핑몰 도메인 (예: `taobao.com`, `1688.com`)
goodsUrl	String	선택	상품 URL (최대 1000자)
goodsImgUrl	String	필수	상품 이미지 URL (최대 1000자)
entrPrdlstNo	Number	필수	HS코드 (6자리 숫자)
entrPrdlstNm	String	필수	통관품목명 한글 (최대 50자)
goodsEnNm	String	필수	통관품목명 영문 (최대 50자)
goodsChNm	String	필수	통관품목명 중문 (최대 50자)
goodsOptn	String	선택	중문 옵션 (색상/사이즈, 최대 50자)
goodsMaterial	String	선택	상품 주요 재질 (소량 사업자통관시 HS코드 참고용, 최대 50자)
goodsQy	Number	필수	구매 수량(검수시 참고)
goodsReportQy	Number	필수	관세청 신고 수량
goodsAmount	Number	필수	총 구매 금액 (위안)
dlvyAmount	Number	선택	중국 내 배송료 (위안)
shopmalNm	String	선택	국내 쇼핑몰 이름 (최대 20자)
koOrderNo	String	선택	국내 쇼핑몰 주문번호 (최대 50자)
orderReference	String	선택	주문 쇼핑몰 참고사항 (최대 50자)

요청 / 응답 예시

JSON

{
  "reqstSeCode"       : "AD",
  "trnsprtMthdCode"   : "T3",
  "tradeTyCode"       : "T1",
  "clearanceCode"     : "C1",
  "pointDcMthdCode"   : "P1",
  "acptncMthCode"     : "A2",
  "boxRemovCode"      : "B1",
  "repackCodeList"    : "P1,P5",
  "addOptnCodeList"   : "",
  "converterCnt"      : 0,
  "largeBoxPrePcYn"   : "Y",
  "originCertifiYn"   : "N",
  "receiverKoNm"      : "홍길동",
  "receiverEnNm"      : "HONG GILDONG",
  "telno"             : "01012345678",
  "zip"               : "06292",
  "basicAdres"        : "서울특별시 강남구 테헤란로 123",
  "detailAdres"       : "101동 202호",
  "applcntSeCode"     : "A1",
  "personalNoBizno"   : "P123456789012",
  "receiverSmsYn"     : "Y",
  "smsSendCodeList"   : "A1,E1,K1,L1",
  "repGoodsNm"        : "스마트폰 케이스",
  "taxSmsReceiveYn"   : "N",
  "reqstMssage"       : "정품 여부 확인 후 검수 부탁드립니다.",
  "dlvyRequstMssage"  : "문 앞에 놔주세요.",
  
  "goodsList": [
    {
      "trackingNo"    : "SF1234567890",
      "orderNo"       : "TB202501010001",
      "shopmalUrl"    : "taobao.com",
      "goodsUrl"      : "https://item.taobao.com/item.htm?id=123456",
      "goodsImgUrl"   : "https://img.taobao.com/sample.jpg",
      "entrPrdlstNo"  : 391900,
      "entrPrdlstNm"  : "플라스틱 케이스",
      "goodsEnNm"     : "Plastic Case",
      "goodsChNm"     : "塑料壳",
      "goodsOptn"     : "블랙/XL",
      "goodsMaterial" : "플라스틱",
      "goodsQy"       : 2,
      "goodsReportQy" : 2,
      "goodsAmount"   : 25.00,
      "dlvyAmount"    : 3.00,
      "shopmalNm" : "스마트스토어",
      "koOrderNo" : "6645444454354445",
      "orderReference" : "국내쇼핑몰 주문 참고내용"
    }
  ]
}

JSON · HTTP 200

{
  "resultCd"         : "S",
  "resultMsg"        : "신청이 완료되었습니다.",
  "dlvyReqstEsntlNo" : "DR20250101000001"
}

JSON · HTTP 400

{
  "resultCd"   : "F",
  "resultCode" : "BAD_REQUEST",
  "resultMsg"  : "상품 목록은 1건 이상 입력해주세요."
}

PUT /api/v1/agency/dlvy/requests/{dlvyReqstEsntlNo} 신청서 수정

신청서 고유번호를 Path Variable로 지정하고, 수정할 내용을 Request Body로 전송합니다.

ℹ️

Request Body 필드 구조는 신청서 등록(POST)과 동일합니다. 입고 이전 상태의 신청서만 수정할 수 있습니다.

Path Variable

파라미터	타입	필수	설명
dlvyReqstEsntlNo	String	필수	수정할 배송대행 신청서 고유번호

GET /api/v1/agency/dlvy/requests/{dlvyReqstEsntlNo} 신청서 상세 조회

Path Variable

파라미터	타입	필수	설명
dlvyReqstEsntlNo	String	필수	조회할 배송대행 신청서 고유번호

응답 필드

필드명	타입	설명
dlvyReqstEsntlNo	String	배송대행 신청서 고유번호
reqstProcSttusCode	String	처리 진행 상태 코드
reqstSeCode	String	신청 구분 코드
trnsprtMthdCode	String	운송 방식 코드
tradeTyCode	String	거래 유형 코드
clearanceCode	String	통관 방식 코드
clearanceTaxUSD	Number	과세 기준 금액(USD)
pointDcMthdCode	String	포인트 차감 방식 코드
acptncMthCode	String	수령 방식 코드
boxRemovCode	String	박스 제거 옵션 코드
repackCodeList	String	재포장 옵션 코드 목록(콤마 구분)
addOptnCodeList	String	부가서비스 옵션 코드 목록(콤마 구분)
converterCnt	Number	돼지코 수량
largeBoxPrePcYn	String	대형박스 선처리 여부(Y/N)
originCertifiYn	String	원산지 표기 여부(Y/N)
reqstMssage	String	요청사항
payAgentReqstContent	String	구매대행 요청 내용
receiverKoNm	String	수령인 한글명
receiverEnNm	String	수령인 영문명
telno	String	연락처
zip	String	우편번호
basicAdres	String	기본주소
detailAdres	String	상세주소
dlvyRequstMssage	String	배송 요청사항
applcntSeCode	String	신청자 구분 코드
personalNoBizno	String	개인통관고유부호 또는 사업자번호
receiverSmsYn	String	받는사람 SMS 발송 여부(Y/N)
smsSendCodeList	String	SMS 발송 항목 코드 목록(콤마 구분)
repGoodsNm	String	알림톡 표시 대표 상품명
taxSmsReceiveYn	String	관부가세 안내 SMS 수신 여부(Y/N)
waybilNo	String	국내 배송 송장번호
dlvyCmpnyCode	String	국내 택배사 코드
subDlvyCmpnyCode	String	화물택배사 코드
subWaybilNo	String	화물택배 운송장번호
goodsList	Array<Object>	신청서에 포함된 상품 목록

goodsList 상품 필드

필드명	타입	설명
dlvyReqstEsntlNo	String	배송대행 신청서 고유번호
goodsNo	Number	상품 순번
trackingNo	String	중국 운송장번호
orderNo	String	중국 주문번호
shopmalUrl	String	중국 쇼핑몰 URL
goodsUrl	String	상품 URL
goodsImgUrl	String	상품 이미지 URL
entrPrdlstNo	String	HS코드
entrPrdlstNm	String	통관품목명 한글
goodsEnNm	String	통관품목명 영문
goodsChNm	String	통관품목명 중문
goodsOptn	String	상품 옵션(중문)
goodsMaterial	String	상품 재질(소량 사업자통관인 경우)
goodsQy	Number	상품 구매 수량
goodsReportQy	Number	관세청 신고 수량
goodsAmount	Number	상품 금액(위안)
dlvyAmount	Number	중국내 배송비(위안)
shopmalNm	String	국내 쇼핑몰 이름
koOrderNo	String	국내 쇼핑몰 주문번호
orderReference	String	국내 쇼핑몰 주문 참고

DELETE /api/v1/agency/dlvy/requests/{dlvyReqstEsntlNo} 신청서 삭제

신청서를 삭제합니다. 본인의 신청서이고 입고 이전 상태여야 삭제 가능합니다.

파라미터	타입	필수	설명
dlvyReqstEsntlNo	String	필수	삭제할 배송대행 신청서 고유번호

PUT /api/v1/agency/dlvy/requests/{dlvyReqstEsntlNo}/tracking-no 트래킹번호 수정

중국 내 배송 운송장번호(해외 트래킹번호)를 수정합니다.
본인의 신청서이고 입고 이전 상태여야 수정 가능합니다.

필드명	타입	필수	설명
dlvyReqstEsntlNo (Path)	String	필수	신청서 고유번호
goodsNo	Number	필수	상품 순번(신청서 상세 조회 API에서 제공)
trackingNo	String	필수	변경할 해외 트래킹 번호 (최대 30자)

PUT /api/v1/agency/dlvy/requests/{dlvyReqstEsntlNo}/personal-no 받는사람(통관부호) 정보 수정

받는사람(개인통관고유부호 포함) 정보를 수정합니다.
본인의 신청서이고 검수 이전 상태여야 수정 가능합니다.

필드명	타입	필수	설명
dlvyReqstEsntlNo (Path)	String	필수	신청서 고유번호
receiverKoNm	String	필수	받는 사람 한글 이름
receiverEnNm	String	선택	받는 사람 영문 이름
telno	String	필수	연락처 (숫자만, 예: `01011112222`, 최대 13자)
zip	String	필수	우편번호 (5자리 숫자)
basicAdres	String	필수	기본주소
detailAdres	String	필수	상세주소 (최대 100자)
dlvyRequstMssage	String	선택	배송 요청사항 — 택배 기사 전달 (최대 50자)
personalNoBizno	String	필수	개인통관고유부호 (`P`로 시작, 최대 15자) 또는 사업자번호

GET /api/v1/agency/dlvy/requests/{dlvyReqstEsntlNo}/summary 요약정보 조회

신청서 상태, 배송비용, 예외처리비용, 운송장정보 등 요약 정보를 조회합니다.

Path Variable

파라미터	타입	필수	설명
dlvyReqstEsntlNo	String	필수	조회할 배송대행 신청서 고유번호

응답 필드

필드명	타입	설명
dlvyReqstEsntlNo	String	신청서 고유번호
reqstProcSttusCode	String	신청서 처리 상태 코드
dlvyMinusPoint	Number	배송 비용(원)
etcMinusPoint	Number	예외처리 비용(원, 반품/폐기 등 처리시 비용)
waybilNo	String	국내 배송 송장번호
dlvyCmpnyCode	String	국내 택배사 코드
subDlvyCmpnyCode	String	화물택배사 코드
subWaybilNo	String	화물택배 운송장번호

GET /api/v1/agency/dlvy/requests/{dlvyReqstEsntlNo}/forward-info 운송장 조회

원송장번호, 화물택배 운송장번호 등 운송장 관련 정보를 조회합니다.

Path Variable

파라미터	타입	필수	설명
dlvyReqstEsntlNo	String	필수	조회할 배송대행 신청서 고유번호

응답 필드

필드명	타입	설명
waybilNo	String	국내 배송 송장번호
dlvyCmpnyCode	String	국내 택배사 코드
subDlvyCmpnyCode	String	화물택배사 코드
subWaybilNo	String	화물택배 운송장번호

오류 응답 예시

HTTP Status	resultCode	resultMsg 예시
400	`BAD_REQUEST`	필수 항목이 누락되었습니다.
400	`BAD_REQUEST`	상품 목록은 1건 이상 입력해주세요.
400	`BAD_REQUEST`	처리(수정/삭제 등) 불가능한 상태의 신청서입니다.
403	`FORBIDDEN`	해당 신청서에 대한 접근 권한이 없습니다.
404	`NOT_FOUND`	신청서를 찾을 수 없습니다.
401	`INVALID_ACCESS_KEY`	Access Key가 올바르지 않거나 등록되지 않은 경우
401	`API_DISABLED`	API 사용 상태가 비활성화되었거나 삭제된 인증정보인 경우
401	`API_KEY_EXPIRED`	API Key의 만료일시가 현재 시간보다 이전인 경우
401	`INVALID_SECRET_KEY`	Secret Key가 일치하지 않는 경우
401	`INVALID_IP`	요청한 클라이언트 IP가 허용 IP 목록에 포함되지 않은 경우

🔐

SecretKey 만료일시는 발급일로부터 1년입니다.(만료된 경우 재발급)
안전한 곳에 즉시 보관하고, 분실 시 반드시 재발급 후 기존 키를 폐기하세요.

루트스마일 배송대행 API 가이드 · v1.0 | Base URL: /api/v1/agency/dlvy

배송대행 API개발 가이드

API 개요

인증 (AccessKey / SecretKey)

공통 응답 구조

코드값 정의

전체 엔드포인트 목록

오류 응답 예시

배송대행 API
개발 가이드