이 문서는 광고 만들기: 광고계정 API 사용법을 안내합니다.
광고계정이란 광고집행을 관리하는 단위로, 광고주가 직접 생성하거나 광고 운영을 대행하는 대행사가 직접 생성할 수 있습니다. 대행사에서 광고계정을 생성할 경우 광고주 정보를 별도로 기입할 수 있습니다. 광고계정의 사업자 정보는 세금계산서 발행정보의 기준이 됩니다.
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://api.keywordad.kakao.com/openapi/v1/adAccounts/pages |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
- | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
광고계정 목록을 조회합니다.
비즈니스 토큰을 헤더에 담아 GET
으로 요청합니다. 성공 시 응답은 광고계정 목록을 페이지 형식으로 포함합니다. 광고계정 목록의 다음 페이지를 조회하려면 page
값을 1씩 증가시켜 요청합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN} 인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
config | String |
광고계정 상태ON , OFF , DEL 중 하나미입력 시 ON , OFF 만 출력 |
X |
page | Integer |
조회할 페이지 번호(기본값: 0) | X |
size | Integer |
페이지 당 광고계정 개수(기본값: 10) | X |
이름 | 타입 | 설명 |
---|---|---|
content | AdAccount[] |
광고계정 정보 목록 |
size | Integer |
페이지 당 개수 |
totalElements | Integer |
전체 개수 |
totalPages | Integer |
전체 페이지 개수 |
page | Integer |
페이지 번호 |
이름 | 타입 | 설명 |
---|---|---|
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} |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
- | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
특정 광고계정의 상세 정보를 조회합니다.
비즈니스 토큰과 광고계정 ID(adAccountId
)를 헤더에 담아 GET
으로 요청합니다. 성공 시 응답 본문에 JSON 객체로 광고계정 상세 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
광고계정은 사업자 광고계정, 개인 광고계정 두 가지 종류가 있습니다. 광고계정 별로 필요한 정보는 다음과 같습니다.
광고계정 | 광고계정 소유 사업자 정보 | 광고계정 사업자 정보 |
---|---|---|
사업자 광고계정 (광고주 생성) |
O | O |
사업자 광고계정 (대행사 생성) |
O | Optional |
개인 광고계정 | X | X |
광고계정의 게재와 관련된 상태(statusDescription)는 광고계정 상태(config
), 관리자정지 여부(adminStop
), 잔액부족 여부(outOfBalance
)의 조합으로 만들어집니다.
이름 | 설명 | 필수 |
---|---|---|
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 |
광고계정명 |
ownerCompany | Company |
광고계정 소유 사업자 정보 |
advertiser | Company |
광고주 사업자 정보 |
type | String |
광고계정 유형 BUSINESS(사업자 광고계정), INDIVIDUAL(개인 광고계정) 중 하나 |
config | String |
광고계정 상태 ON, OFF, DEL(삭제) 중 하나 |
adminStop | Boolean |
관리자 정지 여부 |
outOfBalance | Boolean |
잔액부족 여부 |
statusDescription | String |
광고계정의 게재와 관련된 현재 상태 |
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",
"ownerCompany": {
"businessRegistrationNumber": "120-81-47521",
"name": "주식회사 카카오"
},
"advertiser": {
"businessRegistrationNumber": "120-81-47521",
"name": "주식회사 카카오"
},
"type": "BUSINESS",
"config":"ON",
"adminStop": false,
"outOfBalance": false,
"statusDescription": "운영 가능"
}
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://api.keywordad.kakao.com/openapi/v1/adAccounts/balance |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
- | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
광고계정의 실시간 잔액을 조회합니다.
비즈니스 토큰과 광고계정 ID(adAccountId
)를 헤더에 담아 GET
으로 요청합니다. 성공 시 응답 본문에 JSON 객체로 잔액 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN} 인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 |
---|---|---|
id | 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",
"cash": 5000000.0,
"freeCash": 100000.0
}
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://api.keywordad.kakao.com/openapi/v1/adAccounts/bizRight |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
- | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
광고계정 영업권을 조회합니다.
조회 대상의 비즈니스 토큰과 광고계정 ID(adAccountId
)를 헤더에 담아 GET
으로 요청합니다. 성공 시 응답 본문에 JSON 객체로 영업권 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
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/profiles |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
- | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
사용자의 카카오톡 채널 프로필 목록을 조회합니다. 응답의 각 id
값을 비즈채널 생성 시 이용할 수 있습니다.
비즈니스 토큰을 헤더에 담아 GET
으로 요청하며, 요청이 성공하면 응답 본문에 JSON 객체로 사용자의 카카오톡 채널 프로필 정보 목록을 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
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 |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
- | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
새로운 광고계정을 생성합니다. 광고계정 생성은 사업자 계정에 한하여 가능하며, 광고주 및 대행사 계정을 생성할 수 있습니다.
비즈니스 토큰을 헤더에 담아 POST
로 요청합니다. 성공 시 생성된 광고계정 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN} 인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
name | String |
생성할 광고계정 이름 | O |
ownerCompanyId | Long |
광고계정 소유 사업자 번호 사업자 정보 보기를 통해 조회한 ID 값 대행사 사용자는 대행사 사업자 번호 |
O |
advertiserCompanyId | Long |
광고주 사업자 번호 사업자 정보 보기를 통해 조회한 ID 값 ( ownerCompanyId 에 대행사 번호 추가 후 advertiserCompanyId 미입력시 개인 광고주 유형으로 생성) |
X* |
* 광고주 사업자인 경우, advertiserCompanyId는 필수 파라미터 아님
이름 | 타입 | 설명 |
---|---|---|
id | Long |
광고계정 ID |
name | String |
광고계정명 |
ownerCompany | Company |
광고계정 소유 사업자 정보 |
advertiser | Company |
광고주 사업자 정보 |
type | String |
광고계정 유형 BUSINESS(사업자 광고계정), INDIVIDUAL(개인 광고계정) 중 하나 |
config | String |
광고계정 상태(ON, OFF 중 하나) |
adminStop | Boolean |
관리자 정지 여부 |
outOfBalance | Boolean |
잔액부족 여부 |
statusDescription | String |
광고계정의 게재와 관련된 현재 상태 |
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":"테스트_광고계정",
"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": "운영중"
}
메서드 | URL | 인증 방식 |
---|---|---|
PUT |
https://api.keywordad.kakao.com/openapi/v1/adAccounts |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
- | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
광고계정의 상태를 ON 또는 OFF로 변경합니다. 광고계정이 삭제 진행 중인 경우 변경할 수 없습니다.
비즈니스 토큰과 광고계정 ID(adAccountId
)를 헤더에 담아 PUT
으로 요청합니다. 성공 시 HTTP 상태 코드 200에 응답 본문은 없으며, 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
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