간편연결

이 문서는 카카오비즈니스 간편연결 기능을 소개하고 구현 방법을 안내합니다.

기능 소개

카카오비즈니스 간편연결은 가맹점이 제휴사 플랫폼(웹, 앱, 모바일 등) 화면에서 간편하게 비즈니스 채널을 만들고 관리할 수 있도록 카카오가 제공하는 플러그인 형태의 도구입니다.

가맹점은 제휴사 플랫폼에서 카카오비즈니스 간편연결 팝업창으로 카카오톡 채널을 생성하고, 제휴사의 매장과 연결할 수 있습니다. 또한, 제휴사와 카카오간 채널 비즈니스 심사 대행 부속계약 체결시 생성한 채널을 비즈니스 채널로 자동 전환할 수 있습니다.

주요 기능과 제공 조건

카카오비즈니스 간편연결은 팝업창으로 아래 기능을 제공합니다. 일부 기능은 제휴사에 따라 제공하지 않을 수 있습니다.

사용 방법

카카오비즈니스 간편연결은 사용 권한이 있는 앱에서만 사용할 수 있으며, 카카오와 제휴 계약을 체결한 제휴사에 한해 부여됩니다. 아래 사용 권한 신청 방법을 참고합니다.

1. 제휴사 앱 생성, 아래 조건 모두 만족 필요(신규 앱 생성 권장)
   • 쉬운 메시지광고와 동일한 제휴사 앱 사용
   • 앱 이름에 회사명(상호, 법인 또는 단체명) 포함
   • 비즈 앱 설정
2. 제휴 신청 시 카카오 담당자에게 아래 내용을 전달해야 합니다.
   • 앱 ID: 앱 관리 페이지에서 확인 가능

이용 정책

매장 고유 코드 관리

제휴사에서 부여한 store_key(매장 고유 코드)는 아래 조건을 만족하도록 관리해야 합니다.

• 해당 매장의 연결 및 연결 해제 상태 관리
• 통신 시 암호화 필수, 암호화 값에서 URL 예약 문자(+, /, =) 제외 필요
  • 암호화 후 Base64 URL 방식으로 인코딩(Encoding) 및 복호화 전 디코딩(Decoding) 권장

허용 IP 주소

카카오비즈니스 간편연결을 사용하려면, 허용 IP 주소를 참고해 앱 관리 페이지의 [앱] > [고급] > [허용 IP 주소]에서 접근 허용이 필요한 제휴사 서버의 IP를 등록해야 합니다.

간편연결 과정

아래는 카카오비즈니스 간편연결 과정을 표현한 시퀀스 다이어그램(Sequence Diagram)입니다.

1. 가맹점이 제휴사 플랫폼에서 간편연결을 요청합니다.
2. 간편연결 팝업창 호출을 요청하면, 카카오는 제휴사로 매장 조회를 호출해 가맹점 정보를 전달받습니다.
3. 카카오는 전달받은 가맹점 정보로 가맹점에 팝업창을 출력해 간편연결을 요청합니다.
4. 가맹점이 팝업창의 간편연결 상세 내용에 동의하면, 카카오비즈니스 회원가입과 카카오톡 채널 생성 및 연결 절차 수행 후 간편연결 완료 화면을 출력합니다.
5. 간편 연결 완료 후 제휴사는 가맹점의 카카오톡 채널 프로필 ID를 응답받습니다.

개발 가이드

테스트 환경 안내

카카오비즈니스 간편연결은 실제 서비스 적용 전 동작 확인을 위한 샌드박스(Sandbox) 페이즈(Phase)를 지원합니다.

카카오디벨로퍼스 앱은 개발 환경의 페이즈별로 구분되므로, 페이즈마다 테스트를 위한 앱을 등록해야 합니다. 샌드박스 앱은 카카오와 제휴 계약을 체결한 제휴사에 한해 별도 제공합니다. 아래 페이즈별 도메인 정보를 참고합니다.

간편연결 팝업창 호출

기본 정보

제휴사의 앱 또는 웹페이지에서 간편연결 팝업을 호출합니다.

가맹점이 간편연결을 시도(예: 버튼 선택) 시 제휴사 앱 JavaScript 키와 매장 고유 코드를 쿼리 파라미터로 URL에 포함해 간편연결 팝업을 호출합니다. (참고: 매장 고유 코드 관리)

간편연결 팝업은 opener에 window.opener.postMessage({data}, targetOrigin)로 현재 상태 또는 결과를 전달합니다. window.opener가 undefined이거나 null인 경우, WKScriptMessageHandler 프로토콜을 이용해 postMessage 발송을 시도합니다.

