kakao developers

광고 만들기: 광고계정

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

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

광고계정 목록 보기

기본 정보

GET /openapi/v1/adAccounts HTTP/1.1
Host: api.keywordad.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

광고계정 목록을 조회합니다.

액세스 토큰(Access token)을 헤더에 담아 GET으로 요청합니다. 성공 시 응답 바디에 JSON 객체로 광고계정 상세 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

Request

Header

Name	Type	Description	Required
Authorization	String	액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달	O

Parameter

Name	Type	Description	Required
config	String	광고계정 상태 ON, OFF, DEL 중 하나 미입력 시 ON, OFF만 출력	X

Response

Name	Type	Description
id	Long	광고계정 ID
name	String	광고계정명
memberType	String	멤버타입
config	String	광고계정 상태(ON, OFF, DEL)

Sample

Request

curl -X GET "https://api.keywordad.kakao.com/openapi/v1/adAccounts?config=ON,OFF,DEL" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}"

Response

[
    {
      "id": "1111111111",
      "name": "카카오키워드광고_광고계정1",
      "memberType": "MASTER",
      "config":"ON",
    },
    {
      "id": "1111111112",
      "name": "카카오키워드광고_광고계정2",
      "memberType": "MEMBER",
      "config":"ON",
    }
]

광고계정 보기

기본 정보

GET /openapi/v1/adAccounts/${adAccountId} HTTP/1.1
Host: api.keywordad.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

특정 광고계정의 상세 정보를 조회합니다.

액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청합니다. 성공 시 응답 바디에 JSON 객체로 광고계정 상세 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

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

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

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

Request

Header

Name	Type	Description	Required
Authorization	String	액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달	O
adAccountId	Long	광고계정 ID	O

Response

Name	Type	Description
id	Long	광고계정 ID
name	String	광고계정명
ownerCompany	Company	광고계정 소유 사업자 정보
advertiser	Company	광고주 사업자 정보
type	String	광고계정 유형 BUSINESS(사업자 광고계정), INDIVIDUAL(개인 광고계정) 중 하나
config	String	광고계정 상태 ON, OFF, DEL(삭제) 중 하나
adminStop	Boolean	관리자 정지 여부
outOfBalance	Boolean	잔액부족 여부
statusDescription	String	광고계정의 게재와 관련된 현재 상태

Sample

Request

curl -X GET "https://api.keywordad.kakao.com/openapi/v1/adAccounts/${adAccountId}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}" 

Response

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

실시간 잔액 보기

기본 정보

GET /openapi/v1/adAccounts/balance HTTP/1.1
Host: api.keywordad.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

광고계정의 실시간 잔액을 조회합니다.

액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청합니다. 성공 시 응답 바디에 JSON 객체로 잔액 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

Request

Header

Name	Type	Description	Required
Authorization	String	액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달	O
adAccountId	Long	광고계정 ID	O

Response

Name	Type	Description
id	Long	광고계정 ID
cash	Long	유상캐시
freeCash	Long	무상캐시

Sample

Request

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

Response

{
  "id": "1111111111",
  "cash": 5000000,
  "freeCash": 100000
}

영업권 보기

기본 정보

GET /openapi/v1/adAccounts/bizRight HTTP/1.1
Host: api.keywordad.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

광고계정 영업권을 조회합니다.

조회 대상의 액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청합니다. 성공 시 응답 바디에 JSON 객체로 영업권 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

Request

Header

Name	Type	Description	Required
Authorization	String	액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달	O
adAccountId	Long	광고계정 ID	O

Response

Name	Type	Description
id	Long	광고계정 ID
bizRightCompanyName	String	영업권을 가진 사업자명

Sample

Request

curl -X GET "https://api.keywordad.kakao.com/openapi/v1/adAccounts/bizRight" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "AdAccountId: {adAccountId}"

Response

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

카카오톡 채널 프로필 목록 보기

기본 정보

GET /openapi/v1/adAccounts/channel/profiles HTTP/1.1
Host: api.keywordad.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

사용자의 카카오톡 채널 프로필 목록을 조회합니다. 응답의 각 id 값을 비즈채널 생성 시 이용할 수 있습니다.

액세스 토큰(Access token)을 헤더에 담아 GET으로 요청하며, 요청이 성공하면 응답 바디(Body)에 JSON 객체로 사용자의 카카오톡 채널 프로필 정보 목록을 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

Request

Header

Name	Type	Description	Required
Authorization	String	액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달	O

Response

Name	Type	Description
uuid	String	카카오톡 채널 검색용 ID
name	String	카카오톡 채널 이름

Sample

Request

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

Response

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

광고계정 생성하기

기본 정보

POST /openapi/v1/adAccounts HTTP/1.1
Host: api.keywordad.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

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

액세스 토큰(Access token)을 헤더에 담아 POST로 요청합니다. 성공 시 생성된 광고계정 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

Request

Header

Name	Type	Description	Required
Authorization	String	액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달	O

Parameter

Name	Type	Description	Required
name	String	생성할 광고계정 이름	O
ownerCompanyId	Long	광고계정 소유 사업자 번호 사업자 정보 보기를 통해 조회한 ID 값 대행사 사용자는 대행사 사업자 번호	O
advertiserCompanyId	Long	광고주 사업자 번호 사업자 정보 보기를 통해 조회한 ID 값 (ownerCompanyId에 대행사 번호 추가 후 advertiserCompanyId 미입력시 개인 광고주 유형으로 생성)	X*

* 광고주 사업자인 경우, advertiserCompanyId는 필수 파라미터 아님

Response

Name	Type	Description
id	Long	광고계정 ID
name	String	광고계정명
ownerCompany	Company	광고계정 소유 사업자 정보
advertiser	Company	광고주 사업자 정보
type	String	광고계정 유형 BUSINESS(사업자 광고계정), INDIVIDUAL(개인 광고계정) 중 하나
config	String	광고계정 상태(ON, OFF 중 하나)
adminStop	Boolean	관리자 정지 여부
outOfBalance	Boolean	잔액부족 여부
statusDescription	String	광고계정의 게재와 관련된 현재 상태

Sample

Request

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

Response

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

광고계정 상태 바꾸기

기본 정보

PUT /openapi/v1/adAccounts/onOff HTTP/1.1
Host: api.keywordad.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

광고계정의 상태를 ON 또는 OFF로 변경합니다. 광고계정이 삭제 진행 중인 경우 변경할 수 없습니다.

액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 PUT으로 요청합니다. 성공 시 HTTP 상태 코드 200에 응답 바디는 없으며, 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

Request

Header

Name	Type	Description	Required
Authorization	String	액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달	O
adAccountId	Long	광고계정 ID	O

Parameter

Name	Type	Description	Required
config	String	변경하고자 하는 광고계정의 상태 ON, OFF 중 하나	O

Sample

Request

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

Response: 성공

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

더 보기

카카오 키워드광고 API 레퍼런스