카카오 키워드광고

광고 생성: 광고계정

이 문서는 광고 생성: 광고계정 API 사용법을 안내합니다.

광고계정이란 광고집행을 관리하는 단위로, 광고주가 직접 생성하거나 광고 운영을 대행하는 대행사가 직접 생성할 수 있습니다. 대행사에서 광고계정을 생성할 경우 광고주 정보를 별도로 기입할 수 있습니다. 광고계정의 사업자 정보는 세금계산서 발행정보의 기준이 됩니다.

광고계정 목록 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://api.keywordad.kakao.com/openapi/v1/adAccounts/pages`	비즈니스 토큰

요구 사항	참고
비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

광고계정 목록을 반환합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` 인증 방식, 비즈니스 토큰으로 인증 요청	O

쿼리 파라미터

이름	타입	설명	필수
config	`String`	광고계정 상태 `ON`, `OFF`, `DEL` 중 하나 미입력 시 `ON`, `OFF`만 출력	X
page	`Integer`	조회할 페이지 번호(기본값: 0) 다음 페이지를 조회하려면 값을 1씩 증가시켜 요청	X
size	`Integer`	페이지 당 광고계정 개수(기본값: 10)	X

응답

본문

이름	타입	설명
content	`AdAccount[]`	광고계정 정보 목록
size	`Integer`	페이지 당 개수
totalElements	`Integer`	전체 개수
totalPages	`Integer`	전체 페이지 개수
page	`Integer`	페이지 번호

AdAccount

이름	타입	설명
memberType	`String`	멤버 타입, 아래 중 하나 MASTER: 마스터 권한 MEMBER: 멤버 권한
name	`String`	광고계정명
config	`String`	광고계정 상태, 아래 중 하나 ON OFF DEL
id	Long	광고계정 번호

예제

요청

curl -G GET "https://api.keywordad.kakao.com/openapi/v1/adAccounts/pages" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -d "config=ON" \
    -d "config=OFF" \
    -d "page=0" \
    -d "size=2"

응답

{
  "content": [
    {
      "id": 111,
      "name": "테스트계정1",
      "memberType": "MASTER",
      "config": "ON"
    },
    {
      "id": 222,
      "name": "테스트계정2",
      "memberType": "MASTER",
      "config": "ON"
    }
  ],
  "size": 2,
  "totalElements": 92,
  "totalPages": 46,
  "page": 0
}

광고계정 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://api.keywordad.kakao.com/openapi/v1/adAccounts/${AD_ACCOUNT_ID}`	비즈니스 토큰

요구 사항	참고
비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

특정 광고계정의 상세 정보를 반환합니다.

광고계정의 게재와 관련된 상태(statusDescription)는 광고계정 상태(config), 관리자정지 여부(adminStop), 잔액부족 여부(outOfBalance)의 조합으로 만들어집니다.

광고계정 종류

광고계정은 사업자 광고계정, 개인 광고계정 두 가지 종류가 있습니다. 광고계정 별로 필요한 정보는 아래와 같습니다.

광고계정	광고계정 소유 사업자 정보	광고계정 사업자 정보
사업자 광고계정(광고주 생성)	O	O
개인 광고계정	X	X

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` 인증 방식, 비즈니스 토큰으로 인증 요청	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` 광고계정 ID	O

경로 변수

이름	타입	설명	필수
AD_ACCOUNT_ID	`Long`	광고계정 ID	O

응답

본문

이름	타입	설명
id	`Long`	광고계정 ID
name	`String`	광고계정명
type	`String`	광고계정 유형, 아래 중 하나 `BUSINESS`: 사업자 광고계정 `INDIVIDUAL`: 개인 광고계정
config	`String`	광고계정 상태, 아래 중 하나 `ON`: 운영중 `OFF`: 운영중지 `DEL`: 삭제
adminStop	`Boolean`	관리자 정지 여부
outOfBalance	`Boolean`	잔액부족 여부
statusDescription	`String`	광고계정의 게재와 관련된 현재 상태
bizWalletId	`Long`	비즈월렛 ID
advertiser	`Company`	광고주 사업자 정보

예제

요청

curl -v -G GET "https://api.keywordad.kakao.com/openapi/v1/adAccounts/${AD_ACCOUNT_ID}" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"

응답

{
  "id": "1111111111",
  "name": "카카오키워드광고_광고계정1",
  "type": "BUSINESS",
  "config": "ON",
  "adminStop": false,
  "outOfBalance": false,
  "statusDescription": "운영 가능",
  "bizWalletId": "11111",
  "advertiser": {
    "businessRegistrationNumber": "120-81-47521",
    "name": "주식회사 카카오"
  }
}

실시간 잔액 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://api.keywordad.kakao.com/openapi/v1/adAccounts/balance`	비즈니스 토큰

요구 사항	참고
비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

광고계정의 실시간 잔액을 반환합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` 인증 방식, 비즈니스 토큰으로 인증 요청	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` 광고계정 ID	O

응답

본문

이름	타입	설명
id	`Long`	광고계정 ID
bizWalletId	`Long`	비즈월렛 ID
cash	`Double`	유상캐시
freeCash	`Double`	무상캐시

예제

요청

curl -v -G GET "https://api.keywordad.kakao.com/openapi/v1/adAccounts/balance" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"

응답

