Delivery SaaS API 문서
택배 통합 API를 사용하여 여러 택배사의 배송 조회, 등록, 관리를 하나의 인터페이스로 처리할 수 있습니다.
📢 이 문서에 대하여
회사 내부에서 쓰던 API를 외부에 공개하면서 만든 API 문서입니다.
API는 내부적으로 사용하기 위해 보안, 편리성을 극대화하였지만 외부에 공개하면서 이 문서는 완벽하지 않을 수 있습니다.
수익이 목적이 아니다 보니 문서의 검토 없이 게시하였습니다.
혹시 API 문서가 잘못된 게 있다고 생각이 든다면 관리자에게 연락주세요.
Base URL
https://api-rldhrf7nya-du.a.run.app
모든 API 엔드포인트는 /api/v1 경로를 포함합니다.
지원 택배사
- 롯데택배 (lotte) - 조회, 등록 지원
- CJ대한통운 (cj) - 조회, 등록 지원
- 우체국택배 (post) - 조회 지원
📦 모든 택배사의 조회, 등록이 가능합니다.
다만 실 이용자의 요청에 의해 기능은 추가될 예정입니다.
타 택배사의 조회, 등록이 필요하다면 관리자에게 연락주세요.
주요 기능
- ✅ 송장번호 기반 배송 조회 (계정 불필요)
- ✅ 택배사 계정 등록 후 배송 등록
- ✅ 대량 배송 등록 (최대 1,000건)
- ✅ 발송 내역 조회 및 통계
💡 시작하기
아직 API 키가 없으신가요? 아래 회원가입 API를 통해 무료로 API 키를 발급받으세요.
회원가입
이메일 인증을 통해 간편하게 회원가입하고 API 키를 발급받을 수 있습니다.
📧 2단계 이메일 인증
1단계: 이메일 주소 입력 → 6자리 인증 코드 발송
2단계: 인증 코드 입력 → API Key + Secret Key 자동 발급
1단계: 인증 코드 요청
POST
/api/v1/auth/signup/request
Request Body
| 필드 |
타입 |
필수 |
설명 |
| email |
String |
필수 |
이메일 주소 |
예시 요청
curl -X POST https://api-rldhrf7nya-du.a.run.app/api/v1/auth/signup/request \
-H "Content-Type: application/json" \
-d '{"email": "your@email.com"}'
응답 (성공)
{
"isSuccess": true,
"message": "인증 코드가 이메일로 발송되었습니다. 5분 이내에 인증을 완료해주세요."
}
응답 (실패 - 이미 가입된 이메일)
{
"isSuccess": false,
"error": "이미 가입된 이메일입니다"
}
2단계: 인증 코드 검증 및 회원가입
POST
/api/v1/auth/signup/verify
Request Body
| 필드 |
타입 |
필수 |
설명 |
| email |
String |
필수 |
이메일 주소 |
| code |
String |
필수 |
6자리 인증 코드 |
예시 요청
curl -X POST https://api-rldhrf7nya-du.a.run.app/api/v1/auth/signup/verify \
-H "Content-Type: application/json" \
-d '{
"email": "your@email.com",
"code": "123456"
}'
응답 (성공)
{
"isSuccess": true,
"data": {
"apiKey": "pk_live_abc123def456",
"secretKey": "sk_client_minimal_xyz789abc123",
"message": "회원가입이 완료되었습니다. API 키를 안전하게 보관하세요."
}
}
응답 (실패 - 잘못된 코드)
{
"isSuccess": false,
"error": "잘못된 인증 코드입니다"
}
응답 (실패 - 코드 만료)
{
"isSuccess": false,
"error": "인증 코드가 만료되었습니다. 다시 요청해주세요."
}
⚠️ 중요 사항
- 인증 코드는 5분간 유효합니다
- 인증 시도는 최대 5회까지 가능합니다
- 발급된 Secret Key는 재발급이 불가능하니 안전하게 보관하세요
- 무료 플랜으로 시작하며 월 30,000회 API 호출이 가능합니다
인증
모든 API 요청은 API Key와 Secret Key를 사용한 인증이 필요합니다.
기본 인증 방식
모든 API 호출 시 동일한 인증 헤더를 사용합니다.
Authorization: Bearer {apiKey}:{secretKey}
조회 전용 API 예시
curl https://api-rldhrf7nya-du.a.run.app/api/v1/tracking/trace \
-H "Authorization: Bearer pk_live_abc123:sk_client_minimal_xyz789" \
-H "Content-Type: application/json" \
-d '{"items": [{"courierCode": "lotte", "trackingNumber": "123456789012"}]}'
택배 계정 관련 API 예시
택배 계정 등록, 배송 등록 등의 API도 동일한 인증 방식을 사용합니다.
curl https://api-rldhrf7nya-du.a.run.app/api/v1/courier/accounts/register \
-H "Authorization: Bearer pk_live_abc123:sk_client_minimal_xyz789" \
-H "Content-Type: application/json" \
-d '{"providerId": "lotte", "accountId": "your_id", "accountPassword": "your_pw"}'
⚠️ 택배 계정 등록 후 추가 키 발급
택배 계정을 등록하면 courierAccountKey가 발급됩니다. 이 키는 배송 등록, 대량 업로드 등 택배 계정이 필요한 API 호출 시 요청 본문에 포함하여 사용합니다.
🔒 보안 주의사항
Secret Key는 절대 클라이언트 사이드 코드(브라우저)에 노출하지 마세요. 서버에서만 사용해야 합니다.
송장번호 배송 조회
송장번호만으로 배송 현황을 실시간 조회합니다. 택배사 계정이 없어도 사용 가능합니다.
요청
POST
/api/v1/tracking/trace
Headers
| 이름 |
값 |
설명 |
| Authorization |
Bearer {apiKey}:{secretKey} |
필수 |
| Content-Type |
application/json |
JSON 형식 |
Request Body
| 필드 |
타입 |
필수 |
설명 |
| items |
Array |
필수 |
조회할 송장 목록 (최대 100개) |
| items[].courierCode |
String |
필수 |
택배사 코드 (lotte, cj, post) |
| items[].trackingNumber |
String |
필수 |
송장번호 (12자리) |
예시 요청
{
"items": [
{
"courierCode": "lotte",
"trackingNumber": "123456789012"
},
{
"courierCode": "cj",
"trackingNumber": "987654321098"
}
]
}
응답
{
"isSuccess": true,
"results": [
{
"courierCode": "lotte",
"trackingNumber": "123456789012",
"status": "IN_TRANSIT",
"statusText": "배송중",
"receiverName": "홍길동",
"productName": "애플망고 3kg",
"trackingDetails": [
{
"location": "서울 강남구",
"status": "배송중",
"dateTime": "2025-12-02T14:30:00Z"
}
]
}
]
}
배송 상태 코드
| 코드 |
설명 |
| READY | 접수 완료 |
| COLLECTED | 집화 완료 |
| IN_TRANSIT | 배송중 |
| OUT_FOR_DELIVERY | 배송 출발 |
| DELIVERED | 배송 완료 |
| FAILED | 배송 실패 |
택배사 목록 조회
지원하는 택배사 목록을 조회합니다.
요청
GET
/api/v1/tracking/couriers
Headers
| 이름 |
값 |
| Authorization |
Bearer {apiKey}:{secretKey} |
응답
{
"isSuccess": true,
"couriers": [
{
"code": "lotte",
"name": "롯데택배",
"supportsTracking": true,
"supportsRegistration": true
},
{
"code": "cj",
"name": "CJ대한통운",
"supportsTracking": true,
"supportsRegistration": true
},
{
"code": "post",
"name": "우체국택배",
"supportsTracking": true,
"supportsRegistration": false
}
]
}
택배사 계정 등록
택배사 계정을 등록하면 배송 등록, 대량 업로드 등 전체 기능을 사용할 수 있습니다.
📦 택배사별 등록 절차
롯데택배 (lotte): ID, 비밀번호만 입력하면 즉시 등록 완료
CJ대한통운 (cj): ID, 비밀번호 입력 후 문자 인증 필요 (2단계)
요청
POST
/api/v1/courier/accounts/register
Headers
| 이름 |
값 |
| Authorization |
Bearer {apiKey}:{secretKey} |
| Content-Type |
application/json |
Request Body
| 필드 |
타입 |
필수 |
설명 |
| providerId |
String |
필수 |
택배사 코드 ("lotte", "cj" 지원) |
| accountId |
String |
필수 |
택배사 로그인 ID |
| accountPassword |
String |
필수 |
택배사 로그인 비밀번호 |
예시 요청
{
"providerId": "lotte",
"accountId": "your_lotte_id",
"accountPassword": "your_lotte_password"
}
응답 (롯데택배 - 즉시 완료)
{
"isSuccess": true,
"courierAccountKey": "WYA5Rk2hUGKkYNW5Qnkn",
"providerId": "lotte",
"status": "active",
"message": "계정이 성공적으로 등록되었습니다."
}
응답 (CJ대한통운 - 문자 인증 대기)
{
"isSuccess": true,
"courierAccountKey": "ABC123XYZ456",
"providerId": "cj",
"status": "pending_verification",
"message": "문자 인증이 필요합니다. 등록한 휴대폰으로 인증 코드가 발송되었습니다.",
"requiresVerification": true
}
⚠️ CJ대한통운 문자 인증
CJ는 계정 등록 시 CJ 계정에 등록된 휴대폰으로 문자 인증 코드가 발송됩니다. requiresVerification: true 응답을 받으면 사용자에게 인증 코드 입력을 안내하세요.
CJ 문자 인증 완료 (2단계)
POST
/api/v1/courier/accounts/verify
Request Body
{
"courierAccountKey": "ABC123XYZ456",
"verificationCode": "123456"
}
응답 (인증 완료)
{
"isSuccess": true,
"courierAccountKey": "ABC123XYZ456",
"providerId": "cj",
"status": "active",
"message": "계정이 성공적으로 등록되었습니다."
}
💡 courierAccountKey
응답으로 받은 courierAccountKey는 배송 등록 시 사용됩니다. 안전하게 보관하세요.
택배사 계정 목록
등록된 택배사 계정 목록을 조회합니다.
요청
GET
/api/v1/courier/accounts
Headers
| 이름 |
값 |
| Authorization |
Bearer {apiKey}:{secretKey} |
응답
{
"isSuccess": true,
"accounts": [
{
"courierAccountKey": "WYA5Rk2hUGKkYNW5Qnkn",
"providerId": "lotte",
"providerName": "롯데택배",
"accountId": "your_lotte_id",
"status": "active",
"dateCreated": "2025-12-01T10:00:00Z"
}
]
}
토큰 갱신 (재인증)
CJ대한통운 계정의 토큰이 만료되었을 때 재인증을 수행합니다.
📦 택배사별 토큰 관리
롯데택배 (lotte): 토큰 만료 시 시스템이 자동으로 갱신합니다. 이용자가 토큰 만료를 신경 쓸 필요가 없습니다.
CJ대한통운 (cj): 토큰 만료 시 이용자가 직접 재인증 로직을 구현해야 합니다. 시스템이 자동으로 갱신할 수 없습니다.
⚠️ CJ 토큰 만료 처리
CJ 계정을 사용하는 API 호출 시 토큰 만료 에러가 발생하면, 이 API를 호출하여 재인증을 수행해야 합니다. CJ는 문자 인증(SMS OTP)이 필요합니다.
요청
POST
/api/v1/courier/accounts/:accountKey/reauth
Headers
| 이름 |
값 |
설명 |
| Authorization |
Bearer {apiKey}:{secretKey} |
필수 |
URL Parameters
| 이름 |
타입 |
필수 |
설명 |
| accountKey |
string |
✅ |
재인증할 택배 계정 키 |
응답 (문자 인증 필요)
{
"isSuccess": true,
"requiresOtp": true,
"sessionId": "temp_session_xyz789",
"message": "CJ 계정에 등록된 휴대폰으로 1522-7513에서 문자가 발송됩니다. 휴대폰 번호 뒤 4자리를 답장으로 보내주세요. (예: 99)"
}
💡 CJ 문자 인증 방법
- CJ에서 1522-7513 번호로 문자가 발송됩니다.
- 사용자는 해당 번호로 "99"를 답장으로 보냅니다.
- 3분 이내에 OTP 검증 API를 호출해야 합니다.
OTP 검증 (2단계)
POST
/api/v1/courier/accounts/:accountKey/verify-otp
Request Body
{
"sessionId": "temp_session_xyz789",
"otp": "99"
}
응답 (재인증 완료)
{
"isSuccess": true,
"message": "재인증이 완료되었습니다. 계정을 다시 사용할 수 있습니다."
}
💡 토큰 만료 감지
CJ 계정을 사용하는 API 호출 시 "CJ 세션이 만료되었습니다" 에러가 발생하면 이 재인증 API를 호출하세요.
내 발송 건 조회
등록된 택배 계정으로 발송한 배송 건 목록을 조회합니다. 택배사 계정 등록이 필요합니다.
💡 계정 기반 조회
이 API는 택배사 계정을 등록한 후 해당 계정으로 발송한 배송 건을 조회합니다. 송장번호 기반 조회와는 달리 courierAccountKey가 필요합니다.
요청
GET
/api/v1/courier/orders/list?courierAccountKey={key}&startDate={date}&endDate={date}
Headers
| 이름 |
값 |
설명 |
| Authorization |
Bearer {apiKey}:{secretKey} |
필수 |
Query Parameters
| 이름 |
타입 |
필수 |
설명 |
| courierAccountKey |
string |
✅ |
택배 계정 키 (계정 등록 시 발급) |
| startDate |
string |
❌ |
조회 시작일 (YYYY-MM-DD) |
| endDate |
string |
❌ |
조회 종료일 (YYYY-MM-DD) |
응답
{
"isSuccess": true,
"orders": [
{
"orderId": "20241202-001",
"receiverName": "홍길동",
"receiverAddress": "서울시 강남구 테헤란로 123",
"trackingNumber": "123456789012",
"status": "IN_TRANSIT",
"statusText": "배송중",
"productName": "애플망고 3kg",
"createdAt": "2024-12-02T10:30:00Z"
}
],
"total": 1
}
상태 코드
| 코드 |
상태 |
설명 |
| READY |
접수 |
택배사 접수 완료 |
| IN_TRANSIT |
배송중 |
배송 진행 중 |
| OUT_FOR_DELIVERY |
배송출발 |
고객 배송 출발 |
| DELIVERED |
배송완료 |
배송 완료 |
배송 단건 등록
택배사 계정을 사용하여 배송을 등록합니다.
요청
POST
/api/v1/courier/orders/create
Request Body
| 필드 |
타입 |
필수 |
설명 |
| courierAccountKey |
String |
필수 |
택배사 계정 키 |
| receiverName |
String |
필수 |
수령인 이름 |
| receiverPhone1 |
String |
필수 |
수령인 전화번호 |
| receiverAddress |
String |
필수 |
배송 주소 |
| goodsName |
String |
필수 |
상품명 |
| goodsQty |
Number |
선택 |
수량 (기본값: 1) |
예시 요청
{
"courierAccountKey": "WYA5Rk2hUGKkYNW5Qnkn",
"receiverName": "홍길동",
"receiverPhone1": "01012345678",
"receiverAddress": "서울시 강남구 테헤란로 123",
"goodsName": "애플망고 3kg",
"goodsQty": 1
}
응답
{
"isSuccess": true,
"trackingNumber": "123456789012",
"message": "배송이 성공적으로 등록되었습니다."
}
배송 대량 등록
한 번에 최대 1,000개의 배송을 등록할 수 있습니다.
요청
POST
/api/v1/courier/orders/bulk-upload
Request Body
| 필드 |
타입 |
필수 |
설명 |
| courierAccountKey |
String |
필수 |
택배사 계정 키 |
| items |
Array |
필수 |
배송 목록 (최대 1,000개) |
예시 요청
{
"courierAccountKey": "WYA5Rk2hUGKkYNW5Qnkn",
"items": [
{
"receiverName": "홍길동",
"receiverPhone1": "01012345678",
"receiverAddress": "서울시 강남구 테헤란로 123",
"goodsName": "애플망고 3kg",
"goodsQty": 1
},
{
"receiverName": "김영희",
"receiverPhone1": "01098765432",
"receiverAddress": "부산시 해운대구 센텀로 456",
"goodsName": "샤인머스켓 2kg",
"goodsQty": 2
}
]
}
응답
{
"isSuccess": true,
"summary": {
"total": 2,
"success": 2,
"failed": 0
},
"results": [
{
"index": 0,
"isSuccess": true,
"trackingNumber": "123456789012"
},
{
"index": 1,
"isSuccess": true,
"trackingNumber": "210987654321"
}
]
}
발송 목록 조회
등록한 배송 내역을 조회합니다.
요청
GET
/api/v1/courier/orders?courierAccountKey={key}&page={page}&limit={limit}
Query Parameters
| 파라미터 |
타입 |
필수 |
설명 |
| courierAccountKey |
String |
필수 |
택배사 계정 키 |
| page |
Number |
선택 |
페이지 번호 (기본값: 1) |
| limit |
Number |
선택 |
페이지당 개수 (기본값: 50, 최대: 100) |
응답
{
"isSuccess": true,
"page": 1,
"limit": 50,
"total": 127,
"orders": [
{
"trackingNumber": "123456789012",
"receiverName": "홍길동",
"goodsName": "애플망고 3kg",
"status": "DELIVERED",
"statusText": "배송 완료",
"dateCreated": "2025-12-01T10:00:00Z"
}
]
}