문서 메뉴 · 개요

싼퀵 개발자센터

퀵서비스 배송 API

여러 퀵서비스 업체의 요금을 실시간으로 비교해
가장 저렴한 곳으로 배송을 요청합니다.

견적 조회·주문·취소·배송 상태 웹훅까지 REST API 하나로 연동합니다.

이런 팀을 위한 API입니다

쇼핑몰 · 커머스주문이 들어오면 퀵이 자동 접수

당일 배송 상품 주문을 그대로 퀵 주문으로 넘깁니다. 담당자가 전화나 앱으로 옮겨 적지 않습니다.

사내 시스템 · ERP반복 발송을 시스템에서 처리

서류·샘플·부품처럼 매일 나가는 발송을 사내 화면에서 바로 접수하고 상태를 자동으로 받습니다.

서비스 · 플랫폼내 앱에 퀵 배송 기능 추가

업체별 계약과 비교 로직 없이 퀵 배송을 자사 서비스 기능으로 붙입니다.

연동하면 달라지는 것

계약도 연동도 한 번

업체마다 따로 계약하고 API를 붙일 필요가 없습니다.

가격 비교를 만들지 않아도 됩니다

요청 한 번에 여러 업체 요금이 실시간으로 비교된 상태로 옵니다. 주문은 서비스 유형만 고르면 가장 저렴한 업체로 접수됩니다.

배차 실패에도 주문이 멈추지 않습니다

자동 라우팅(업체전환)을 켜두면 다음 순위 업체로 자동 전환되고, 웹훅으로 알려드립니다.

시작하기

테스트 키 발급. 대시보드 > API
연동 검증. 테스트 환경에서 견적·주문·취소와 웹훅을 검증합니다. 실제 결제·배차는 발생하지 않습니다.
운영 사용 신청. 대시보드 > API에서 신청하면 승인 후 운영 키를 발급할 수 있습니다.

연동 흐름

견적 조회 흐름

1
견적 요청
출발지·도착지 정보를 보냅니다.
2
요금 조회
서버에서 배송업체별 현재 요금을 조회합니다.
3
견적 응답
배송업체·서비스 유형별 예상 요금과 소요 시간을 반환합니다.

전체 주문 흐름

1
주문 요청
출발지·도착지와 배송 정보를 보냅니다.
2
배송업체 주문 접수
요청한 서비스 유형(이코노미, 일반, 급송)의 최저가 업체에 주문을 접수합니다. 요금은 등록된 카드로 결제됩니다.
3
기사 배정·배송
기사가 배정된 뒤 물품을 픽업하고 배송합니다.
4
배송 완료
물품이 수령인에게 전달되면 배송이 완료됩니다.

주문 취소 흐름

선택: 취소 전에 취소 수수료 조회 API로 예상 수수료와 환불액을 확인할 수 있습니다.

1
취소 요청
주문 ID와 취소 사유를 보냅니다.
2
배송업체 주문 취소
배송업체에 주문 취소를 요청하고 결과를 확인합니다.
3
환불
주문 취소가 완료되면 결제 금액에서 취소 수수료를 제외한 금액을 환불합니다.

API 살펴보기

POST/quotes견적 조회POST/orders주문 생성GET/orders/{orderId}주문 조회POST/orders/{orderId}/cancel주문 취소

테스트 환경

테스트 환경의 제약사항과 특이사항입니다.

제약사항

이메일 인증 후 승인 없이 테스트 키를 발급할 수 있습니다.
결제·기사 배정·배송·취소·환불은 시뮬레이션입니다.
실제 카드 청구·기사 접수·문자·이메일 주문 알림은 발생하지 않습니다.
웹훅은 등록한 주소로 실제 전송됩니다.
테스트 웹훅 등록 정보와 키는 운영과 별도로 관리됩니다.
테스트 주문·로그는 운영에 이관되지 않습니다.
주문과 웹훅 내역은 7일간 보관합니다.

인증

모든 API 요청은 Bearer API 키로 인증합니다.

Base URL

운영 — sk_live_ 키

https://ssanquick.com/api/v1

테스트 — sk_test_ 키

https://sandbox.ssanquick.com/api/v1

환경마다 주소와 키가 다릅니다. 테스트 키를 운영 주소로 보내면 인증이 거절됩니다.
테스트 키 발급은 대시보드 API 메뉴에서 합니다. 웹훅 테스트 전송은 테스트 탭에서만 제공합니다.

인증 헤더

HTTP

Authorization: Bearer <API 키>

API 키는 대시보드 > API에서 발급합니다.

응답 형식

성공 응답은 success: true와 data를 반환합니다.
실패 응답은 success: false와 error를 반환합니다.

오류 응답

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "유효하지 않은 API 키입니다."
  }
}

성공·실패를 가리지 않고 모든 응답에 X-Request-Id 헤더가 붙습니다.
장애 문의 시 이 값을 함께 알려주시면 해당 요청을 바로 찾을 수 있습니다.

공통 오류 보기 →

오류

HTTP 상태와 error.code로 실패 원인을 구분합니다.

오류 응답

JSON

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "요청값을 다시 확인해주세요."
  }
}

오류 응답 필드

필드명	타입	설명	포함 조건
success	boolean	항상 false	항상
error.code	string	프로그램에서 분기할 오류 코드	항상
error.message	string	오류 설명	항상
error.details	object	추가 오류 정보	제공되는 경우

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

오류 코드

HTTP	오류 코드	의미	처리 방법
400	invalid_request	JSON 본문을 읽을 수 없습니다.	JSON 형식을 확인합니다.
400	invalid_request	현재 주문 상태에서는 처리할 수 없습니다. (예: 배송이 완료되어 취소할 수 없습니다.)	주문을 조회해 현재 상태를 확인합니다. 같은 요청을 재시도해도 결과는 같습니다.
415	invalid_request	요청 본문의 형식이 올바르지 않습니다.	Content-Type을 application/json으로 보냅니다.
422	invalid_request	요청값이 올바르지 않습니다.	필수 필드와 입력값을 확인합니다.
422	invalid_request	출발지 또는 도착지 주소를 찾지 못했습니다.	기본 주소에는 도로명 주소와 건물번호까지만 보내고 층·호수·건물명은 상세 주소 필드에 넣습니다. 같은 주소로 재시도해도 결과는 같습니다.
401	invalid_api_key	API 키가 유효하지 않습니다.	환경과 API 키를 확인합니다.
402	payment_failed	등록 카드 결제가 거절됐습니다. 주문은 생성되지 않습니다.	카드 상태를 확인한 뒤 같은 clientOrderId로 다시 요청하면 재결제를 시도합니다.
404	order_not_found	주문을 찾을 수 없습니다.	orderId를 확인합니다.
409	payment_required	등록된 결제 카드가 없습니다.	대시보드에서 카드를 등록합니다.
409	order_in_progress	같은 주문 요청을 처리 중입니다.	같은 clientOrderId로 다시 요청합니다.
503	order_in_progress	배송업체의 주문 접수 결과를 확인하고 있습니다.	같은 clientOrderId로 다시 요청합니다.
429	rate_limited	요청 한도를 초과했습니다.	Retry-After 이후 다시 요청합니다.
500	internal_error	요청 처리 중 오류가 발생했습니다.	잠시 후 다시 요청합니다.
500	payment_status_unknown	결제 결과를 확인할 수 없습니다.	주문 목록을 확인하고 고객센터에 문의합니다.
503	payment_status_unknown	결제 결과 확인이 지연되고 있습니다.	주문 목록을 확인하고 고객센터에 문의합니다.
502	order_failed	주문 접수에 실패하고 결제가 취소됐습니다.	새 주문이 필요하면 다시 요청합니다.
500	refund_failed	주문 접수 실패 후 카드 환불에 실패했습니다.	주문을 조회하고 고객센터에 문의합니다.
502	refund_failed	주문 취소 후 카드 환불에 실패했습니다.	주문을 조회하고 고객센터에 문의합니다.
503	service_unavailable	배송 서비스 응답을 확인할 수 없습니다.	잠시 후 다시 요청합니다.

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

버전 관리

API의 주 버전은 URL에서 구분합니다.

현재 버전

/api/v1

기존 연동을 깨뜨리는 변경은 새 주 버전으로 제공합니다.
선택 필드 추가와 새 오류 코드 추가처럼 기존 요청을 유지하는 변경은 v1에 반영될 수 있습니다.

주문 상태

API에서 공통으로 사용하는 주문 상태입니다.

상태 정의

필드명	타입	설명	포함 조건
accepted	string	배송업체 접수 완료, 기사 배정 전	항상
driver_assigned	string	기사 배정 완료	항상
picked_up	string	기사가 물품을 인수해 배송 중	항상
completed	string	배송 완료	항상
cancelled	string	주문 취소 완료 (배차 불가로 인한 자동 취소 포함)	항상

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

견적 조회

출발지와 도착지의 오토바이 퀵 요금을 배송업체별로 조회합니다.

POST/api/v1/quotes

요청 필드

필드명	필수	형식·제약
departureAddress	필수	출발지 기본 주소. 도로명 주소와 건물번호까지 입력
destinationAddress	필수	도착지 기본 주소. 도로명 주소와 건물번호까지 입력
vehicleType	필수	motorcycle
departureAddressDetail	선택	출발지 층·호수 등 상세 주소
destinationAddressDetail	선택	도착지 층·호수 등 상세 주소

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

요청 예시

cURL