{
  "id": "1111111111",
  "bizWalletId": "11111",
  "cash": 5000000.0,
  "freeCash": 100000.0
}

영업권 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://api.keywordad.kakao.com/openapi/v1/adAccounts/bizRight`	비즈니스 토큰

요구 사항	참고
비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

광고계정 영업권을 반환합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` 인증 방식, 비즈니스 토큰으로 인증 요청	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` 광고계정 ID	O

응답

본문

이름	타입	설명
id	`Long`	광고계정 ID
bizRightCompanyName	`String`	영업권을 가진 회사명(상호, 법인 또는 단체명)

예제

요청

curl -v -G GET "https://api.keywordad.kakao.com/openapi/v1/adAccounts/bizRight" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"

응답

{
  "id": 1111111111,
  "bizRightCompanyName": "주식회사 카카오"
}

카카오톡 채널 프로필 목록 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://api.keywordad.kakao.com/openapi/v1/adAccounts/channel/profiles`	비즈니스 토큰

요구 사항	참고
비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

사용자의 카카오톡 채널 프로필 목록을 반환합니다.

응답의 각 id 값을 비즈채널 생성 시 이용할 수 있습니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` 인증 방식, 비즈니스 토큰으로 인증 요청	O

응답

본문

이름	타입	설명
uuid	`String`	카카오톡 채널 검색용 ID
name	`String`	카카오톡 채널 이름

예제

요청

curl -v -G GET "https://api.keywordad.kakao.com/openapi/v1/adAccounts/channel/profiles" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}"

응답

[
  {
    "uuid": "@kakao1",
    "name": "카카오채널1"
  },
  {
    "uuid": "@kakao2",
    "name": "카카오채널2"
  }
]

광고계정 생성

기본 정보

메서드	URL	인증 방식
`POST`	`https://api.keywordad.kakao.com/openapi/v1/adAccounts`	비즈니스 토큰

요구 사항	참고
비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

새로운 광고계정을 생성합니다.

광고계정 생성은 사업자 계정에 한하여 가능하며, 광고주 및 대행사 계정을 생성할 수 있습니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` 인증 방식, 비즈니스 토큰으로 인증 요청	O

본문

이름	타입	설명	필수
name	`String`	생성할 광고계정 이름	O
advertiserCompanyId	`Long`	광고주 사업자 번호 사업자 정보 조회 API로 조회한 ID 값	O

응답

본문

이름	타입	설명
id	`Long`	광고계정 ID
name	`String`	광고계정명
type	`String`	광고계정 유형, 아래 중 하나 `BUSINESS`: 사업자 광고계정 `INDIVIDUAL`: 개인 광고계정
config	`String`	광고계정 상태(ON, OFF 중 하나)
adminStop	`Boolean`	관리자 정지 여부
outOfBalance	`Boolean`	잔액부족 여부
statusDescription	`String`	광고계정의 게재와 관련된 현재 상태
bizWalletId	`Long`	비즈월렛 ID
advertiser	`Company`	광고주 사업자 정보

예제

요청

curl -v -X POST "https://api.keywordad.kakao.com/openapi/v1/adAccounts" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
            "name": "테스트_광고계정",
            "advertiserCompanyId": 34
        }'

응답

{
  "id": "1111111111",
  "name": "카카오키워드광고_광고계정",
  "type": "BUSINESS",
  "config": "ON",
  "adminStop": false,
  "outOfBalance": false,
  "statusDescription": "운영중",
  "bizWalletId": "11111",
  "advertiser": {
    "businessRegistrationNumber": "120-81-47521",
    "name": "주식회사 카카오"
  }
}

광고계정 상태 변경

기본 정보

메서드	URL	인증 방식
`PUT`	`https://api.keywordad.kakao.com/openapi/v1/adAccounts`	비즈니스 토큰

요구 사항	참고
비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

광고계정의 상태를 ON 또는 OFF로 변경합니다.

광고계정을 삭제 중인 경우 변경할 수 없습니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` 인증 방식, 비즈니스 토큰으로 인증 요청	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` 광고계정 ID	O

본문

이름	타입	설명	필수
config	`String`	변경하고자 하는 광고계정의 상태, 아래 중 하나 `ON`: 운영중 `OFF`: 운영중지	O

예제

요청

curl -v -X PUT "https://api.keywordad.kakao.com/openapi/v1/adAccounts" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \
    -H "Content-Type: application/json" \
    -d '{
            "config": "ON"
        }'

응답: 성공

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

사이드 메뉴

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

광고

지도

내비게이션

검색

더 보기

광고 생성: 광고계정

광고계정 목록 조회

기본 정보

요청

헤더

쿼리 파라미터

응답

본문

AdAccount

예제

요청

응답

광고계정 조회

기본 정보

광고계정 종류

요청

헤더

경로 변수

응답

본문

예제

요청

응답

실시간 잔액 조회

기본 정보

요청

헤더

응답

본문

예제

요청

응답

영업권 조회

기본 정보

요청

헤더

응답

본문

예제

요청

응답

카카오톡 채널 프로필 목록 조회

기본 정보

요청

헤더

응답

본문

예제

요청

응답

광고계정 생성

기본 정보

요청

헤더

본문

응답

본문

예제

요청

응답

광고계정 상태 변경

기본 정보

요청

헤더

본문

예제

요청

응답: 성공

더 보기

도움이 되었나요?