페이지 이동경로
  • 문서>
  • 카카오싱크>
  • 배송지 조회하기

카카오싱크

배송지 조회하기

이 문서는 배송지 조회하기 API 사용 방법을 안내합니다.

카카오싱크를 적용한 서비스는 필요에 따라 사용자의 배송지 정보를 제공받을 수 있습니다. 배송지 정보는 사용자 정보 요청과 마찬가지로 사용자의 정보 제공 동의가 있어야 제공됩니다. [내 애플리케이션] > [카카오 로그인] > [동의 항목]에서 '배송지 정보(shipping_address)'를 필수 또는 선택 항목으로 설정하고, 배송지 조회하기 API를 호출해 사용자의 배송지 정보를 제공받을 수 있습니다.

카카오싱크 이용 시 기본적으로 '배송지 정보' 동의 항목을 선택 동의 항목으로 설정할 수 있으며, 배송지 정보가 반드시 필요한 경우에는 신청하기를 참고해 카카오싱크 검수를 통해 필수 동의 항목 설정 권한을 받을 수 있습니다.

카카오가 해당 사용자로부터 배송지 정보 제공에 동의받아 저장하고 있지 않다면 연결된 서비스에도 제공할 수 없습니다. 배송지 정보가 꼭 필요한 서비스라면 사용자 관리에서 배송지 정보를 필수 항목으로 설정하고 '수집 후 제공' 옵션을 설정해야 합니다.

이 기능은 [도구] > [REST API 테스트]를 통해 사용해 볼 수 있습니다.

동의 항목 설정 필요

이 API를 사용하려면 동의 항목 설정을 참고하여 '배송지 정보' 동의 항목을 설정해야 합니다. 동의 항목이 설정되어 있더라도 사용자가 동의하지 않으면 '배송지 정보'를 받을 수 없습니다. 동의 내역 확인하기 API를 통해 사용자가 동의한 동의 항목을 먼저 확인할 수 있습니다.

이 문서에 사용된 태그

Tag Description
로그인 필수 카카오 로그인이 필요한 API를 의미합니다. 카카오 로그인을 먼저 구현하고, 카카오 로그인을 통해 발급 받은 액세스 토큰(Access Token)을 이용하여 해당 API를 호출해야 합니다.

Web 로그인 필수

이 API는 액세스 토큰으로 요청하는 방식, 서비스 관리자가 애플리케이션(이하 앱)의 어드민 키와 회원번호로 요청하는 방식 두 가지로 제공됩니다. 서버에서 배송지를 요청할 때는 요청 헤더(Header)에 사용자 토큰 대신 어드민 키를 사용하고, 배송지를 조회할 사용자를 지정해야 합니다.

응답에 shipping_addresses 값이 없다면 shipping_addresses_needs_agreement 값을 참고해 사용자로부터 동의받아야 하는지 판단합니다. 해당 값이 true라면 사용자의 동의를 거쳐 배송지 정보를 받을 수 있으므로, 추가 항목 동의 받기 기능을 사용해 동의 및 배송지 정보를 받습니다. false라면 사용자의 동의 여부와 관계없이 배송지 정보를 받을 수 없는 상태이므로, 자체적으로 사용자로부터 배송지 정보를 수집하셔야 합니다.

Request

Access Token 사용

URL
GET v1/user/shipping_address HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {ACCESS_TOKEN}
Parameter
Name Type Description Required
address_id Long 배송지 정보가 많은 경우, 특정 배송지 정보만 얻고 싶을 때 배송지 ID 지정 X
from_updated_at Integer 배송지 정보가 많아 여러 페이지에 걸쳐 응답이 제공될 때, 기준이 되는 배송지 updated_at 시각
해당 시각(미포함) 이전에 수정된 배송지부터 조회
이전 페이지의 마지막 배송지의 updated_at을 다음 페이지 input으로 사용
값을 0으로 전달하면 처음부터 조회
X
page_size Integer 2 이상, 한 페이지에 포함할 배송지 개수
기본 값 10
X

어드민 키 사용

