kakaoT 퀵 • 도보 배송 API Sandbox

시작하기

이 문서는 REST API인 카카오 T 퀵∙도보 배송 API(이하 퀵∙도보 배송 API)를 사용하여 카카오모빌리티가 제공하는 퀵 배송, 도보 배송 등의 서비스를 이용하는 방법을 안내합니다.

퀵∙도보 배송 API는 각 서비스마다 제공하던 여러 개의 API를 하나로 통합하여 제공하므로, 한 번의 연동으로 빠르고 간편하게 카카오모빌리티의 서비스를 사용할 수 있습니다. 퀵∙도보 배송 API를 통해 출발지와 목적지의 위치, 주문 유형 등과 같은 상세 정보를 확인하고 주문을 취소할 수 있습니다. 또한, 주문 상태 및 배송원의 현재 위치를 조회할 수 있습니다.

시작하기 전에복사하기

Vendor ID 및 API 키 발급받기

퀵∙도보 배송 API를 사용하려면 먼저 Vendor ID와 API 키를 발급받아야 합니다. 아래의 절차를 따라 Vendor ID와 API 키를 확인하세요.

1. 🔗kakaoT 퀵∙도보 배송 API Sandbox에 로그인하세요. 계정이 없을 경우, 회원 가입을 한 후 다음 단계를 진행하세요.
2. 로그인 후, 화면 왼쪽 상단에서API → API 키 발급 및 관리를 클릭합니다.
3. API 키 발급하기를 클릭합니다.

   • Vendor ID와 API 키를 발급받기 위해서는 반드시 이메일을 인증해야 합니다.
   • API 키는 그룹 계정별 최대 5개까지 발급됩니다.

   
4. 사용할 API를 선택한 후, 다음을 클릭합니다.
5. 콜백을 보낼 URL 주소와 프록시(proxy)에 등록할 목적지 IP 주소를 입력한 다음 확인을 클릭합니다.
6. 아래와 같이 발급된 키값을 복사하여 사용합니다.

Signkey 값 및 Authorization 파라미터 값 생성하기

REST API를 호출하려면 요청 헤더의 Authorization 파라미터 값이 필요합니다. 이를 생성하려면 먼저 Signkey 값을 생성해야 합니다.

1. 1. Signkey 값 생성하기

   아래 단계를 따라 Signkey 값을 만들 수 있습니다.

   1. 타임스탬프(timestamp), 논스 값(nonce), kakaoT 퀵∙도보 배송 API Sandbox에서 발급받은 API 키값을 차례대로 붙인 문자열을 만듭니다.
   2. 위의 단계에서 조합한 문자열을 HMAC-SHA512로 서명하여 Signkey 값을 생성합니다.

      표 1 | Signkey 생성 정보

      Value	Type	Description
      timestamp	Long	요청이 생성된 시각으로 밀리 초 단위로 시간을 표기
      nonce	Integer	사용자가 임의로 지정한 숫자
      apiKey	String	kakaoT 퀵∙도보 배송 API Sandbox에서 발급받은 API 키

      라이트 모드복사하기

        final String timestamp =
      String.valueOf(System.currentTimeMillis());
        final String nonce = "121212";
        final String apiKey = "${API_KEY}"; //kakaoT ∙ API Sandbox API  
        final String sign = signature(timestamp, nonce, apiKey);
      
        static String signature(final String timestamp, final String
      nonce, final String apiKey)
            throws InvalidKeyException, NoSuchAlgorithmException {
          final String plainText = timestamp + nonce + apiKey;
          return HmacSignature.signatureSHA512(plainText);
        }
      
        static String signatureSHA512(final String plainText)
            throws NoSuchAlgorithmException, InvalidKeyException {
      
          final MessageDigest md =
      MessageDigest.getInstance("SHA-512");
          md.update(plainText.getBytes());
          return String.format("%0128x", new BigInteger(1,
      md.digest()));
        }
      

2. 2. Authorization 파라미터 값 생성하기

   Authorization 파라미터 값은 위에서 생성된 Signkey 값, 타임스탬프(timestamp), 논스 값(nonce)의 조합을 Base64로 인코딩하여 생성합니다. 조합 시 구분자는 $$를 사용합니다.

   표 2 | Authorization 파라미터 값 생성 정보

   Value	Type	Description
   timestamp	Long	요청이 생성된 시각으로 밀리 초 단위로 시간을 표기
   nonce	Integer	사용자가 임의로 지정한 숫자
   sign	String	Signkey 값

   라이트 모드복사하기

   final String authorization = Base64.getEncoder()
           .encodeToString(String.valueOf(timestamp + "$$" +
   nonce + "$$" + sign).getBytes());

3. 3. Authorization 파라미터 값 인증하기

   발급받은 Authorization 파라미터 값의 유효성을 확인하려면 인증 API를 활용할 수 있습니다. 해당 API를 사용하여 Authorization 파라미터 값이 올바른지 확인해 보세요.

   Request

   요청 호출 방식과 각 요청 헤더에 포함될 내용에 안내합니다. 요청이 실패할 경우 🔗문제 해결하기에서 에러에 대한 상세 내용을 확인하세요.

   호출 방식

   표 3 | 호출 방식

   Method	URL
   GET	https://open-api-logistics.kakaomobility .com/v1/auth/check

   요청 헤더

   표 4 | 요청 헤더

   Parameter	Description
   Authorization	시작하기에서 생성한 Authorization 파라미터 값
   vendor	kakaoT 퀵∙도보 배송 API Sandbox에서 발급받은 Vendor 아이디
   Content-Type	application/json

   요청 코드 예제

   라이트 모드복사하기

   curl -X 'GET' \
     'https://open-api-logistics.kakaomobility.com/v1/auth/check'
     -H 'accept: application/json' \
     -H 'Authorization: XXX' \
     -H 'Content-Type: application/json' \
     -H 'vendor: ${vendor_id}' \ 
     

퀵∙도보 배송 API 목록복사하기

퀵∙도보 배송 API에서 제공하는 기능과 기본적인 요청 규격 정보는 다음과 같습니다.