curl -X POST https://ssanquick.com/api/v1/quotes   -H "Authorization: Bearer <API 키>"   -H "Content-Type: application/json"   -d '{
    "departureAddress": "서울 강남구 테헤란로 123",
    "departureAddressDetail": "10층",
    "destinationAddress": "서울 서초구 서초대로 456",
    "vehicleType": "motorcycle"
  }'

성공 응답

아래는 예시 응답입니다. 실제 응답에는 조회 시점에 요금을 응답한 여러 업체가 담기며, 업체 수와 순서는 조회마다 다릅니다.

JSON

{
  "success": true,
  "data": {
    "departureAddress": "서울 강남구 테헤란로 123",
    "destinationAddress": "서울 서초구 서초대로 456",
    "vehicleType": "motorcycle",
    "offers": [
      {
        "carrier": "A업체",
        "serviceType": "economy",
        "price": 8000,
        "estimatedTime": "3시간 내",
        "estimatedTimeSeconds": 10800
      },
      {
        "carrier": "B업체",
        "serviceType": "standard",
        "price": 12000,
        "estimatedTime": "2시간 내",
        "estimatedTimeSeconds": 7200
      },
      {
        "carrier": "A업체",
        "serviceType": "standard",
        "price": 12000,
        "estimatedTime": "1시간 30분 내",
        "estimatedTimeSeconds": 5400
      },
      {
        "carrier": "B업체",
        "serviceType": "express",
        "price": 16000,
        "estimatedTime": "45분 내",
        "estimatedTimeSeconds": 2700
      },
      {
        "carrier": "A업체",
        "serviceType": "express",
        "price": 16000,
        "estimatedTime": "45분 내",
        "estimatedTimeSeconds": 2700
      }
    ],
    "createdAt": "2026-09-07T03:00:00.000Z"
  }
}

응답 필드

필드명	타입	설명	포함 조건
success	boolean	요청 성공 여부	항상
data	object	견적 결과	항상
data.departureAddress	string	출발지 주소	항상
data.destinationAddress	string	도착지 주소	항상
data.vehicleType	string	motorcycle	항상
data.offers	object[]	견적 목록. 금액 오름차순	항상
data.offers[].carrier	string	응답 내 업체 구분용. 주문 선택값이 아니며, 요청 간 동일 업체를 보장하지 않습니다	항상
data.offers[].serviceType	string	economy, standard, express	항상
data.offers[].price	number	견적 금액(원)	항상
data.offers[].estimatedTime	string \| null	예상 소요 시간	항상
data.offers[].estimatedTimeSeconds	number \| null	예상 소요 시간(초)	항상
data.createdAt	string	견적 생성 시각(ISO 8601)	항상

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

주문 생성

배송 정보를 전송해 주문을 생성하고 등록 카드로 결제합니다. 배송업체는 지정하지 않으며, 요청한 서비스 유형에서 주문 시점 최저가 업체로 자동 접수됩니다.

POST/api/v1/orders

배송업체 자동 선정

주문 요청에는 업체를 지정하는 필드가 없습니다. serviceType만 지정합니다.
주문 시점에 싼퀵이 접수할 수 있는 업체 중 해당 서비스 유형(이코노미, 일반, 급송)의 최저가 업체로 접수됩니다.
결제 금액은 응답의 price로 확정되며, 견적 조회 금액과 다를 수 있습니다.

자동 라우팅(업체전환)

배차 실패·업체 취소·기사 배정 지연 시 다음 순위 업체·상품으로 자동 라우팅합니다.
대시보드 › 설정 › 주문 설정의 자동 라우팅(업체전환)이 켜져 있을 때만 동작하며, 급송 제외가 켜져 있으면 급송으로는 라우팅하지 않습니다.
새 요금이 더 높으면 차액이 등록 카드로 추가 결제됩니다. 추가 결제는 payments[]에 reason: "reroute"로 남고, 영수증도 건별로 들어 있습니다.
라우팅 후 price는 추가 결제를 포함한 누적 금액입니다. 새 기사가 배정되면 order.driver_reassigned가 전달되며, data.price로 누적 금액을 함께 보냅니다.
배차 실패·업체 취소 시 라우팅할 곳이 없으면 자동 취소·전액 환불되고 order.cancelled가 전달됩니다.

요청 필드

필드명	필수	형식·제약
departureAddress	필수	출발지 기본 주소. 도로명 주소와 건물번호까지 입력
destinationAddress	필수	도착지 기본 주소. 도로명 주소와 건물번호까지 입력
departureAddressDetail	선택	출발지 층·호수 등 상세 주소
destinationAddressDetail	선택	도착지 층·호수 등 상세 주소
vehicleType	필수	motorcycle
serviceType	필수	economy, standard, express
senderName	필수	발송인 이름
senderPhone	필수	발송인 연락처
receiverName	필수	수령인 이름
receiverPhone	필수	수령인 연락처
clientOrderId	필수	고객사 주문 식별자. 같은 값으로 다시 요청하면 기존 주문을 반환. 결제가 거절된 요청은 같은 값으로 다시 요청하면 재결제를 시도
productSize	선택	XS: 초소형, 세 변 합 70cm 이하, 2kg 이하 S: 소형, 세 변 합 100cm 이하, 5kg 이하 M: 중형, 세 변 합 140cm 이하, 20kg 이하 생략 시 M
driverNote	선택	기사 전달 사항

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

요청 예시

cURL

curl -X POST https://ssanquick.com/api/v1/orders   -H "Authorization: Bearer <API 키>"   -H "Content-Type: application/json"   -d '{
    "departureAddress": "서울 강남구 테헤란로 123",
    "departureAddressDetail": "10층",
    "destinationAddress": "서울 서초구 서초대로 456",
    "destinationAddressDetail": "3층",
    "vehicleType": "motorcycle",
    "serviceType": "standard",
    "productSize": "M",
    "senderName": "홍길동",
    "senderPhone": "01011112222",
    "receiverName": "김철수",
    "receiverPhone": "01033334444",
    "clientOrderId": "partner-order-1001",
    "driverNote": "도착 전에 연락해주세요"
  }'

성공 응답

price는 실제 결제된 금액입니다. 견적 조회 금액과 다를 수 있습니다.
주문 생성과 같은 clientOrderId의 재요청은 모두 HTTP 200을 반환합니다.
재요청 시에는 기존 주문 식별 정보를 반환합니다.
결제가 거절된 요청(402)은 주문으로 남지 않으며, 같은 clientOrderId로 다시 요청하면 재결제를 시도합니다.

JSON

{
  "success": true,
  "data": {
    "orderId": "ord_example",
    "clientOrderId": "partner-order-1001",
    "status": "accepted",
    "price": 12000,
    "createdAt": "2026-09-07T03:00:00.000Z"
  }
}

응답 필드

필드명	타입	설명	포함 조건
success	boolean	요청 성공 여부	항상
data	object	생성된 주문	항상
data.orderId	string	주문 조회·취소에 사용하는 싼퀵 API 주문 ID	항상
data.clientOrderId	string \| null	고객사 내부 주문 식별자	항상
data.status	string	주문 상태	항상
data.price	number	결제된 주문 금액(원)	항상
data.createdAt	string	주문 생성 시각(ISO 8601)	항상

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

주문 조회

주문 ID로 현재 주문 정보를 조회합니다.

GET/api/v1/orders/{orderId}

요청 필드

필드명	필수	형식·제약
orderId (경로)	필수	주문 생성 응답의 orderId

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

요청 예시

cURL

curl https://ssanquick.com/api/v1/orders/{orderId} \
  -H "Authorization: Bearer <API 키>"

성공 응답

JSON

{
  "success": true,
  "data": {
    "orderId": "ord_example",
    "clientOrderId": "partner-order-1001",
    "status": "driver_assigned",
    "price": 12000,
    "payments": [
      {
        "reason": "initial",
        "amount": 12000,
        "status": "paid",
        "paidAt": "2026-09-07T02:58:00.000Z",
        "receiptUrl": "https://dashboard.tosspayments.com/receipt/example-1"
      },
      {
        "reason": "reroute",
        "amount": 2900,
        "status": "paid",
        "paidAt": "2026-09-07T03:00:00.000Z",
        "receiptUrl": "https://dashboard.tosspayments.com/receipt/example-2"
      }
    ],
    "serviceType": "standard",
    "departureAddress": "서울 강남구 테헤란로 123",
    "destinationAddress": "서울 서초구 서초대로 456",
    "driverName": "김기사",
    "driverPhone": "010-1234-5678",
    "createdAt": "2026-09-07T03:00:00.000Z",
    "updatedAt": "2026-09-07T03:00:00.000Z"
  }
}

응답 필드