URL
GET v1/user/shipping_address HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {APP_ADMIN_KEY}
Parameter
Name Type Description Required
target_id_type String 사용자 ID 타입, user_id로 고정 O
target_id Long 회원번호 O
address_id Long 배송지 정보가 많은 경우, 특정 배송지 정보만 얻고 싶을 때 배송지 ID 지정 X
from_updated_at Integer 배송지 정보가 많아 여러 페이지에 걸쳐 응답이 제공될 때, 기준이 되는 배송지 updated_at 시각
해당 시각(미포함) 이전에 수정된 배송지부터 조회
이전 페이지의 마지막 배송지의 updated_at을 다음 페이지 input으로 사용
값을 0으로 전달하면 처음부터 조회
X
page_size Integer 2 이상, 한 페이지에 포함할 배송지 개수
기본 값 10
X
Response
Name Type Description Required
user_id Long 회원번호 O
shipping_addresses ShippingAddress[] 배송지 정보 리스트 X
shipping_addresses_needs_agreement Boolean 배송지를 얻기 위한 추가 동의 필요 여부 X
shipping_addresses
Name Type Description Required
id Long 배송지 ID O
name String 배송지명 X
is_default Boolean 기본 배송지 여부 O
updated_at Integer 수정시각 X
type String 배송지 타입
구주소 또는 신주소(도로명주소)
X
base_address String 우편번호 검색시 채워지는 기본 주소 X
detail_address String 기본 주소에 추가하는 상세 주소 X
receiver_name String 수령인 이름 X
receiver_phone_number1 String 수령인 연락처 X
receiver_phone_number2 String 수령인 추가 연락처 X
zone_number String 신주소 우편번호, 신주소인 경우에 반드시 존재함 X
zip_code String 구주소 우편번호, 우편번호를 소유하지 않는 구주소도 존재하여 구주소인 경우도 해당값이 없을 수 있음 X
Sample
Request: 액세스 토큰 사용
curl -v -X GET "https://kapi.kakao.com/v1/user/shipping_address" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"
Request: 어드민 키 사용
curl -v -G GET "https://kapi.kakao.com/v1/user/shipping_address" \
  -H "Authorization: KakaoAK {APP_ADMIN_KEY}" \
  -d "target_id_type=user_id" \
  -d "target_id={USER_ID}"
Response
{
  "user_id": 9876543211234,
  "shipping_addresses": [
    {
      "id": 319,
      "name": "회사",
      "is_default": true,
      "updated_at": 1538448856,
      "type": "NEW",
      "base_address": "경기 성남시 분당구 판교역로 231 (삼평동, 에이치스퀘어 에스동)",
      "detail_address": "6층",
      "receiver_name": "판교",
      "receiver_phone_number1": "031-123-2345",
      "receiver_phone_number2": "",
      "zone_number": "13494",
      "zip_code": "463-400"
    },
    {
      "id": 320,
      "name": "회사",
      "is_default": false,
      "updated_at": 1538450389,
      "type": "OLD",
      "base_address": "경기 성남시 분당구 삼평동 680 (삼평동, 에이치스퀘어 에스동)",
      "detail_address": "6층",
      "receiver_name": "판교2",
      "receiver_phone_number1": "010-0056-1234",
      "receiver_phone_number2": "",
      "zone_number": "13494",
      "zip_code": "463-400"
    }
  ],
  "shipping_addresses_needs_agreement": false
}

Android 로그인 필수

필요한 모듈 설정하기

배송지 조회 API는 카카오 로그인 모듈의 UserApiClient가 제공합니다. 필요한 모듈 설정하기를 참고하여 build.gradle(Module) 파일에 카카오 로그인 모듈인 v2-user을 추가합니다.

구현하기

UserApiClientshippingAddresses() API를 호출합니다. 다음 파라미터를 선택적으로 사용할 수 있습니다.

Parameter
Name Type Description Required
fromUpdatedAt Date 배송지 정보가 많아 여러 페이지에 걸쳐 응답이 제공될 때, 기준이 되는 배송지 updated_at 시각
해당 시각(미포함) 이전에 수정된 배송지부터 조회
이전 페이지의 마지막 배송지의 updated_at을 다음 페이지 input으로 사용
값을 0으로 전달하면 처음부터 조회
X
pageSize Int 2 이상, 한 페이지에 포함할 배송지 개수
기본 값 10
X

