이 문서는 광고 만들기: 광고계정 API 사용법을 안내합니다.
광고계정이란 광고집행을 관리하는 단위로, 광고주가 직접 생성하거나 광고 운영을 대행하는 대행사가 직접 생성할 수 있습니다. 대행사에서 광고계정을 생성할 경우 광고주 정보를 별도로 기입할 수 있습니다. 광고계정의 사업자 정보는 세금계산서 발행정보의 기준이 됩니다.
GET /openapi/v1/adAccounts HTTP/1.1
Host: api.keywordad.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
광고계정 목록을 조회합니다.
액세스 토큰(Access token)을 헤더에 담아 GET
으로 요청합니다. 성공 시 응답 바디에 JSON 객체로 광고계정 상세 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
Name | Type | Description | Required |
---|---|---|---|
Authorization | String |
액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달 |
O |
Name | Type | Description | Required |
---|---|---|---|
config | String |
광고계정 상태ON , OFF , DEL 중 하나 미입력 시 ON , OFF 만 출력 |
X |
Name | Type | Description |
---|---|---|
id | Long |
광고계정 ID |
name | String |
광고계정명 |
memberType | String |
멤버타입 |
config | String |
광고계정 상태(ON , OFF , DEL ) |
curl -X GET "https://api.keywordad.kakao.com/openapi/v1/adAccounts?config=ON,OFF,DEL" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"
[
{
"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
)의 조합으로 만들어집니다.
Name | Type | Description | Required |
---|---|---|---|
Authorization | String |
액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달 |
O |
adAccountId | Long |
광고계정 ID | O |
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 |
광고계정의 게재와 관련된 현재 상태 |
curl -X GET "https://api.keywordad.kakao.com/openapi/v1/adAccounts/${adAccountId}" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: {adAccountId}"
{
"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 객체로 잔액 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
Name | Type | Description | Required |
---|---|---|---|
Authorization | String |
액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달 |
O |
adAccountId | Long |
광고계정 ID | O |
Name | Type | Description |
---|---|---|
id | Long |
광고계정 ID |
cash | Long |
유상캐시 |
freeCash | Long |
무상캐시 |
curl -X GET "https://api.keywordad.kakao.com/openapi/v1/adAccounts/balance" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: {adAccountId}"
{
"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 객체로 영업권 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
Name | Type | Description | Required |
---|---|---|---|
Authorization | String |
액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달 |
O |
adAccountId | Long |
광고계정 ID | O |
Name | Type | Description |
---|---|---|
id | Long |
광고계정 ID |
bizRightCompanyName | String |
영업권을 가진 사업자명 |
curl -X GET "https://api.keywordad.kakao.com/openapi/v1/adAccounts/bizRight" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "AdAccountId: {adAccountId}"
{
"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 객체로 사용자의 카카오톡 채널 프로필 정보 목록을 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
Name | Type | Description | Required |
---|---|---|---|
Authorization | String |
액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달 |
O |
Name | Type | Description |
---|---|---|
uuid | String |
카카오톡 채널 검색용 ID |
name | String |
카카오톡 채널 이름 |
curl -X GET "https://api.keywordad.kakao.com/openapi/v1/adAccounts/channel/profiles" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"
[
{
"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
로 요청합니다. 성공 시 생성된 광고계정 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
Name | Type | Description | Required |
---|---|---|---|
Authorization | String |
액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달 |
O |
Name | Type | Description | Required |
---|---|---|---|
name | String |
생성할 광고계정 이름 | O |
ownerCompanyId | Long |
광고계정 소유 사업자 번호 사업자 정보 보기를 통해 조회한 ID 값 대행사 사용자는 대행사 사업자 번호 |
O |
advertiserCompanyId | Long |
광고주 사업자 번호 사업자 정보 보기를 통해 조회한 ID 값 ( ownerCompanyId 에 대행사 번호 추가 후 advertiserCompanyId 미입력시 개인 광고주 유형으로 생성) |
X* |
* 광고주 사업자인 경우, advertiserCompanyId는 필수 파라미터 아님
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 |
광고계정의 게재와 관련된 현재 상태 |
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
}'
{
"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에 응답 바디는 없으며, 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
Name | Type | Description | Required |
---|---|---|---|
Authorization | String |
액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달 |
O |
adAccountId | Long |
광고계정 ID | O |
Name | Type | Description | Required |
---|---|---|---|
config | String |
변경하고자 하는 광고계정의 상태 ON, OFF 중 하나 |
O |
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"
}'
HTTP/1.1 200 OK
Content-Length: 0
Content-type: application/json;charset=UTF-8