필드명	타입	설명	포함 조건
success	boolean	요청 성공 여부	항상
data	object	조회한 주문	항상
data.orderId	string	주문 조회·취소에 사용하는 싼퀵 API 주문 ID	항상
data.clientOrderId	string \| null	고객사 내부 주문 식별자	항상
data.status	string	주문 상태	항상
data.price	number	주문 금액(원). 자동 라우팅 시 누적 금액	항상
data.serviceType	string	배송 서비스 유형 economy: 이코노미 standard: 일반 express: 급송	항상
data.departureAddress	string	출발지 기본 주소	항상
data.destinationAddress	string	도착지 기본 주소	항상
data.createdAt	string	주문 생성 시각(ISO 8601)	항상
data.departureAddressDetail	string	출발지 상세 주소	입력한 경우
data.destinationAddressDetail	string	도착지 상세 주소	입력한 경우
data.driverName	string	배정된 기사 이름	배송업체에서 제공한 경우
data.driverPhone	string	배정된 기사 연락처	배송업체에서 제공한 경우
data.updatedAt	string	마지막 변경 시각(ISO 8601)	항상
data.payments	object[]	건별 결제·영수증. 승인 시각 오름차순	항상
data.payments[].reason	string	결제 사유. initial · reroute · surcharge	항상
data.payments[].amount	number	이 건의 결제 금액(원)	항상
data.payments[].status	string	paid · cancelled · partially_refunded	항상
data.payments[].refundAmount	number	환불된 금액(원)	환불이 있을 때만
data.payments[].paidAt	string	승인 시각(ISO 8601)	항상
data.payments[].receiptUrl	string	영수증 링크	발급된 경우만
data.cancellationFee	number	취소 수수료(원)	취소 완료 후
data.refundAmount	number	환불액(원)	취소 완료 후

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

주문 목록

고객사의 주문을 최신순으로 조회합니다.

GET/api/v1/orders

요청 필드

필드명	필수	형식·제약
page (쿼리)	선택	페이지 번호. 기본값 1
limit (쿼리)	선택	페이지당 항목 수. 기본값 20, 최대 100

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

요청 예시

cURL

curl "https://ssanquick.com/api/v1/orders?page=1&limit=20" \
  -H "Authorization: Bearer <API 키>"

성공 응답

JSON

