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

카카오싱크

배송지 조회하기

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

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

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

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

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

Web

기본 정보
사전 설정 카카오 로그인 사용자 동의
플랫폼 등록
카카오 로그인 활성화
동의 항목
필요 필요:
배송지 정보(shipping_address)

이 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

Request: 어드민 키 사용

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

* has_shipping_addresse: Deprecated, 배송지 정보 값 소유 여부(Boolean), API를 통한 해당 사용자 정보의 제공 가능 여부를 확인하는 용도로 사용할 수 없음, needs_agreement 참고

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을 추가합니다.

구현하기

기본 정보
사전 설정 카카오 로그인 사용자 동의 레퍼런스
플랫폼 등록
카카오 로그인 활성화
동의 항목
필요 필요:
배송지 정보(shipping_address)
공통
UserShippingAddresses
Android SDK
shippingAddresses()
ReactiveX Android SDK
shippingAddresses()

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

구현하기

기본 정보
사전 설정 카카오 로그인 사용자 동의 레퍼런스
플랫폼 등록
카카오 로그인 활성화
동의 항목
필요 필요:
배송지 정보(shipping_address)
공통
ShippingAddress
iOS SDK
shippingAddresses()
ReactiveX iOS SDK
shippingAddresses()

배송지 조회 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 {
      // 배송지 조회 가능한 사용자가 아님
    }
  }
})

Flutter

시작하기 전에

필요한 패키지 설정하기

배송지 기능을 사용하려면 설치하기를 참고하여 pubspec.yaml 파일에 Flutter SDK 전체 또는 카카오 로그인 패키지에 대한 의존성을 추가해야 합니다.

구현하기

기본 정보
사전 설정 카카오 로그인 사용자 동의 레퍼런스
플랫폼 등록
카카오 로그인 활성화
동의 항목
필요 필요:
배송지 정보(shipping_address)
shippingAddresses()
UserShippingAddresses

현재 로그인한 사용자의 배송지 정보를 가져옵니다. UserApishippingAddresses()를 호출합니다. 요청 시 다음 파라미터를 선택적으로 사용할 수 있습니다.

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

요청 성공 시 사용자 회원번호와 배송지 정보를 담은 UserShippingAddresses 객체를 받습니다. ShippingAddress의 상세 정보는 Web 응답 또는 레퍼런스를 참고합니다.

아래는 배송지 가져오기 예제로, 사용자가 [배송지 정보] 동의 항목에 동의하지 않았다면 동의 요청 후 다시 배송지 정보를 가져오는 과정을 포함합니다.

// 배송지 가져오기
UserShippingAddresses userShippingAddress;
try {
  userShippingAddress = await UserApi.instance.shippingAddresses();
} catch (error) {
  print('배송지 조회 실패 $error');
  return;
}

// 사용자의 배송지 정보 동의 항목 동의 여부에 따라 응답 처리
if (userShippingAddress.shippingAddresses != null) {
  print('배송지 조회 성공'
        '\n회원번호: ${userShippingAddress.userId}'
        '\n배송지: \n${userShippingAddress.shippingAddresses?.join('\n')}');
} else if (!userShippingAddress.needsAgreement) {
  print('사용자 카카오계정에 배송지 정보 없음'
        '배송지 정보가 꼭 필요하다면 동의 항목 설정에서 수집 후 제공 기능을 활성화 해 보세요.');
} else if (userShippingAddress.needsAgreement) {
  print('사용자에게 배송지 제공 동의를 받아야 합니다');

  // 배송지 동의 항목의 ID
  List<String> scopes = ['shipping_address'];

  // 사용자에게 배송지 정보 제공을 위한 동의 요청
  OAuthToken token;
  try {
    token = await UserApi.instance.loginWithNewScopes(scopes);
    print('사용자가 동의한 동의 항목: ${token.scopes}');
  } catch (error) {
    print('배송지 정보 동의 요청 실패 $error');
  }

  // 사용자 동의 후 다시 배송지 정보 가져오기
  try {
    UserShippingAddresses userShippingAddresses =
        await UserApi.instance.shippingAddresses();
    print('배송지 조회 성공'
          '\n회원번호: ${userShippingAddresses.userId}'
          '\n${userShippingAddresses.shippingAddresses?.join('\n')}');
  } catch (error) {
    print('배송지 조회 실패 $error');
  }
}

더보기

Web

Android

iOS

Flutter