postMessage가 전달되는 이벤트 목록은 아래와 같습니다.

1. 카카오톡 채널에 대한 연동 요청 성공
   • 신규 카카오톡 채널 개설
   • 기존 카카오톡 채널 연결
   • 카카오톡 채널 권한 이관
2. 가맹점 광고계정 생성 요청 성공
3. 톡체크아웃 판매점 생성 요청 성공
4. 간편연결 팝업 닫기 요청
   • close_reason에 이유 전달

제휴사는 postMessage에서 간편연결 결과 또는 간편연결 팝업 닫기 요청을 확인하고 처리해야 합니다. 현재 상태는 이벤트 수신 처리의 postMessage를 확인합니다.

간편연결 팝업창에서 에러 발생 시 팝업창 내 에러에서 원인을 확인합니다.

요청

쿼리 파라미터

응답

본문

Channel

Ad

예제

요청

<button onclick="window.open('https://biz-extension.kakao.com?app_key=${PARTNER_APP_JAVASCRIPT_KEY}&store_key=${STORE_KEY}', '_blank')">시작하기</button>

응답: 성공

// 신규 카카오톡 채널 개설 완료, 카카오톡 채널 권한 이관 완료, 제휴사 돌아가기 시 결과
{
    "service_type": "BIZ_EXTENSION",
    "channel": {
        "channel_public_id": "_Xyz",
        "channel_uuid": "@검색아이디",
        "channel_profile_name": "프로필명",
        "action_type": "CREATE"
    },
    "ad": {
        "action_type": "CREATE"
    },
    "close_reason": "RETURN_BUTTON"
}

// 신규 카카오톡 채널 개설 완료
{
    "service_type": "BIZ_EXTENSION",
    "channel": {
        "channel_public_id": "_Xyz",
        "channel_uuid": "@검색아이디",
        "channel_profile_name": "프로필명",
        "action_type": "CREATE"
    }
}

// 기존 카카오톡 채널 연결 완료
{
    "service_type": "BIZ_EXTENSION",
    "channel": {
        "channel_public_id": "_Xyz",
        "channel_uuid": "@검색아이디",
        "channel_profile_name": "프로필명",
        "action_type": "CONNECT"
    }
}

// 카카오톡 채널 생성 후 권한 이관 완료
{
    "service_type": "BIZ_EXTENSION",
    "channel": {
        "channel_public_id": "_Xyz",
        "channel_uuid": "@검색아이디",
        "channel_profile_name": "프로필명",
        "action_type": "TRANSFER"
    }
}

// 카카오톡 채널 생성 후 권한 이관 완료, 가맹점 광고계정 생성 완료
{
    "service_type": "BIZ_EXTENSION",
    "channel": {
        "channel_public_id": "_Xyz",
        "channel_uuid": "@검색아이디",
        "channel_profile_name": "프로필명",
        "action_type": "TRANSFER"
    },
    "ad": {
        "action_type": "CREATE"
    }
}

이벤트 수신 처리

// React
React.useEffect(() => {
  const onMessage = (messageEvent: MessageEvent<ExtensionResult>) => {
    if (messageEvent.data.service_type === 'BIZ_EXTENSION') {
      ...
    }
  };

  window.addEventListener('message', onMessage);

  return () => {
    window.removeEventListener('message', onMessage);
  };
}, []);
 
// iOS
// https://developer.apple.com/documentation/webkit/wkscriptmessagehandler
func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
  ...
}

매장 조회

기본 정보

요구 사양에 맞춰 제휴사에서 개발해야 하는 API입니다. 개발 완료 후 카카오비즈니스 간편연결을 연동할 수 있습니다. 카카오싱크 간편설정을 적용한 제휴사는 쇼핑몰 정보 조회 API를 활용할 수 있습니다.

카카오가 가맹점의 사업자와 매장 정보를 조회하기 위해 호출하는 제휴사의 API입니다.

제휴사 플랫폼 URL과 매장 고유 코드를 포함한 지정된 형식의 URL로 GET 요청을 받습니다. 인증이 필요한 경우 헤더 형식을 지정하고 요청에 포함시켜 수행할 수 있습니다. (참고: 매장 고유 코드 관리)

요청 받기 성공 시 응답으로 매장 정보를 포함한 JSON 객체를 반환해야 합니다.

요청

헤더

경로 변수

응답

본문