{
  "success": true,
  "data": {
    "items": [
      {
        "orderId": "ord_example",
        "clientOrderId": "partner-order-1001",
        "status": "accepted",
        "price": 12000,
        "serviceType": "standard",
        "departureAddress": "서울 강남구 테헤란로 123",
        "destinationAddress": "서울 서초구 서초대로 456",
        "createdAt": "2026-09-07T03:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1
    }
  }
}

응답 필드

필드명	타입	설명	포함 조건
success	boolean	요청 성공 여부	항상
data.items	object[]	주문 목록	항상
data.items[].orderId	string	주문 조회·취소에 사용하는 싼퀵 API 주문 ID	항상
data.items[].clientOrderId	string \| null	고객사 내부 주문 식별자	항상
data.items[].status	string	주문 상태	항상
data.items[].price	number	주문 금액(원). 자동 라우팅 시 누적 금액	항상
data.items[].serviceType	string	배송 서비스 유형 economy: 이코노미 standard: 일반 express: 급송	항상
data.items[].departureAddress	string	출발지 기본 주소	항상
data.items[].destinationAddress	string	도착지 기본 주소	항상
data.items[].createdAt	string	주문 생성 시각(ISO 8601)	항상
data.pagination.page	number	현재 페이지	항상
data.pagination.limit	number	페이지당 항목 수	항상
data.pagination.total	number	전체 주문 수	항상

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

취소 수수료 조회

취소 가능 여부와 예상 환불액을 조회합니다.

GET/api/v1/orders/{orderId}/cancel-fee

요청 필드

필드명	필수	형식·제약
orderId (경로)	필수	주문 생성 응답의 orderId

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

요청 예시

cURL

curl https://ssanquick.com/api/v1/orders/{orderId}/cancel-fee \
  -H "Authorization: Bearer <API 키>"

성공 응답

JSON

{
  "success": true,
  "data": {
    "cancellable": true,
    "fee": 0,
    "refundAmount": 12000
  }
}

응답 필드

필드명	타입	설명	포함 조건
success	boolean	요청 성공 여부	항상
data.cancellable	boolean	취소 가능 여부	항상
data.fee	number	취소 수수료(원)	항상
data.refundAmount	number	예상 환불액(원)	항상
data.reason	string	취소할 수 없는 이유	취소 불가 시

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

주문 취소

배송을 취소하고 등록 카드 결제를 환불합니다.

POST/api/v1/orders/{orderId}/cancel

요청 필드

필드명	필수	형식·제약
orderId (경로)	필수	주문 생성 응답의 orderId
cancelReason	필수	취소 사유

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

요청 예시

cURL

curl -X POST https://ssanquick.com/api/v1/orders/{orderId}/cancel   -H "Authorization: Bearer <API 키>"   -H "Content-Type: application/json"   -d '{"cancelReason":"고객 요청"}'

성공 응답

취소된 주문을 다시 취소하면 같은 주문 상태를 반환합니다.

JSON

{
  "success": true,
  "data": {
    "orderId": "ord_example",
    "clientOrderId": "partner-order-1001",
    "status": "cancelled",
    "cancellationFee": 0,
    "refundAmount": 12000,
    "updatedAt": "2026-09-07T03:01:00.000Z"
  }
}

응답 필드

필드명	타입	설명	포함 조건
success	boolean	요청 성공 여부	항상
data	object	취소 처리 후 주문	항상
data.orderId	string	주문 조회·취소에 사용하는 싼퀵 API 주문 ID	항상
data.clientOrderId	string \| null	고객사 내부 주문 식별자	항상
data.status	string	취소 완료 상태. cancelled	항상
data.cancellationFee	number	취소 수수료(원)	항상
data.refundAmount	number	환불액(원)	항상
data.updatedAt	string	취소 처리 시각(ISO 8601)	항상

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

웹훅

주문 이벤트를 등록한 HTTPS 주소로 전달합니다.

웹훅 키

대시보드 > API에서 웹훅을 등록하면 웹훅 키를 발급합니다.
수신 요청의 X-Ssanquick-Webhook-Key 값이 발급받은 키와 일치하는지 확인합니다.

웹훅 키를 재발급하면 기존 키는 즉시 만료됩니다.
새 키를 수신 서버에 반영하세요.

이벤트별 샘플 본문은 대시보드 › API의 테스트 탭에서 전송할 수 있습니다.
운영 탭은 실제 주문 이벤트와 기존 실패 이력의 재전송만 지원합니다.

요청 헤더

X-Ssanquick-Webhook-Key: whsec_…

웹훅 재전송 흐름

1
최초 전송
이벤트 본문과 웹훅 키를 등록한 주소로 보냅니다.
2
직전 실패 후 1분
첫 번째 재시도
응답 시간 초과 또는 2xx 이외 응답이면 다시 보냅니다.
3
직전 실패 후 5분
두 번째 재시도
같은 이벤트 ID와 본문으로 다시 보냅니다.
4
직전 실패 후 30분
마지막 자동 재시도
최초 전송을 포함해 최대 4회 시도합니다.
5
실패로 종료
4회 모두 실패하면 자동 재시도를 종료합니다. 수신 서버의 키·응답 상태를 확인합니다.
6
대시보드에서 재전송
장애 해결 후 API > 웹훅 전송 내역에서 재전송합니다. 같은 이벤트 ID와 현재 웹훅 키로 전송합니다.

전달 정책

공개 인터넷에서 접근 가능한 HTTPS 443 주소만 허용합니다(내부망·예약 IP 불가). 리다이렉트는 따라가지 않습니다.
테스트 환경 수신처는 공개 IPv4 주소가 하나 이상 있어야 합니다(IPv6 전용 호스트 불가).
10초 안에 2xx 를 반환해야 성공으로 기록됩니다 — 무거운 처리는 응답 후 비동기로 하세요.
2xx 응답을 받지 못한 건은 아래 재시도 규칙에 따라 다시 보냅니다.
자동 라우팅(업체전환)으로 다시 접수되면 order.driver_reassigned가 전달됩니다.

재시도·재전송

2xx 를 받지 못하면 1분 → 5분 → 30분 간격으로 최대 4회 시도합니다.
재시도된 건은 같은 id로 다시 갑니다.
수신처가 이미 처리했더라도 2xx 를 돌려주지 못하면 다시 보내므로, id로 중복을 걸러 주세요.
이벤트 수신 순서가 바뀔 수 있습니다. 최종 상태는 주문 조회로 확인하세요.
재시도가 소진된 건은 대시보드 웹훅 전송 내역에서 다시 보낼 수 있습니다.

order.driver_assigned

기사 배정

기사 배정을 확인했을 때 전달합니다. 기사 정보는 확인된 항목만 포함합니다.

JSON

{
  "id": "whd_example",
  "event": "order.driver_assigned",
  "occurredAt": "2026-09-07T03:00:00.000Z",
  "data": {
    "orderId": "ord_example",
    "clientOrderId": "partner-order-1001",
    "price": 12000,
    "payments": [
      {
        "reason": "initial",
        "amount": 12000,
        "status": "paid",
        "paidAt": "2026-09-07T02:58:00.000Z",
        "receiptUrl": "https://dashboard.tosspayments.com/receipt/example-1"
      }
    ],
    "driverName": "김기사",
    "driverPhone": "010-1234-5678"
  }
}

수신 필드

필드명	타입	설명	포함 조건
id	string	이벤트 ID. 재시도·재전송에서도 동일	항상
event	string	이벤트 유형: order.driver_assigned	항상
occurredAt	string	이벤트 발생 시각(ISO 8601). 주문 조회 응답의 createdAt(주문 생성 시각)과 다른 값입니다	항상
data	object	이벤트가 발생한 주문 정보	항상
data.orderId	string	주문 조회에 사용하는 싼퀵 API 주문 ID	항상
data.clientOrderId	string \| null	고객사 내부 주문 식별자	항상
data.price	number	결제 확정 누적 금액(원). 자동 라우팅 추가 결제를 포함합니다	항상
data.payments	object[]	건별 결제·영수증. 승인 시각 오름차순	항상
data.payments[].reason	string	initial · reroute · surcharge	항상
data.payments[].amount	number	이 건의 결제 금액(원)	항상
data.payments[].status	string	paid · cancelled · partially_refunded	항상
data.payments[].refundAmount	number	환불된 금액(원)	환불이 있을 때만
data.payments[].paidAt	string	승인 시각(ISO 8601)	항상
data.payments[].receiptUrl	string	영수증 링크	발급된 경우만
data.driverName	string	기사 이름	확인된 경우
data.driverPhone	string	기사 전화번호	확인된 경우

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

order.driver_reassigned

기사 재배정

배정 기사가 변경됐을 때 전달합니다. 업체 자체 재배차와 자동 라우팅(업체전환)이 모두 해당합니다. 기사 정보는 확인된 항목만 포함합니다.

JSON

{
  "id": "whd_example",
  "event": "order.driver_reassigned",
  "occurredAt": "2026-09-07T03:00:00.000Z",
  "data": {
    "orderId": "ord_example",
    "clientOrderId": "partner-order-1001",
    "price": 14900,
    "payments": [
      {
        "reason": "initial",
        "amount": 12000,
        "status": "paid",
        "paidAt": "2026-09-07T02:58:00.000Z",
        "receiptUrl": "https://dashboard.tosspayments.com/receipt/example-1"
      },
      {
        "reason": "reroute",
        "amount": 2900,
        "status": "paid",
        "paidAt": "2026-09-07T03:00:00.000Z",
        "receiptUrl": "https://dashboard.tosspayments.com/receipt/example-2"
      }
    ],
    "driverName": "이기사",
    "driverPhone": "010-9876-5432"
  }
}

수신 필드

필드명	타입	설명	포함 조건
id	string	이벤트 ID. 재시도·재전송에서도 동일	항상
event	string	이벤트 유형: order.driver_reassigned	항상
occurredAt	string	이벤트 발생 시각(ISO 8601). 주문 조회 응답의 createdAt(주문 생성 시각)과 다른 값입니다	항상
data	object	이벤트가 발생한 주문 정보	항상
data.orderId	string	주문 조회에 사용하는 싼퀵 API 주문 ID	항상
data.clientOrderId	string \| null	고객사 내부 주문 식별자	항상
data.price	number	결제 확정 누적 금액(원). 자동 라우팅 추가 결제를 포함합니다	항상
data.payments	object[]	건별 결제·영수증. 승인 시각 오름차순	항상
data.payments[].reason	string	initial · reroute · surcharge	항상
data.payments[].amount	number	이 건의 결제 금액(원)	항상
data.payments[].status	string	paid · cancelled · partially_refunded	항상
data.payments[].refundAmount	number	환불된 금액(원)	환불이 있을 때만
data.payments[].paidAt	string	승인 시각(ISO 8601)	항상
data.payments[].receiptUrl	string	영수증 링크	발급된 경우만
data.driverName	string	기사 이름	확인된 경우
data.driverPhone	string	기사 전화번호	확인된 경우

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

order.picked_up

픽업 완료

기사가 물품을 인수했을 때 전달합니다.

JSON

{
  "id": "whd_example",
  "event": "order.picked_up",
  "occurredAt": "2026-09-07T03:00:00.000Z",
  "data": {
    "orderId": "ord_example",
    "clientOrderId": "partner-order-1001",
    "price": 14900,
    "payments": [
      {
        "reason": "initial",
        "amount": 12000,
        "status": "paid",
        "paidAt": "2026-09-07T02:58:00.000Z",
        "receiptUrl": "https://dashboard.tosspayments.com/receipt/example-1"
      },
      {
        "reason": "reroute",
        "amount": 2900,
        "status": "paid",
        "paidAt": "2026-09-07T03:00:00.000Z",
        "receiptUrl": "https://dashboard.tosspayments.com/receipt/example-2"
      }
    ]
  }
}

수신 필드

필드명	타입	설명	포함 조건
id	string	이벤트 ID. 재시도·재전송에서도 동일	항상
event	string	이벤트 유형: order.picked_up	항상
occurredAt	string	이벤트 발생 시각(ISO 8601). 주문 조회 응답의 createdAt(주문 생성 시각)과 다른 값입니다	항상
data	object	이벤트가 발생한 주문 정보	항상
data.orderId	string	주문 조회에 사용하는 싼퀵 API 주문 ID	항상
data.clientOrderId	string \| null	고객사 내부 주문 식별자	항상
data.price	number	결제 확정 누적 금액(원). 자동 라우팅 추가 결제를 포함합니다	항상
data.payments	object[]	건별 결제·영수증. 승인 시각 오름차순	항상
data.payments[].reason	string	initial · reroute · surcharge	항상
data.payments[].amount	number	이 건의 결제 금액(원)	항상
data.payments[].status	string	paid · cancelled · partially_refunded	항상
data.payments[].refundAmount	number	환불된 금액(원)	환불이 있을 때만
data.payments[].paidAt	string	승인 시각(ISO 8601)	항상
data.payments[].receiptUrl	string	영수증 링크	발급된 경우만

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

order.completed

배송 완료

배송이 완료됐을 때 전달합니다.

JSON

{
  "id": "whd_example",
  "event": "order.completed",
  "occurredAt": "2026-09-07T03:00:00.000Z",
  "data": {
    "orderId": "ord_example",
    "clientOrderId": "partner-order-1001",
    "price": 14900,
    "payments": [
      {
        "reason": "initial",
        "amount": 12000,
        "status": "paid",
        "paidAt": "2026-09-07T02:58:00.000Z",
        "receiptUrl": "https://dashboard.tosspayments.com/receipt/example-1"
      },
      {
        "reason": "reroute",
        "amount": 2900,
        "status": "paid",
        "paidAt": "2026-09-07T03:00:00.000Z",
        "receiptUrl": "https://dashboard.tosspayments.com/receipt/example-2"
      }
    ]
  }
}

수신 필드

필드명	타입	설명	포함 조건
id	string	이벤트 ID. 재시도·재전송에서도 동일	항상
event	string	이벤트 유형: order.completed	항상
occurredAt	string	이벤트 발생 시각(ISO 8601). 주문 조회 응답의 createdAt(주문 생성 시각)과 다른 값입니다	항상
data	object	이벤트가 발생한 주문 정보	항상
data.orderId	string	주문 조회에 사용하는 싼퀵 API 주문 ID	항상
data.clientOrderId	string \| null	고객사 내부 주문 식별자	항상
data.price	number	결제 확정 누적 금액(원). 자동 라우팅 추가 결제를 포함합니다	항상
data.payments	object[]	건별 결제·영수증. 승인 시각 오름차순	항상
data.payments[].reason	string	initial · reroute · surcharge	항상
data.payments[].amount	number	이 건의 결제 금액(원)	항상
data.payments[].status	string	paid · cancelled · partially_refunded	항상
data.payments[].refundAmount	number	환불된 금액(원)	환불이 있을 때만
data.payments[].paidAt	string	승인 시각(ISO 8601)	항상
data.payments[].receiptUrl	string	영수증 링크	발급된 경우만

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

order.cancelled

주문 취소

주문 취소와 환불이 완료됐을 때 전달합니다.

JSON

{
  "id": "whd_example",
  "event": "order.cancelled",
  "occurredAt": "2026-09-07T03:01:00.000Z",
  "data": {
    "orderId": "ord_example",
    "clientOrderId": "partner-order-1001",
    "price": 12000,
    "payments": [
      {
        "reason": "initial",
        "amount": 12000,
        "status": "paid",
        "paidAt": "2026-09-07T02:58:00.000Z",
        "receiptUrl": "https://dashboard.tosspayments.com/receipt/example-1"
      },
      {
        "reason": "reroute",
        "amount": 2900,
        "status": "paid",
        "paidAt": "2026-09-07T03:00:00.000Z",
        "receiptUrl": "https://dashboard.tosspayments.com/receipt/example-2"
      }
    ],
    "cancellationFee": 0,
    "refundAmount": 12000
  }
}

수신 필드

필드명	타입	설명	포함 조건
id	string	이벤트 ID. 재시도·재전송에서도 동일	항상
event	string	이벤트 유형: order.cancelled	항상
occurredAt	string	이벤트 발생 시각(ISO 8601). 주문 조회 응답의 createdAt(주문 생성 시각)과 다른 값입니다	항상
data	object	이벤트가 발생한 주문 정보	항상
data.orderId	string	주문 조회에 사용하는 싼퀵 API 주문 ID	항상
data.clientOrderId	string \| null	고객사 내부 주문 식별자	항상
data.price	number	결제 확정 누적 금액(원). 자동 라우팅 추가 결제를 포함합니다	항상
data.payments	object[]	건별 결제·영수증. 승인 시각 오름차순	항상
data.payments[].reason	string	initial · reroute · surcharge	항상
data.payments[].amount	number	이 건의 결제 금액(원)	항상
data.payments[].status	string	paid · cancelled · partially_refunded	항상
data.payments[].refundAmount	number	환불된 금액(원)	환불이 있을 때만
data.payments[].paidAt	string	승인 시각(ISO 8601)	항상
data.payments[].receiptUrl	string	영수증 링크	발급된 경우만
data.cancellationFee	number	취소 수수료(원)	항상
data.refundAmount	number	환불액(원)	항상

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

문서 메뉴 · 개요

싼퀵 개발자센터

퀵서비스 배송 API

여러 퀵서비스 업체의 요금을 실시간으로 비교해
가장 저렴한 곳으로 배송을 요청합니다.

견적 조회·주문·취소·배송 상태 웹훅까지 REST API 하나로 연동합니다.

이런 팀을 위한 API입니다

쇼핑몰 · 커머스주문이 들어오면 퀵이 자동 접수

당일 배송 상품 주문을 그대로 퀵 주문으로 넘깁니다. 담당자가 전화나 앱으로 옮겨 적지 않습니다.

사내 시스템 · ERP반복 발송을 시스템에서 처리

서류·샘플·부품처럼 매일 나가는 발송을 사내 화면에서 바로 접수하고 상태를 자동으로 받습니다.

서비스 · 플랫폼내 앱에 퀵 배송 기능 추가

업체별 계약과 비교 로직 없이 퀵 배송을 자사 서비스 기능으로 붙입니다.

연동하면 달라지는 것

계약도 연동도 한 번

업체마다 따로 계약하고 API를 붙일 필요가 없습니다.

가격 비교를 만들지 않아도 됩니다

요청 한 번에 여러 업체 요금이 실시간으로 비교된 상태로 옵니다. 주문은 서비스 유형만 고르면 가장 저렴한 업체로 접수됩니다.

배차 실패에도 주문이 멈추지 않습니다

자동 라우팅(업체전환)을 켜두면 다음 순위 업체로 자동 전환되고, 웹훅으로 알려드립니다.

시작하기

테스트 키 발급. 대시보드 > API
연동 검증. 테스트 환경에서 견적·주문·취소와 웹훅을 검증합니다. 실제 결제·배차는 발생하지 않습니다.
운영 사용 신청. 대시보드 > API에서 신청하면 승인 후 운영 키를 발급할 수 있습니다.

연동 흐름

견적 조회 흐름

1
견적 요청
출발지·도착지 정보를 보냅니다.
2
요금 조회
서버에서 배송업체별 현재 요금을 조회합니다.
3
견적 응답
배송업체·서비스 유형별 예상 요금과 소요 시간을 반환합니다.

전체 주문 흐름

1
주문 요청
출발지·도착지와 배송 정보를 보냅니다.
2
배송업체 주문 접수
요청한 서비스 유형(이코노미, 일반, 급송)의 최저가 업체에 주문을 접수합니다. 요금은 등록된 카드로 결제됩니다.
3
기사 배정·배송
기사가 배정된 뒤 물품을 픽업하고 배송합니다.
4
배송 완료
물품이 수령인에게 전달되면 배송이 완료됩니다.

주문 취소 흐름

선택: 취소 전에 취소 수수료 조회 API로 예상 수수료와 환불액을 확인할 수 있습니다.

1
취소 요청
주문 ID와 취소 사유를 보냅니다.
2
배송업체 주문 취소
배송업체에 주문 취소를 요청하고 결과를 확인합니다.
3
환불
주문 취소가 완료되면 결제 금액에서 취소 수수료를 제외한 금액을 환불합니다.

API 살펴보기

POST/quotes견적 조회POST/orders주문 생성GET/orders/{orderId}주문 조회POST/orders/{orderId}/cancel주문 취소

테스트 환경

테스트 환경의 제약사항과 특이사항입니다.

제약사항

이메일 인증 후 승인 없이 테스트 키를 발급할 수 있습니다.
결제·기사 배정·배송·취소·환불은 시뮬레이션입니다.
실제 카드 청구·기사 접수·문자·이메일 주문 알림은 발생하지 않습니다.
웹훅은 등록한 주소로 실제 전송됩니다.
테스트 웹훅 등록 정보와 키는 운영과 별도로 관리됩니다.
테스트 주문·로그는 운영에 이관되지 않습니다.
주문과 웹훅 내역은 7일간 보관합니다.

인증

모든 API 요청은 Bearer API 키로 인증합니다.

Base URL

운영 — sk_live_ 키

https://ssanquick.com/api/v1

테스트 — sk_test_ 키

https://sandbox.ssanquick.com/api/v1

인증 헤더

HTTP

Authorization: Bearer <API 키>

API 키는 대시보드 > API에서 발급합니다.

응답 형식

성공 응답은 success: true와 data를 반환합니다.
실패 응답은 success: false와 error를 반환합니다.

오류 응답

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "유효하지 않은 API 키입니다."
  }
}

