제휴사 전용 API

이 문서는 제휴사 전용 카카오톡 채널 API 사용 방법을 안내합니다.

제휴사 전용

제휴사 전용 API는 별도 사용 협의가 완료된 서비스 앱에만 제공하는 기능입니다. 이 문서는 해당 기능 사용 권한이 있는 앱에 한해 유효한 정보를 담고 있습니다.

제휴사용 채널 생성

기본 정보

메서드	URL	인증 방식
`POST`	`https://kapi.kakao.com/v1/talkchannel/create`	서비스 앱 어드민 키

권한	사전 설정	카카오 로그인	동의항목
필요	어드민 키	-	-

제휴사에 입점한 가맹점의 카카오톡 채널을 개설하여 제휴사와 카카오 비즈니스를 연결합니다.

비즈니스 채널로 자동 전환을 위해서, 제휴 계약 및 채널 비즈니스 심사 대행 부속계약이 체결되어 있어야 합니다.

호출 허용 IP 주소 설정

해당 API는 보안 유지를 위한 호출 허용 IP 주소 등록이 필수 사항입니다. 앱 관리 페이지의 [앱] > [어드민 키] > [호출 허용 IP 주소]에서 사용할 IP를 등록합니다. 자세한 정보는 호출 허용 IP 주소를 참고합니다.

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

요청 성공 시 응답은 매장 고유 코드와 카카오톡 채널 프로필 ID를 포함한 JSON 객체입니다. 요청 실패 시 에러 코드에서 원인을 확인합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O
Content-Type	`Content-Type: application/json` 요청 데이터 타입	O

쿼리 파라미터

이름	타입	설명	필수
store_key	`String`	제휴사에서 부여한 매장의 암호화된 고유 코드(최대 255자)	O
store_id	`Long`	제휴사에서 부여한 매장의 암호화된 정수형 고유 코드	O

본문

이름	타입	설명	필수
business	`Business`	비즈니스 인증을 위한 사업자 정보	O
channel_profile	`ChannelProfile`	카카오톡 채널 정보	O

Business

이름	타입	설명	필수
identification_number	`String`	사업자등록번호 또는 고유 번호	O
name	`String`	업체 또는 사업자 이름	O
representative_name	`String`	대표자 이름	O
business_category	`String`	업태	O
business_category_item	`String`	종목	O
zipcode	`String`	사업자 주소의 우편번호	O
base_address	`String`	사업자의 우편번호 기준 기본 주소	O
detail_address	`String`	사업자의 건물명, 동, 호수 등 상세 주소	O

ChannelProfile

이름	타입	설명	필수
name	`String`	채널 프로필명(최대 20자)	O
search_id	`String`	채널 검색용 ID(최대 15자)	O
profile_image_url	`String`	프로필 이미지 URL 권장 크기: 640 x 640 px 최대 용량: 10 MB 지원하는 파일 형식: `JPG`, `JPEG`, `PNG`	O
is_adult	`String`	성인 채널 여부, 아래 중 하나 `Y`: 성인 채널 `N`: 성인 채널 아님	O

응답

본문

이름	타입	설명	필수
store_key	`String`	매장 고유 코드	O
channel_public_id	`String`	카카오톡 채널 프로필 ID	O
code	`Integer`	에러 코드	X
msg	`String`	에러 메시지	X
extras	`JSON`	에러 관련 추가 정보	X

예제

요청

curl -X POST "https://kapi.kakao.com/v1/talkchannel/create?store_key=${STORE_KEY}&store_id=${STORE_ID}" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
            "business": {
                "identification_number": "000-00-00000",
                "name": "주식회사 카카오",
                "representative_name": "카카오",
                "business_category": "서비스업",
                "business_category_item": "인터넷정보매개(포털)",
                "zipcode": "63309",
                "base_address": "제주특별자치도 제주시 첨단로 242(영평동)",
                "detail_address": "카카오 스페이스"
            },
            "channel_profile": {
                "name": "카카오",
                "search_id": "카카오",
                "profile_image_url": "https://${프로필 이미지 URL}",
                "is_adult": "Y"
            }
        }'

응답: 성공

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "store_key": "${STORE_KEY}",
  "channel_public_id": "${CHANNEL_PUBLIC_ID}"
}

응답: 실패, 파라미터 누락

// HTTP/1.1 400 Bad request
// Content-Type: application/json;charset=UTF-8
{
  "code": -2,
  "msg": "미입력한 항목이 존재합니다.",
  "extras": {
    "violations": {
      "name": "2자 이상 20자 미만으로 입력해주세요.",
      "searchId": "2자 이상 15자 미만으로 입력해주세요."
    }
  }
}

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

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

에러 코드

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

코드	설명	HTTP 상태 코드
-825	해당 `store_key`에 연결된 채널이 이미 존재하는 경우	400

인하우스/공동체 문서

문서 홈

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

카카오맵

내비게이션

광고

검색

더 보기