다음은 사용자가 배송지 정보 제공에 동의했는지 확인한 후, 사용자가 동의한 경우 배송지 정보를 요청하는 예제입니다.

Kotlin
RxKotlin
// 배송지 조회 (추가 동의)
UserApiClient.instance.shippingAddresses { userShippingAddresses, error ->
    if (error != null) {
        Log.e(TAG, "배송지 조회 실패", error)
    }
    else if (userShippingAddresses != null) {
        if (userShippingAddresses.shippingAddresses != null) {
            Log.i(TAG, "배송지 조회 성공" +
                    "\n회원번호: ${userShippingAddresses.userId}" +
                    "\n배송지: \n${userShippingAddresses.shippingAddresses?.joinToString("\n")}")
        }
        else if (userShippingAddresses.needsAgreement == false) {
            Log.e(TAG, "사용자 계정에 배송지 없음. 꼭 필요하다면 동의항목 설정에서 수집 기능을 활성화 해보세요.")
        }
        else if (userShippingAddresses.needsAgreement == true) {
            Log.d(TAG, "사용자에게 배송지 제공 동의를 받아야 합니다.")

            val scopes = listOf("shipping_address")

            // 사용자에게 배송지 제공 동의 요청
            UserApiClient.instance.loginWithNewScopes(context, scopes) { token, error ->
                if (error != null) {
                    Log.e(TAG, "배송지 제공 동의 실패", error)
                }
                else if (token != null) {
                    Log.d(TAG, "allowed scopes: ${token.scopes}")

                    // 배송지 조회 재요청
                    UserApiClient.instance.shippingAddresses { userShippingAddresses, error ->
                        if (error != null) {
                            Log.e(TAG, "배송지 조회 실패", error)
                        }
                        else if (userShippingAddresses != null) {
                            Log.i(TAG, "배송지 조회 성공" +
                                    "\n회원번호: ${userShippingAddresses.userId}" +
                                    "\n배송지: \n${userShippingAddresses.shippingAddresses?.joinToString("\n")}")
                        }
                    }
                }
            }
        }
    }
}
var disposables = CompositeDisposable()

// 배송지 조회 (추가 동의)
UserApiClient.rx.shippingAddresses()
    .flatMap { userShippingAddresses ->
        if (userShippingAddresses.needsAgreement == true) {
            Log.d(TAG, "사용자에게 배송지 제공 동의를 받아야 합니다.")

            // InsufficientScope 에러 생성
            Single.error(ApiError.fromScopes(listOf("shipping_address")))
        }
        else {
            Single.just(userShippingAddresses)
        }
    }
    .retryWhen(
        // InsufficientScope 에러에 대해 추가 동의 후 재요청
        RxAuthOperations.instance.incrementalAuthorizationRequired(context)
    )
    .subscribeOn(Schedulers.io())
    .observeOn(AndroidSchedulers.mainThread())
    .subscribe({ userShippingAddresses ->
        if (userShippingAddresses.shippingAddresses != null) {
            Log.i(TAG, "배송지 조회 성공" +
                    "\n회원번호: ${userShippingAddresses.userId}" +
                    "\n배송지: \n${userShippingAddresses.shippingAddresses?.joinToString("\n")}")
        } else {
            Log.e(TAG, "사용자 계정에 배송지 없음. 꼭 필요하다면 동의항목 설정에서 수집 기능을 활성화 해보세요.")
        }
    }, { error ->
        Log.e(TAG, "배송지 조회 실패", error)
    })
    .addTo(disposables)

요청 성공 시 응답은 UserShippingAddresses 객체로 받습니다. UserShippingAddresses는 각각의 배송지 정보를 담은 ShippingAddress 객체의 리스트(List)를 포함합니다. ShippingAddress의 구성 요소 및 자료형은 Web의 응답 및 레퍼런스를 참고합니다.

Legacy Android 로그인 필수

com.kakao.usermgmt 패키지의 UserManagement 클래스를 사용해 API를 호출합니다. 아래 예제 코드를 통해 요청 전 확인해야 할 서비스 가입(앱 연결) 상태 확인이나 에러, 추가 동의가 필요할 경우 등의 처리를 어떤 식으로 구현하는지 참고할 수 있습니다. 응답은 Web과 동일합니다.