성공·실패를 가리지 않고 모든 응답에 X-Request-Id 헤더가 붙습니다.
장애 문의 시 이 값을 함께 알려주시면 해당 요청을 바로 찾을 수 있습니다.

공통 오류 보기 →

오류

HTTP 상태와 error.code로 실패 원인을 구분합니다.

오류 응답

JSON

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "요청값을 다시 확인해주세요."
  }
}

오류 응답 필드

필드명	타입	설명	포함 조건
success	boolean	항상 false	항상
error.code	string	프로그램에서 분기할 오류 코드	항상
error.message	string	오류 설명	항상
error.details	object	추가 오류 정보	제공되는 경우

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

오류 코드

HTTP	오류 코드	의미	처리 방법
400	invalid_request	JSON 본문을 읽을 수 없습니다.	JSON 형식을 확인합니다.
400	invalid_request	현재 주문 상태에서는 처리할 수 없습니다. (예: 배송이 완료되어 취소할 수 없습니다.)	주문을 조회해 현재 상태를 확인합니다. 같은 요청을 재시도해도 결과는 같습니다.
415	invalid_request	요청 본문의 형식이 올바르지 않습니다.	Content-Type을 application/json으로 보냅니다.
422	invalid_request	요청값이 올바르지 않습니다.	필수 필드와 입력값을 확인합니다.
422	invalid_request	출발지 또는 도착지 주소를 찾지 못했습니다.	기본 주소에는 도로명 주소와 건물번호까지만 보내고 층·호수·건물명은 상세 주소 필드에 넣습니다. 같은 주소로 재시도해도 결과는 같습니다.
401	invalid_api_key	API 키가 유효하지 않습니다.	환경과 API 키를 확인합니다.
402	payment_failed	등록 카드 결제가 거절됐습니다. 주문은 생성되지 않습니다.	카드 상태를 확인한 뒤 같은 clientOrderId로 다시 요청하면 재결제를 시도합니다.
404	order_not_found	주문을 찾을 수 없습니다.	orderId를 확인합니다.
409	payment_required	등록된 결제 카드가 없습니다.	대시보드에서 카드를 등록합니다.
409	order_in_progress	같은 주문 요청을 처리 중입니다.	같은 clientOrderId로 다시 요청합니다.
503	order_in_progress	배송업체의 주문 접수 결과를 확인하고 있습니다.	같은 clientOrderId로 다시 요청합니다.
429	rate_limited	요청 한도를 초과했습니다.	Retry-After 이후 다시 요청합니다.
500	internal_error	요청 처리 중 오류가 발생했습니다.	잠시 후 다시 요청합니다.
500	payment_status_unknown	결제 결과를 확인할 수 없습니다.	주문 목록을 확인하고 고객센터에 문의합니다.
503	payment_status_unknown	결제 결과 확인이 지연되고 있습니다.	주문 목록을 확인하고 고객센터에 문의합니다.
502	order_failed	주문 접수에 실패하고 결제가 취소됐습니다.	새 주문이 필요하면 다시 요청합니다.
500	refund_failed	주문 접수 실패 후 카드 환불에 실패했습니다.	주문을 조회하고 고객센터에 문의합니다.
502	refund_failed	주문 취소 후 카드 환불에 실패했습니다.	주문을 조회하고 고객센터에 문의합니다.
503	service_unavailable	배송 서비스 응답을 확인할 수 없습니다.	잠시 후 다시 요청합니다.

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

버전 관리

API의 주 버전은 URL에서 구분합니다.

현재 버전

/api/v1

주문 상태

API에서 공통으로 사용하는 주문 상태입니다.

상태 정의

필드명	타입	설명	포함 조건
accepted	string	배송업체 접수 완료, 기사 배정 전	항상
driver_assigned	string	기사 배정 완료	항상
picked_up	string	기사가 물품을 인수해 배송 중	항상
completed	string	배송 완료	항상
cancelled	string	주문 취소 완료 (배차 불가로 인한 자동 취소 포함)	항상

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

견적 조회

출발지와 도착지의 오토바이 퀵 요금을 배송업체별로 조회합니다.

POST/api/v1/quotes

요청 필드

필드명	필수	형식·제약
departureAddress	필수	출발지 기본 주소. 도로명 주소와 건물번호까지 입력
destinationAddress	필수	도착지 기본 주소. 도로명 주소와 건물번호까지 입력
vehicleType	필수	motorcycle
departureAddressDetail	선택	출발지 층·호수 등 상세 주소
destinationAddressDetail	선택	도착지 층·호수 등 상세 주소

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

요청 예시

cURL

curl -X POST https://ssanquick.com/api/v1/quotes   -H "Authorization: Bearer <API 키>"   -H "Content-Type: application/json"   -d '{
    "departureAddress": "서울 강남구 테헤란로 123",
    "departureAddressDetail": "10층",
    "destinationAddress": "서울 서초구 서초대로 456",
    "vehicleType": "motorcycle"
  }'

성공 응답

아래는 예시 응답입니다. 실제 응답에는 조회 시점에 요금을 응답한 여러 업체가 담기며, 업체 수와 순서는 조회마다 다릅니다.

JSON