Business

Address

SiteData

AuthUser

예제

요청

curl -v -G GET "https://${PARTNER_PLATFORM_URL}/.../${STORE_KEY}"

응답

HTTP/1.1 200 OK
{
    "business": {
        "identificationNumber": "사업자 등록 번호 또는 고유 번호",
        "name": "업체 또는 사업자 이름",
        "representativeName": "대표자 이름",
        "category": "업태",
        "categoryItem": "종목",
        "address": {
            "zipCode": "우편번호",
            "baseAddress": "사업자의 기본주소",
            "detailAddress": "주소2"
        },
        "mailOrderNumberType": "DEALER",
        "mailOrderNumber": "2015-제주아라-0032"
    },
    "siteData": {
        "name": "매장 이름",
        "image": "매장 로고 이미지 URL",
        "description": "매장 대표 문구"
    },
    "authUser": {
        "name": "가맹점 본인 이름",
        "phoneNumber": "가맹점 본인 핸드폰 번호"
    }
}

간편연결 상태 웹훅

기본 정보

요구 사양에 맞춰 제휴사에서 개발해야 하는 API입니다.

간편연결의 상태 변화를 제휴사에서 지정한 웹훅 URL로 전달합니다.

제휴사 웹훅 URL로 POST 요청을 받습니다. 인증이 필요한 경우 헤더 형식을 지정하고 요청에 포함시켜 수행할 수 있습니다.

요청

헤더

경로 변수

본문

Data

예제

curl -v -X POST "${PARTNER_CALLBACK_URL}" \
    -d '{
            "storeKey": "${STORE_KEY}",
            "action": "CREATE",
            "result": "success",
            "data":
            {
                "service": "channel",
                "channelPublicId": "_sxcH",
                "channelProfileName": "채널 이름",
                "channelUuid" : "채널 검색용 ID"
            }
        }'

매장 연결 해제

기본 정보

제휴사와 매장의 간편연결을 해제합니다. 제휴사가 일괄 생성한 채널에 대한 간편연결도 권한 이관 여부와 상관없이 해제할 수 있습니다.

제휴사 앱 어드민 키를 헤더에 담아 POST로 요청합니다. 암호화된 매장 고유 코드를 쿼리 파라미터로 함께 전달해야 합니다. (참고: 매장 고유 코드 관리)

요청 성공 시 응답은 본문 없이 HTTP 200 상태 코드만 반환합니다. 요청 실패 시 에러 코드로 원인을 확인합니다.

요청

헤더

쿼리 파라미터

예제

요청

curl -v -X POST "https://kapi.kakao.com/v1/talkchannel/unlink?store_key=${STORE_KEY}" \
    -H "Authorization: KakaoAK ${PARTNER_APP_ADMIN_KEY}"

응답: 성공

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
}

응답: 실패, 이미 연결 해제된 매장 채널

HTTP/1.1 400 Bad request
Content-Type: application/json;charset=UTF-8
{
    "code": "-826",
    "msg": "AlreadyExistChannelException"
}

에러 코드

이 외에 에러 코드는 공통 에러 코드를 참고합니다.

팝업창 내 에러

간편연결 팝업창에서 발생하는 에러의 원인에 대해 안내합니다. 에러는 제목 아래 표시되는 본문으로 구분합니다.

제휴사 페이지 구성 가이드

제휴사의 앱 또는 웹페이지에서 가맹점이 카카오비즈니스 간편연결을 할 수 있도록 디자인 가이드 내용을 준수해 아래 사항을 제공해야 합니다. 이미지를 함께 참고합니다.

• 카카오비즈니스 간편연결 소개 문구
• 개인정보 제3자 제공 동의항목 (미동의시 팝업 실행 불가)
• 간편연결 시작하기 버튼

• 간편연결 완료 상태 표시 문구
• 연결된 채널 정보
• 채널홈 및 채널 관리자센터 연결 버튼

디자인 가이드

• 주요 버튼 색상: #FEE500
• 부수 버튼 색상: #ECECEC
• 텍스트 색상: #191919
• 폰트: Noto Sans CJK/KR
• 권장 데스크탑 팝업창 사이즈: 520 x 812 픽셀(Pixel)

참고: 개인정보 제3자 제공동의 동의문

아래는 제휴사가 가맹점 본인에게 받아야할 개인정보 제3자 제공동의 동의문 예시입니다. 내용은 협의에 따라 수정될 수 있습니다.

용어집

이 외 용어는 용어집을 참고합니다.