주문 정보 전달하기
퀵 배송, 도보 배송 등 배송 요청 시 출발지와 도착지의 상세 정보를 제공합니다. 주문 유형을 선택하고 배송 메시지를 전달할 수 있으며 선택한 서비스에 따라 세부 응답을 받아볼 수 있습니다.
해당 API를 사용하려면 Vendor ID와 API 키값이 필요합니다.
발급 방법은 시작하기의 Vendor ID 및 API 키 발급받기를 참고하세요.
Request
요청 호출 방식과 각 요청 헤더에 포함될 내용을 안내합니다. 요청이 실패할 경우 🔗문제 해결하기에서 에러에 대한 상세 내용을 확인하세요.
호출 방식
| Method | URL |
|---|---|
POST | https://open-api-logistics.kakaomobility .com/goa-sandbox-service/api/v2/orders |
요청 헤더
| Parameter | Description |
|---|---|
| Authorization | 시작하기에서 생성한 Authorization 파라미터 값 |
| vendor | kakaoT 퀵∙도보 배송 API Sandbox에서 발급받은 Vendor 아이디 |
| Content-Type | application/json |
요청 코드 예제
REST API를 호출하려면 요청 헤더의 Authorization 파라미터 값이 필요합니다. 이를 생성하려면 먼저 Signkey 값을 생성해야 합니다.
퀵 주문
curl -X 'POST' \
'https://open-api-logistics.kakaomobility.com/goa-sandbox-service/api/v2/orders' \
-H 'accept: application/json' \
-H 'vendor:${vendor_id}' \
-H 'Content-Type: application/json' \
-H 'Authorization: XXX' \
-d '{
"partnerOrderId": "{연동사 주문 ID - 유니크 해야합니다}",
"orderType": "QUICK",
"pickup": {
"location": {
"basicAddress": "서울특별시 강남구 역삼동 xxx",
"detailAddress": "1층",
"latitude": 37.4354059,
"longitude": 126.74551
},
"contact": {
"name": "전달하는 사람 이름",
"phone": "010-1000-0001"
}
},
"waypoints": [{
"location": {
"basicAddress": "서울특별시 강남구 삼성동 xxx",
"detailAddress": "3층",
"latitude": 37.5087956,
"longitude": 127.0632929
},
"contact": {
"name": "경유지1 담당자",
"phone": "010-1000-0003"
},
"note": "경유지1 요청사항"
}],
"dropoff": {
"location": {
"basicAddress": "서울특별시 강남구 일원동 xxx",
"detailAddress": "2층",
"latitude": 37.569691,
"longitude": 126.825791
},
"contact": {
"name": "받는 사람 이름",
"phone": "010-1000-0002"
}
},
"productInfo": {
"trayCount": 1,
"size": "XS",
"totalPrice": 29800,
"products": [
{
"name": "양념게장 (대)",
"quantity": "1",
"price": 29800,
"detail": "터지면 큰일남"
}
]
},
"paymentInfo": {
"paymentType": "CASH_ON_PICKUP"
}
}'요청에 대한 파라미터는 다음과 같습니다.
| Name | Type | Description | Required |
|---|---|---|---|
orderType | Enum | 주문 유형 다음 중 하나: QUICK: 퀵QUICK_ECONOMY: 퀵 이코노미QUICK_EXPRESS: 퀵 급송DOBO: 도보 배송 | 필수 |
partnerOrderId | String | 연동사 주문 아이디 (내부에서 사용하시는 주문 아이디) | 필수 |
Object | 차량 선택 | 선택 | |
Object | 배송 유의사항 | 필수 | |
Object | 출발지 정보 | 필수 | |
Object[] | 경유지 정보 배열 | 선택 | |
Object | 목적지 정보 | 필수 | |
Object | 기타 옵션 | 선택 | |
Object | 의뢰인 정보 | 선택 | |
Object | 선불/출발지현금/도착지현금 | 선택 |
| Condition | Description |
|---|---|
waypoints 배열 요소 개수 | 10개 이하 |
| Body에 waypoints 포함한 상태에서 1. orderType이 다음 중 하나 DOBO: 도보ROBOT: 로봇QUICK_ECONOMY: 퀵 이코노미2. paymentType이 다음 중 하나 CASH_ON_PICKUPCASH_ON_DROPOFF | 미지원 |
Response
응답 성공 시 요청에 대한 성공 여부를 HTTP 상태 코드로, 요청 본문은 JSON 포맷으로 전달합니다.
응답 코드 예제
{
"requestId": "11dd41ec-f030-41ed-a732-18564c0858b3",
"partnerOrderId": "9b6d46c9-0e2f-4fb4-8c13-4f7d12c3a801",
"receipt": {
"orderId": "qo_20260317_00012345",
"orderType": "QUICK",
"status": "MATCHING",
"priceInfo": {
"totalPrice": 18500,
"paymentType": "CARD"
},
"histories": []
},
"pickup": {
"stepId": "pickup_step_id",
"location": {
"basicAddress": "경기도 성남시 판교 어쩌구",
"detailAddress": "1층",
"latitude": 37.3862353,
"longitude": 127.1117317
},
"contact": {
"name": "전달하는 사람 이름",
"phone": "01010000001"
},
"statusUpdatedAt": "2026-03-17T14:20:31.120+09:00"
},
"waypoints": [{
"stepId": "waypoint1_step_id",
"location": {
"basicAddress": "서울특별시 강남구 삼성동 159",
"detailAddress": "3층",
"latitude": 37.5087956,
"longitude": 127.0632929
},
"contact": {
"name": "경유지1 사람 이름",
"phone": "01010000003"
},
"statusUpdatedAt": "2026-03-17T14:20:31.120+09:00"
}],
"dropoff": {
"stepId": "dropoff_step_id",
"location": {
"basicAddress": "서울특별시 강남구 일원동 741",
"detailAddress": "2층",
"latitude": 37.490694420048,
"longitude": 127.079607
},
"contact": {
"name": "받는 사람 이름",
"phone": "01010000002"
},
"statusUpdatedAt": "2026-03-17T14:20:31.120+09:00"
}
}요청 응답에 대한 객체 정보는 다음과 같습니다.
| Name | Type | Description | Required |
|---|---|---|---|
requestId | String | 요청 아이디 | 선택 |
partnerOrderId | String | 연동사 주문 아이디 | 선택 |
Object | 주문 정보 | 선택 | |
Object | 출발지 정보 | 선택 | |
Object[] | 경유지 정보 | 선택 | |
Object | 목적지 정보 | 선택 |