{
  "success": true,
  "data": {
    "departureAddress": "서울 강남구 테헤란로 123",
    "destinationAddress": "서울 서초구 서초대로 456",
    "vehicleType": "motorcycle",
    "offers": [
      {
        "carrier": "A업체",
        "serviceType": "economy",
        "price": 8000,
        "estimatedTime": "3시간 내",
        "estimatedTimeSeconds": 10800
      },
      {
        "carrier": "B업체",
        "serviceType": "standard",
        "price": 12000,
        "estimatedTime": "2시간 내",
        "estimatedTimeSeconds": 7200
      },
      {
        "carrier": "A업체",
        "serviceType": "standard",
        "price": 12000,
        "estimatedTime": "1시간 30분 내",
        "estimatedTimeSeconds": 5400
      },
      {
        "carrier": "B업체",
        "serviceType": "express",
        "price": 16000,
        "estimatedTime": "45분 내",
        "estimatedTimeSeconds": 2700
      },
      {
        "carrier": "A업체",
        "serviceType": "express",
        "price": 16000,
        "estimatedTime": "45분 내",
        "estimatedTimeSeconds": 2700
      }
    ],
    "createdAt": "2026-09-07T03:00:00.000Z"
  }
}

응답 필드

필드명	타입	설명	포함 조건
success	boolean	요청 성공 여부	항상
data	object	견적 결과	항상
data.departureAddress	string	출발지 주소	항상
data.destinationAddress	string	도착지 주소	항상
data.vehicleType	string	motorcycle	항상
data.offers	object[]	견적 목록. 금액 오름차순	항상
data.offers[].carrier	string	응답 내 업체 구분용. 주문 선택값이 아니며, 요청 간 동일 업체를 보장하지 않습니다	항상
data.offers[].serviceType	string	economy, standard, express	항상
data.offers[].price	number	견적 금액(원)	항상
data.offers[].estimatedTime	string \| null	예상 소요 시간	항상
data.offers[].estimatedTimeSeconds	number \| null	예상 소요 시간(초)	항상
data.createdAt	string	견적 생성 시각(ISO 8601)	항상

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

주문 생성

POST/api/v1/orders

배송업체 자동 선정

주문 요청에는 업체를 지정하는 필드가 없습니다. serviceType만 지정합니다.
주문 시점에 싼퀵이 접수할 수 있는 업체 중 해당 서비스 유형(이코노미, 일반, 급송)의 최저가 업체로 접수됩니다.
결제 금액은 응답의 price로 확정되며, 견적 조회 금액과 다를 수 있습니다.

자동 라우팅(업체전환)

배차 실패·업체 취소·기사 배정 지연 시 다음 순위 업체·상품으로 자동 라우팅합니다.
대시보드 › 설정 › 주문 설정의 자동 라우팅(업체전환)이 켜져 있을 때만 동작하며, 급송 제외가 켜져 있으면 급송으로는 라우팅하지 않습니다.
새 요금이 더 높으면 차액이 등록 카드로 추가 결제됩니다. 추가 결제는 payments[]에 reason: "reroute"로 남고, 영수증도 건별로 들어 있습니다.
라우팅 후 price는 추가 결제를 포함한 누적 금액입니다. 새 기사가 배정되면 order.driver_reassigned가 전달되며, data.price로 누적 금액을 함께 보냅니다.
배차 실패·업체 취소 시 라우팅할 곳이 없으면 자동 취소·전액 환불되고 order.cancelled가 전달됩니다.

요청 필드

필드명	필수	형식·제약
departureAddress	필수	출발지 기본 주소. 도로명 주소와 건물번호까지 입력
destinationAddress	필수	도착지 기본 주소. 도로명 주소와 건물번호까지 입력
departureAddressDetail	선택	출발지 층·호수 등 상세 주소
destinationAddressDetail	선택	도착지 층·호수 등 상세 주소
vehicleType	필수	motorcycle
serviceType	필수	economy, standard, express
senderName	필수	발송인 이름
senderPhone	필수	발송인 연락처
receiverName	필수	수령인 이름
receiverPhone	필수	수령인 연락처
clientOrderId	필수	고객사 주문 식별자. 같은 값으로 다시 요청하면 기존 주문을 반환. 결제가 거절된 요청은 같은 값으로 다시 요청하면 재결제를 시도
productSize	선택	XS: 초소형, 세 변 합 70cm 이하, 2kg 이하 S: 소형, 세 변 합 100cm 이하, 5kg 이하 M: 중형, 세 변 합 140cm 이하, 20kg 이하 생략 시 M
driverNote	선택	기사 전달 사항

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

요청 예시

cURL

curl -X POST https://ssanquick.com/api/v1/orders   -H "Authorization: Bearer <API 키>"   -H "Content-Type: application/json"   -d '{
    "departureAddress": "서울 강남구 테헤란로 123",
    "departureAddressDetail": "10층",
    "destinationAddress": "서울 서초구 서초대로 456",
    "destinationAddressDetail": "3층",
    "vehicleType": "motorcycle",
    "serviceType": "standard",
    "productSize": "M",
    "senderName": "홍길동",
    "senderPhone": "01011112222",
    "receiverName": "김철수",
    "receiverPhone": "01033334444",
    "clientOrderId": "partner-order-1001",
    "driverNote": "도착 전에 연락해주세요"
  }'

성공 응답

JSON

{
  "success": true,
  "data": {
    "orderId": "ord_example",
    "clientOrderId": "partner-order-1001",
    "status": "accepted",
    "price": 12000,
    "createdAt": "2026-09-07T03:00:00.000Z"
  }
}

응답 필드

필드명	타입	설명	포함 조건
success	boolean	요청 성공 여부	항상
data	object	생성된 주문	항상
data.orderId	string	주문 조회·취소에 사용하는 싼퀵 API 주문 ID	항상
data.clientOrderId	string \| null	고객사 내부 주문 식별자	항상
data.status	string	주문 상태	항상
data.price	number	결제된 주문 금액(원)	항상
data.createdAt	string	주문 생성 시각(ISO 8601)	항상

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

주문 조회

주문 ID로 현재 주문 정보를 조회합니다.

GET/api/v1/orders/{orderId}

요청 필드

필드명	필수	형식·제약
orderId (경로)	필수	주문 생성 응답의 orderId

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

요청 예시

cURL

curl https://ssanquick.com/api/v1/orders/{orderId} \
  -H "Authorization: Bearer <API 키>"

성공 응답

JSON

{
  "success": true,
  "data": {
    "orderId": "ord_example",
    "clientOrderId": "partner-order-1001",
    "status": "driver_assigned",
    "price": 12000,
    "payments": [
      {
        "reason": "initial",
        "amount": 12000,
        "status": "paid",
        "paidAt": "2026-09-07T02:58:00.000Z",
        "receiptUrl": "https://dashboard.tosspayments.com/receipt/example-1"
      },
      {
        "reason": "reroute",
        "amount": 2900,
        "status": "paid",
        "paidAt": "2026-09-07T03:00:00.000Z",
        "receiptUrl": "https://dashboard.tosspayments.com/receipt/example-2"
      }
    ],
    "serviceType": "standard",
    "departureAddress": "서울 강남구 테헤란로 123",
    "destinationAddress": "서울 서초구 서초대로 456",
    "driverName": "김기사",
    "driverPhone": "010-1234-5678",
    "createdAt": "2026-09-07T03:00:00.000Z",
    "updatedAt": "2026-09-07T03:00:00.000Z"
  }
}

응답 필드

필드명	타입	설명	포함 조건
success	boolean	요청 성공 여부	항상
data	object	조회한 주문	항상
data.orderId	string	주문 조회·취소에 사용하는 싼퀵 API 주문 ID	항상
data.clientOrderId	string \| null	고객사 내부 주문 식별자	항상
data.status	string	주문 상태	항상
data.price	number	주문 금액(원). 자동 라우팅 시 누적 금액	항상
data.serviceType	string	배송 서비스 유형 economy: 이코노미 standard: 일반 express: 급송	항상
data.departureAddress	string	출발지 기본 주소	항상
data.destinationAddress	string	도착지 기본 주소	항상
data.createdAt	string	주문 생성 시각(ISO 8601)	항상
data.departureAddressDetail	string	출발지 상세 주소	입력한 경우
data.destinationAddressDetail	string	도착지 상세 주소	입력한 경우
data.driverName	string	배정된 기사 이름	배송업체에서 제공한 경우
data.driverPhone	string	배정된 기사 연락처	배송업체에서 제공한 경우
data.updatedAt	string	마지막 변경 시각(ISO 8601)	항상
data.payments	object[]	건별 결제·영수증. 승인 시각 오름차순	항상
data.payments[].reason	string	결제 사유. initial · reroute · surcharge	항상
data.payments[].amount	number	이 건의 결제 금액(원)	항상
data.payments[].status	string	paid · cancelled · partially_refunded	항상
data.payments[].refundAmount	number	환불된 금액(원)	환불이 있을 때만
data.payments[].paidAt	string	승인 시각(ISO 8601)	항상
data.payments[].receiptUrl	string	영수증 링크	발급된 경우만
data.cancellationFee	number	취소 수수료(원)	취소 완료 후
data.refundAmount	number	환불액(원)	취소 완료 후

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

주문 목록

고객사의 주문을 최신순으로 조회합니다.

GET/api/v1/orders

요청 필드

필드명	필수	형식·제약
page (쿼리)	선택	페이지 번호. 기본값 1
limit (쿼리)	선택	페이지당 항목 수. 기본값 20, 최대 100

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

요청 예시

cURL