UserManagement.getInstance().shippingAddresses(new
ApiResponseCallback<ShippingAddressResponse>() {
  @Override
  public void onSessionClosed(ErrorResult errorResult) {
    // 로그인이 필요함
  }


  @Override
  public void onFailure(ErrorResult errorResult) {
  }

  @Override
  public void onSuccess(ShippingAddressResponse result) {
    if (result.shippingAddresses != null) {
      // 배송지 정보 조회 성공
    } else if (result.shippingAddressNeedsAgreement()) {
      // 동적 동의 요청
    } else {
      // 배송지 조회 불가
    }
  }
});

iOS 로그인 필수

필요한 모듈 설정하기

배송지 조회 API는 모듈인 KakaoSDKUserRxKakaoSDKUser가 제공합니다. 배송지 조회 API를 사용하려면 카카오 로그인, 사용자 관리 모듈을 모두 설치해야 합니다. 모듈 설치 방법은 설치하기를 참고합니다.

모듈 설치 후 카카오 로그인과 배송지 조회 API를 사용하려면 다음과 같이 import합니다.

Swift
RxSwift
import KakaoSDKAuth
import KakaoSDKUser
import KakaoSDKAuth
import RxKakaoSDKAuth

import KakaoSDKUser
import RxKakaoSDKUser

구현하기

배송지 조회 API는 카카오 로그인 후 발급되는 사용자 토큰이 필요한 API이므로 카카오 로그인이 완료된 후 호출해야 합니다. UserApishippingAddresses() API를 호출합니다. 다음 파라미터를 선택적으로 사용할 수 있습니다.

Parameter
Name Type Description Required
fromUpdatedAt Int 배송지 정보가 많아 여러 페이지에 걸쳐 응답이 제공될 때, 기준이 되는 배송지 updated_at 시각
해당 시각(미포함) 이전에 수정된 배송지부터 조회
이전 페이지의 마지막 배송지의 updated_at을 다음 페이지 input으로 사용
값을 0으로 전달하면 처음부터 조회
X
pageSize Int 2 이상, 한 페이지에 포함할 배송지 개수
기본 값 10
X
Swift
RxSwift
UserApi.shared.shippingAddresses {(shippingAddress, error) in
    if let error = error {
        print(error)
    }
    else {
        print("shippingAddresses() success.")
        //do something
        _ = shippingAddress
    }
}
// Class member property
let disposeBag = DisposeBag()

UserApi.shared.rx.shippingAddresses()
    .subscribe(onSuccess:{ (shippingAddress) in
        print("shippingAddresses() success.")

        //do something
        _ = shippingAddress

    }, onFailure: {error in
        print(error)
    })
    .disposed(by: disposeBag)

요청 성공 시 응답은 UserShippingAddresses 객체로 받습니다. UserShippingAddresses는 각각의 배송지 정보를 담은 ShippingAddress 객체의 배열(Array)을 포함합니다. ShippingAddress의 구성 요소 및 자료형은 Web의 응답 및 레퍼런스를 참고합니다.

Legacy iOS 로그인 필수

배송지 조회 기능은 사용자 로그인 후 사용 가능합니다. 아래 예제 코드에서 배송지 조회 요청 시 발생하는 에러나 예외 처리 방법을 참고합니다. 응답은 Web과 동일합니다.

KOSessionTask.shippingAddressTask(completionHandler: { (userShippingAddress, error) in
  if let userShippingAddress = userShippingAddress {
    if let shippingAddresses = userShippingAddress.shippingAddresses {
      // 배송지 조회 성공
    } else if userShippingAddress.shippingAddressNeedsAgreement {
      // 배송지 정보를 얻기 위해 사용자에게 동의를 요청해야 함
      KOSession.shared()?.updateScopes(["shipping_address"], completionHandler: { (error) in
        if let error = error as NSError? {
          if error.code == KOErrorCancelled.rawValue {
            // 배송지 정보 동의 취소
          } else {
            // 그 외 에러
          }
        } else {
          // 사용자가 배송지 정보 제공에 동의함
          // 배송지 정보를 다시 요청하면 배송지 획득 가능
        }
      })
    } else {
      // 배송지 조회 가능한 사용자가 아님
    }
  }
})

더보기

Web

Android

iOS