curl "https://ssanquick.com/api/v1/orders?page=1&limit=20" \
  -H "Authorization: Bearer <API 키>"

성공 응답

JSON

{
  "success": true,
  "data": {
    "items": [
      {
        "orderId": "ord_example",
        "clientOrderId": "partner-order-1001",
        "status": "accepted",
        "price": 12000,
        "serviceType": "standard",
        "departureAddress": "서울 강남구 테헤란로 123",
        "destinationAddress": "서울 서초구 서초대로 456",
        "createdAt": "2026-09-07T03:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1
    }
  }
}

응답 필드

필드명	타입	설명	포함 조건
success	boolean	요청 성공 여부	항상
data.items	object[]	주문 목록	항상
data.items[].orderId	string	주문 조회·취소에 사용하는 싼퀵 API 주문 ID	항상
data.items[].clientOrderId	string \| null	고객사 내부 주문 식별자	항상
data.items[].status	string	주문 상태	항상
data.items[].price	number	주문 금액(원). 자동 라우팅 시 누적 금액	항상
data.items[].serviceType	string	배송 서비스 유형 economy: 이코노미 standard: 일반 express: 급송	항상
data.items[].departureAddress	string	출발지 기본 주소	항상
data.items[].destinationAddress	string	도착지 기본 주소	항상
data.items[].createdAt	string	주문 생성 시각(ISO 8601)	항상
data.pagination.page	number	현재 페이지	항상
data.pagination.limit	number	페이지당 항목 수	항상
data.pagination.total	number	전체 주문 수	항상

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

취소 수수료 조회

취소 가능 여부와 예상 환불액을 조회합니다.

GET/api/v1/orders/{orderId}/cancel-fee

요청 필드

필드명	필수	형식·제약
orderId (경로)	필수	주문 생성 응답의 orderId

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

요청 예시

cURL

curl https://ssanquick.com/api/v1/orders/{orderId}/cancel-fee \
  -H "Authorization: Bearer <API 키>"

성공 응답

JSON

{
  "success": true,
  "data": {
    "cancellable": true,
    "fee": 0,
    "refundAmount": 12000
  }
}

응답 필드

필드명	타입	설명	포함 조건
success	boolean	요청 성공 여부	항상
data.cancellable	boolean	취소 가능 여부	항상
data.fee	number	취소 수수료(원)	항상
data.refundAmount	number	예상 환불액(원)	항상
data.reason	string	취소할 수 없는 이유	취소 불가 시

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

주문 취소

배송을 취소하고 등록 카드 결제를 환불합니다.

POST/api/v1/orders/{orderId}/cancel

요청 필드

필드명	필수	형식·제약
orderId (경로)	필수	주문 생성 응답의 orderId
cancelReason	필수	취소 사유

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

요청 예시

cURL

curl -X POST https://ssanquick.com/api/v1/orders/{orderId}/cancel   -H "Authorization: Bearer <API 키>"   -H "Content-Type: application/json"   -d '{"cancelReason":"고객 요청"}'

성공 응답

취소된 주문을 다시 취소하면 같은 주문 상태를 반환합니다.

JSON

{
  "success": true,
  "data": {
    "orderId": "ord_example",
    "clientOrderId": "partner-order-1001",
    "status": "cancelled",
    "cancellationFee": 0,
    "refundAmount": 12000,
    "updatedAt": "2026-09-07T03:01:00.000Z"
  }
}

응답 필드

필드명	타입	설명	포함 조건
success	boolean	요청 성공 여부	항상
data	object	취소 처리 후 주문	항상
data.orderId	string	주문 조회·취소에 사용하는 싼퀵 API 주문 ID	항상
data.clientOrderId	string \| null	고객사 내부 주문 식별자	항상
data.status	string	취소 완료 상태. cancelled	항상
data.cancellationFee	number	취소 수수료(원)	항상
data.refundAmount	number	환불액(원)	항상
data.updatedAt	string	취소 처리 시각(ISO 8601)	항상

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

웹훅

주문 이벤트를 등록한 HTTPS 주소로 전달합니다.

웹훅 키

대시보드 > API에서 웹훅을 등록하면 웹훅 키를 발급합니다.
수신 요청의 X-Ssanquick-Webhook-Key 값이 발급받은 키와 일치하는지 확인합니다.

웹훅 키를 재발급하면 기존 키는 즉시 만료됩니다.
새 키를 수신 서버에 반영하세요.

이벤트별 샘플 본문은 대시보드 › API의 테스트 탭에서 전송할 수 있습니다.
운영 탭은 실제 주문 이벤트와 기존 실패 이력의 재전송만 지원합니다.

요청 헤더

X-Ssanquick-Webhook-Key: whsec_…

웹훅 재전송 흐름

1
최초 전송
이벤트 본문과 웹훅 키를 등록한 주소로 보냅니다.
2
직전 실패 후 1분
첫 번째 재시도
응답 시간 초과 또는 2xx 이외 응답이면 다시 보냅니다.
3
직전 실패 후 5분
두 번째 재시도
같은 이벤트 ID와 본문으로 다시 보냅니다.
4
직전 실패 후 30분
마지막 자동 재시도
최초 전송을 포함해 최대 4회 시도합니다.
5
실패로 종료
4회 모두 실패하면 자동 재시도를 종료합니다. 수신 서버의 키·응답 상태를 확인합니다.
6
대시보드에서 재전송
장애 해결 후 API > 웹훅 전송 내역에서 재전송합니다. 같은 이벤트 ID와 현재 웹훅 키로 전송합니다.

전달 정책

공개 인터넷에서 접근 가능한 HTTPS 443 주소만 허용합니다(내부망·예약 IP 불가). 리다이렉트는 따라가지 않습니다.
테스트 환경 수신처는 공개 IPv4 주소가 하나 이상 있어야 합니다(IPv6 전용 호스트 불가).
10초 안에 2xx 를 반환해야 성공으로 기록됩니다 — 무거운 처리는 응답 후 비동기로 하세요.
2xx 응답을 받지 못한 건은 아래 재시도 규칙에 따라 다시 보냅니다.
자동 라우팅(업체전환)으로 다시 접수되면 order.driver_reassigned가 전달됩니다.

재시도·재전송

2xx 를 받지 못하면 1분 → 5분 → 30분 간격으로 최대 4회 시도합니다.
재시도된 건은 같은 id로 다시 갑니다.
수신처가 이미 처리했더라도 2xx 를 돌려주지 못하면 다시 보내므로, id로 중복을 걸러 주세요.
이벤트 수신 순서가 바뀔 수 있습니다. 최종 상태는 주문 조회로 확인하세요.
재시도가 소진된 건은 대시보드 웹훅 전송 내역에서 다시 보낼 수 있습니다.

order.driver_assigned

기사 배정

기사 배정을 확인했을 때 전달합니다. 기사 정보는 확인된 항목만 포함합니다.

JSON

{
  "id": "whd_example",
  "event": "order.driver_assigned",
  "occurredAt": "2026-09-07T03:00:00.000Z",
  "data": {
    "orderId": "ord_example",
    "clientOrderId": "partner-order-1001",
    "price": 12000,
    "payments": [
      {
        "reason": "initial",
        "amount": 12000,
        "status": "paid",
        "paidAt": "2026-09-07T02:58:00.000Z",
        "receiptUrl": "https://dashboard.tosspayments.com/receipt/example-1"
      }
    ],
    "driverName": "김기사",
    "driverPhone": "010-1234-5678"
  }
}

수신 필드

필드명	타입	설명	포함 조건
id	string	이벤트 ID. 재시도·재전송에서도 동일	항상
event	string	이벤트 유형: order.driver_assigned	항상
occurredAt	string	이벤트 발생 시각(ISO 8601). 주문 조회 응답의 createdAt(주문 생성 시각)과 다른 값입니다	항상
data	object	이벤트가 발생한 주문 정보	항상
data.orderId	string	주문 조회에 사용하는 싼퀵 API 주문 ID	항상
data.clientOrderId	string \| null	고객사 내부 주문 식별자	항상
data.price	number	결제 확정 누적 금액(원). 자동 라우팅 추가 결제를 포함합니다	항상
data.payments	object[]	건별 결제·영수증. 승인 시각 오름차순	항상
data.payments[].reason	string	initial · reroute · surcharge	항상
data.payments[].amount	number	이 건의 결제 금액(원)	항상
data.payments[].status	string	paid · cancelled · partially_refunded	항상
data.payments[].refundAmount	number	환불된 금액(원)	환불이 있을 때만
data.payments[].paidAt	string	승인 시각(ISO 8601)	항상
data.payments[].receiptUrl	string	영수증 링크	발급된 경우만
data.driverName	string	기사 이름	확인된 경우
data.driverPhone	string	기사 전화번호	확인된 경우

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

order.driver_reassigned

기사 재배정

배정 기사가 변경됐을 때 전달합니다. 업체 자체 재배차와 자동 라우팅(업체전환)이 모두 해당합니다. 기사 정보는 확인된 항목만 포함합니다.

JSON

{
  "id": "whd_example",
  "event": "order.driver_reassigned",
  "occurredAt": "2026-09-07T03:00:00.000Z",
  "data": {
    "orderId": "ord_example",
    "clientOrderId": "partner-order-1001",
    "price": 14900,
    "payments": [
      {
        "reason": "initial",
        "amount": 12000,
        "status": "paid",
        "paidAt": "2026-09-07T02:58:00.000Z",
        "receiptUrl": "https://dashboard.tosspayments.com/receipt/example-1"
      },
      {
        "reason": "reroute",
        "amount": 2900,
        "status": "paid",
        "paidAt": "2026-09-07T03:00:00.000Z",
        "receiptUrl": "https://dashboard.tosspayments.com/receipt/example-2"
      }
    ],
    "driverName": "이기사",
    "driverPhone": "010-9876-5432"
  }
}

수신 필드

필드명	타입	설명	포함 조건
id	string	이벤트 ID. 재시도·재전송에서도 동일	항상
event	string	이벤트 유형: order.driver_reassigned	항상
occurredAt	string	이벤트 발생 시각(ISO 8601). 주문 조회 응답의 createdAt(주문 생성 시각)과 다른 값입니다	항상
data	object	이벤트가 발생한 주문 정보	항상
data.orderId	string	주문 조회에 사용하는 싼퀵 API 주문 ID	항상
data.clientOrderId	string \| null	고객사 내부 주문 식별자	항상
data.price	number	결제 확정 누적 금액(원). 자동 라우팅 추가 결제를 포함합니다	항상
data.payments	object[]	건별 결제·영수증. 승인 시각 오름차순	항상
data.payments[].reason	string	initial · reroute · surcharge	항상
data.payments[].amount	number	이 건의 결제 금액(원)	항상
data.payments[].status	string	paid · cancelled · partially_refunded	항상
data.payments[].refundAmount	number	환불된 금액(원)	환불이 있을 때만
data.payments[].paidAt	string	승인 시각(ISO 8601)	항상
data.payments[].receiptUrl	string	영수증 링크	발급된 경우만
data.driverName	string	기사 이름	확인된 경우
data.driverPhone	string	기사 전화번호	확인된 경우

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

order.picked_up

픽업 완료

기사가 물품을 인수했을 때 전달합니다.

JSON

{
  "id": "whd_example",
  "event": "order.picked_up",
  "occurredAt": "2026-09-07T03:00:00.000Z",
  "data": {
    "orderId": "ord_example",
    "clientOrderId": "partner-order-1001",
    "price": 14900,
    "payments": [
      {
        "reason": "initial",
        "amount": 12000,
        "status": "paid",
        "paidAt": "2026-09-07T02:58:00.000Z",
        "receiptUrl": "https://dashboard.tosspayments.com/receipt/example-1"
      },
      {
        "reason": "reroute",
        "amount": 2900,
        "status": "paid",
        "paidAt": "2026-09-07T03:00:00.000Z",
        "receiptUrl": "https://dashboard.tosspayments.com/receipt/example-2"
      }
    ]
  }
}

수신 필드

필드명	타입	설명	포함 조건
id	string	이벤트 ID. 재시도·재전송에서도 동일	항상
event	string	이벤트 유형: order.picked_up	항상
occurredAt	string	이벤트 발생 시각(ISO 8601). 주문 조회 응답의 createdAt(주문 생성 시각)과 다른 값입니다	항상
data	object	이벤트가 발생한 주문 정보	항상
data.orderId	string	주문 조회에 사용하는 싼퀵 API 주문 ID	항상
data.clientOrderId	string \| null	고객사 내부 주문 식별자	항상
data.price	number	결제 확정 누적 금액(원). 자동 라우팅 추가 결제를 포함합니다	항상
data.payments	object[]	건별 결제·영수증. 승인 시각 오름차순	항상
data.payments[].reason	string	initial · reroute · surcharge	항상
data.payments[].amount	number	이 건의 결제 금액(원)	항상
data.payments[].status	string	paid · cancelled · partially_refunded	항상
data.payments[].refundAmount	number	환불된 금액(원)	환불이 있을 때만
data.payments[].paidAt	string	승인 시각(ISO 8601)	항상
data.payments[].receiptUrl	string	영수증 링크	발급된 경우만

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

order.completed

배송 완료

배송이 완료됐을 때 전달합니다.

JSON

{
  "id": "whd_example",
  "event": "order.completed",
  "occurredAt": "2026-09-07T03:00:00.000Z",
  "data": {
    "orderId": "ord_example",
    "clientOrderId": "partner-order-1001",
    "price": 14900,
    "payments": [
      {
        "reason": "initial",
        "amount": 12000,
        "status": "paid",
        "paidAt": "2026-09-07T02:58:00.000Z",
        "receiptUrl": "https://dashboard.tosspayments.com/receipt/example-1"
      },
      {
        "reason": "reroute",
        "amount": 2900,
        "status": "paid",
        "paidAt": "2026-09-07T03:00:00.000Z",
        "receiptUrl": "https://dashboard.tosspayments.com/receipt/example-2"
      }
    ]
  }
}

수신 필드

필드명	타입	설명	포함 조건
id	string	이벤트 ID. 재시도·재전송에서도 동일	항상
event	string	이벤트 유형: order.completed	항상
occurredAt	string	이벤트 발생 시각(ISO 8601). 주문 조회 응답의 createdAt(주문 생성 시각)과 다른 값입니다	항상
data	object	이벤트가 발생한 주문 정보	항상
data.orderId	string	주문 조회에 사용하는 싼퀵 API 주문 ID	항상
data.clientOrderId	string \| null	고객사 내부 주문 식별자	항상
data.price	number	결제 확정 누적 금액(원). 자동 라우팅 추가 결제를 포함합니다	항상
data.payments	object[]	건별 결제·영수증. 승인 시각 오름차순	항상
data.payments[].reason	string	initial · reroute · surcharge	항상
data.payments[].amount	number	이 건의 결제 금액(원)	항상
data.payments[].status	string	paid · cancelled · partially_refunded	항상
data.payments[].refundAmount	number	환불된 금액(원)	환불이 있을 때만
data.payments[].paidAt	string	승인 시각(ISO 8601)	항상
data.payments[].receiptUrl	string	영수증 링크	발급된 경우만

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

order.cancelled

주문 취소

주문 취소와 환불이 완료됐을 때 전달합니다.

JSON

{
  "id": "whd_example",
  "event": "order.cancelled",
  "occurredAt": "2026-09-07T03:01:00.000Z",
  "data": {
    "orderId": "ord_example",
    "clientOrderId": "partner-order-1001",
    "price": 12000,
    "payments": [
      {
        "reason": "initial",
        "amount": 12000,
        "status": "paid",
        "paidAt": "2026-09-07T02:58:00.000Z",
        "receiptUrl": "https://dashboard.tosspayments.com/receipt/example-1"
      },
      {
        "reason": "reroute",
        "amount": 2900,
        "status": "paid",
        "paidAt": "2026-09-07T03:00:00.000Z",
        "receiptUrl": "https://dashboard.tosspayments.com/receipt/example-2"
      }
    ],
    "cancellationFee": 0,
    "refundAmount": 12000
  }
}

수신 필드

필드명	타입	설명	포함 조건
id	string	이벤트 ID. 재시도·재전송에서도 동일	항상
event	string	이벤트 유형: order.cancelled	항상
occurredAt	string	이벤트 발생 시각(ISO 8601). 주문 조회 응답의 createdAt(주문 생성 시각)과 다른 값입니다	항상
data	object	이벤트가 발생한 주문 정보	항상
data.orderId	string	주문 조회에 사용하는 싼퀵 API 주문 ID	항상
data.clientOrderId	string \| null	고객사 내부 주문 식별자	항상
data.price	number	결제 확정 누적 금액(원). 자동 라우팅 추가 결제를 포함합니다	항상
data.payments	object[]	건별 결제·영수증. 승인 시각 오름차순	항상
data.payments[].reason	string	initial · reroute · surcharge	항상
data.payments[].amount	number	이 건의 결제 금액(원)	항상
data.payments[].status	string	paid · cancelled · partially_refunded	항상
data.payments[].refundAmount	number	환불된 금액(원)	환불이 있을 때만
data.payments[].paidAt	string	승인 시각(ISO 8601)	항상
data.payments[].receiptUrl	string	영수증 링크	발급된 경우만
data.cancellationFee	number	취소 수수료(원)	항상
data.refundAmount	number	환불액(원)	항상

표를 좌우로 밀어 전체 내용을 확인할 수 있습니다.

퀵서비스 배송 API

이런 팀을 위한 API입니다

연동하면 달라지는 것

시작하기

연동 흐름

견적 요청

요금 조회

견적 응답

주문 요청

배송업체 주문 접수

기사 배정·배송

배송 완료

취소 요청

배송업체 주문 취소

환불

API 살펴보기

테스트 환경

제약사항

인증

Base URL

인증 헤더

응답 형식

오류

오류 응답

오류 응답 필드

오류 코드

버전 관리

현재 버전

주문 상태

상태 정의

요청 필드

요청 예시

성공 응답

응답 필드

배송업체 자동 선정

자동 라우팅(업체전환)

요청 필드

요청 예시

성공 응답

응답 필드

요청 필드

요청 예시

성공 응답

응답 필드

요청 필드

요청 예시

성공 응답

응답 필드

요청 필드

요청 예시

성공 응답

응답 필드

요청 필드

요청 예시

성공 응답

응답 필드

웹훅

웹훅 키

최초 전송

첫 번째 재시도

두 번째 재시도

마지막 자동 재시도

실패로 종료

대시보드에서 재전송

전달 정책

재시도·재전송

기사 배정

수신 필드

기사 재배정

수신 필드

픽업 완료

수신 필드

배송 완료

수신 필드

주문 취소

수신 필드

퀵서비스 배송 API

이런 팀을 위한 API입니다

연동하면 달라지는 것

시작하기