메타데이터 API (사용 중지 예정)

기존 연동 파트너사가 카카오(게임플레이) 서버로 호출해 게임 정보를 관리하던 API입니다.
등록·수정·단건 조회·목록 조회 4개 엔드포인트를 제공하며, 파트너센터 오픈과 함께 사용이 중지됩니다.

사용 중지 안내

게임플레이 파트너센터가 오픈하면 메타데이터 API 호출은 오류로 응답되며, 게임 정보를 등록·수정할 수 없습니다.
파트너센터 오픈 시점부터는 게임 정보를 변경할 때 업데이트 심사를 반드시 거쳐야 하므로, 심사를 건너뛰는 API 경로는 제공하지 않습니다.
신규 파트너사는 이 API를 연동하지 않고 현재 가이드에 따라 입점을 준비한 뒤, 파트너센터 오픈 후 게임 정보를 등록하고 출시 심사를 요청하세요.
기존 연동 파트너사는 오픈 전까지 기존 API와 기존 심사 절차를 사용합니다.
아래 스펙은 오픈 전까지 운영 중인 연동을 유지하기 위한 참고 자료입니다.

관련 가이드: 심사 가이드: 파트너센터 출시·업데이트 심사 절차

API 목록

이름	Method	Path
신규 등록	`POST`	`/v1/api/gameplay`
수정	`PUT`	`/v1/api/gameplay`
단건 조회	`GET`	`/v1/api/gameplay/games/{gameCode}`
목록 조회	`GET`	`/v1/api/gameplay/games`

공통

Base URL

http

https://pf-external-api.kakao.com

헤더

Header	설명
`Authorization`	필수`KakaoAK {APP_KEY}`: 파트너사 디벨로퍼스 앱의 REST API 키
`Content-Type`	필수`application/json`

인증

Authorization 헤더의 APP_KEY 검증
IP ACL 기반(사전 등록된 IP만 허용) 이중 인증.
파트너사 정보 전달 양식에서 제출한 IP 사용

Rate Limit

항목	값
제한 기준	요청 IP 단위
허용량	최대 1,000 RPS
Burst	순간 최대 2,000 requests

제한 초과 시 503 Service Temporarily Unavailable이 반환됩니다.

공통 에러 코드

code	설명
`-900`	허용되지 않은 IP에서 접근

각 API별 추가 에러 코드는 아래 각 섹션을 참고하세요.

게임 메타 신규 등록

파트너사가 신규 게임을 등록하는 시점에 호출합니다.

http

POST /v1/api/gameplay

Request Body

필드	타입	설명
`code`	`string`	필수게임별 고유 키. 최대 25자. 광고의 CPID와 반드시 동일해야 함
`name`	`string`	필수타이틀. 최대 30자
`description`	`string`	필수세부 설명. 최대 50자
`thumbnail`	`object`	필수썸네일 정보. thumbnail 객체 참고
`link`	`string`	필수랜딩 URL. 최대 100자
`genre`	`object`	필수장르. genre 객체 참고
`play_mode`	`string`	필수플레이 방식. play_mode 정의 참고
`ranking`	`object`	필수랭킹 메타. ranking 객체 참고. 랭킹 미사용 게임도 `enabled: false`로 필수 전달
`display_info`	`object`	필수게임 표시 정보. display_info 객체 참고

thumbnail

필드	타입	설명
`square`	`string`	정사각형 이미지 URL. `640 × 640` (1:1), 200 KB 이하
`wide`	`string`	와이드 이미지 URL. `1200 × 630` (1.91:1), 1 MB 이하

카카오가 전달받은 URL에서 이미지를 다운로드해 카카오 CDN에 업로드합니다.
이미지 도메인은 사전에 카카오에 전달해 외부 프록시 화이트리스트 등록이 필요합니다.

genre

필드	타입	설명
`main`	`string`	메인 장르
`subs`	`string[]`	서브 장르. 최대 2개

메인과 동일한 값을 서브에 포함할 수 없습니다.

장르 코드

값	설명
`PUZZLE`	퍼즐
`ACTION`	액션
`SHOOTING`	슈팅
`STRATEGY`	전략
`SIMULATION`	시뮬
`RPG`	RPG
`ADVENTURE`	어드벤쳐
`ARCADE`	아케이드
`BOARD`	보드
`QUIZ`	퀴즈
`SPORTS`	스포츠
`RACING`	레이싱

display_info

게임산업진흥법 시행령 별표 3에 따른 법정 표시 의무 항목입니다.

필드	타입	설명
`age_rating`	`string`	필수이용 등급
`rating_classification_number`	`string`	필수등급 분류 결정서의 고유 번호. 최대 30자 (예: 게임물관리위원회 `CC-OM-260204-002`, 구글플레이스토어 `GOOG-SG-250418-0164`)
`rating_classification_date`	`string`	필수등급 분류 일자. `YYYY-MM-DD`
`corporate_name`	`string`	필수상호. 게임 심의를 받은 자(배급업자 또는 제작업자)의 상호로, 게임별로 다를 수 있음. 최대 50자
`business_registration_number`	`string`	필수제작·배급업 등록(신고) 번호. 게임산업진흥법 제25조에 따라 시·군·구청에 등록·신고한 번호(자유 형식). 회사가 동일하면 게임 간 번호가 같을 수 있음. 최대 30자 (예: `2025-서울강남-06282`)
`content_descriptors`	`string[]`	필수게관위 등급 분류 결정서의 게임물 내용 정보. 최대 7개. 해당 항목 없으면 빈 배열
`has_probability_item`	`boolean`	필수게임 내 확률형 아이템 포함 여부
`additional_notice`	`string`	기타 고지사항. 최대 50자 (배급자 정보 등)

age_rating

값	설명
`ALL`	전체 이용가
`AGE_12`	12세 이용가
`AGE_15`	15세 이용가
`ADULT`	청소년 이용 불가

content_descriptors

값	설명
`SEXUAL`	선정성
`VIOLENT`	폭력성
`FEAR`	공포
`LANGUAGE`	언어의 부적절성
`DRUG`	약물
`CRIME`	범죄
`GAMBLING`	사행성

전체 이용가 게임이라도 해당 내용이 있으면 표시 의무가 있으므로 누락 없이 전달합니다.

Response

200 OK (본문 없음)

에러

code	설명
`-850`	이미 등록된 게임 (`code` 중복)
`-900`	허용되지 않은 IP

게임 메타 수정

http

PUT /v1/api/gameplay

Request Body는 신규 등록과 동일합니다.
변경되지 않은 필드 값도 모두 전달해야 하며, 수정된 값이 하나도 없으면 에러가 발생합니다.

Response

200 OK

에러

code	설명
`-851`	변경된 내역이 없음
`-852`	해당 게임이 존재하지 않음
`-900`	허용되지 않은 IP

게임 메타 단건 조회

gameCode로 파트너사 vendor의 등록 게임 1건을 조회합니다.

http

GET /v1/api/gameplay/games/{gameCode}

Path Parameter

이름	타입	설명
`gameCode`	`string`	필수등록 시 전달한 `code` 값

Response

json

{
  "code": "my_game_001",
  "name": "샘플 게임",
  "description": "샘플 설명",
  "thumbnail": {
    "square": "https://vendor-cdn.example.com/games/my_game_001/square.png",
    "wide": "https://vendor-cdn.example.com/games/my_game_001/wide.png"
  },
  "link": "https://vendor-game.example.com/h5/my_game_001",
  "genre": {"main": "PUZZLE", "subs": ["ACTION"]},
  "play_mode": "STAGE",
  "ranking": {
    "enabled": true,
    "metrics": [{"type": "SCORE", "order": "DESC"}],
    "period_types": ["WEEKLY", "MONTHLY"],
    "default_period_type": "WEEKLY"
  },
  "display_info": {
    "age_rating": "ALL",
    "rating_classification_number": "CC-OM-260204-002",
    "rating_classification_date": "2026-02-04",
    "corporate_name": "샘플게임즈",
    "business_registration_number": "2025-서울강남-06282",
    "content_descriptors": [],
    "has_probability_item": false,
    "additional_notice": null
  },
  "status": "ON"
}

thumbnail은 등록 시 전달한 원본 URL이 반환됩니다 (카카오 CDN 업로드본 아님).

status

값	설명
`ON`	서비스 중
`OFF`	비활성
`QA`	QA 단계 (운영 환경 미노출)
`DELETED`	삭제됨
`UNKNOWN`	미정

에러

code	설명
`-2`	vendor 미등록 caller
`-852`	본인 vendor의 등록 게임 중 `gameCode` 매칭 없음
`-900`	허용되지 않은 IP

게임 메타 목록 조회

본인 vendor가 등록한 게임 메타 정보를 모두 조회합니다.

http

GET /v1/api/gameplay/games

별도 파라미터 없이 caller APP_KEY의 vendor로 스코프가 자동 한정됩니다.

Response

게임 메타 단건 조회의 Response Body 배열 형태입니다.

정렬: 최신 등록순 (createdAt DESC)
status = DELETED인 게임은 제외

json

[
  {"code": "my_game_002", "name": "신규 게임", "status": "OFF"},
  {"code": "my_game_001", "name": "샘플 게임", "status": "ON"}
]

에러

code	설명
`-2`	vendor 미등록 caller
`-900`	허용되지 않은 IP

랭킹 데이터 스펙

랭킹 노출은 사전 조율 후 확정됩니다

ranking.enabled: true로 설정해도 모든 게임이 게임플레이 랭킹 영역(리더보드)에 노출되는 것은 아닙니다.
카카오가 전송된 기록값 데이터를 확인하고 파트너사와 사전 조율을 거쳐 노출 대상과 시점을 확정합니다.
랭킹 설정과 기록값 전송은 노출을 위한 데이터 준비 단계이며, 노출 스펙은 추후 변경될 수 있습니다.
게임 내 자체 랭킹은 이와 무관하게 자유롭게 구현할 수 있습니다.

게임플레이 서비스 내 랭킹 영역에 게임별 랭킹을 노출하려면 다음 두 데이터가 매칭되어야 합니다.
랭킹 설정은 파트너센터에 입력하며, 아래 ranking 스펙은 파트너센터 오픈 전까지 기존 연동을 유지하기 위한 참고 자료입니다.

구분	설명	전달 시점
파트너센터 랭킹 설정 오픈 전: 메타데이터 `ranking`	플레이 방식, 랭킹 사용 여부, 산정 기준	게임 등록·수정 시
사용자 액션데이터 API	사용자 플레이 실제 기록값	플레이 시작·완료·종료 시

파트너센터에 설정한 랭킹 기준과 액션데이터의 기록값이 일치해야 랭킹 집계가 가능합니다.
파트너센터 오픈 전까지는 메타데이터 API로 설정한 기준이 기준값이 됩니다.

`play_mode`

게임 구조를 설명하는 값이며, 실제 랭킹 산정 기준은 ranking.metrics에서 별도 정의합니다.

값	설명
`ROUND`	단판형 게임
`STAGE`	스테이지형 게임
`TIME_ATTACK`	타임어택형 게임
`LEVEL`	레벨형 게임

`ranking`

필드	타입	설명
`enabled`	`boolean`	필수랭킹 사용 여부
`metrics`	`object[]`	랭킹 산정 기록값 목록. 1개만 지원. `enabled: true`일 때 필수
`period_types`	`string[]`	제공할 랭킹 기간. `enabled: true`일 때 필수
`default_period_type`	`string`	기본 랭킹 기간. 허용값은 period_types와 동일. `enabled: true`일 때 필수

랭킹 미사용 게임은 ranking.enabled: false만 전달하고 나머지 하위 필드는 생략할 수 있습니다.

`metrics`

필드	타입	설명
`type`	`string`	필수기록값 유형
`order`	`string`	필수정렬 방향

type 허용값

값	설명	예시
`SCORE`	점수	`123450`
`TIME`	시간 (ms)	`58300` (58.3초)
`PROGRESS`	단계·레벨·웨이브	`10`, `Lv.12`
`DISTANCE`	거리·높이·깊이	`78.1` (m)
`COUNT`	횟수·콤보·수집량	`24`, `120`
`RATE`	비율·정확도·성공률	`98.5` (%)

order

값	설명
`ASC`	값이 작을수록 상위 (예: 클리어 시간)
`DESC`	값이 클수록 상위 (예: 점수, 거리)

복수 metrics는 미지원이며 랭킹 기준은 1개 타입만 지원합니다.

`period_types`

값	설명
`WEEKLY`	주간 랭킹
`MONTHLY`	월간 랭킹

사전 문의 필요 케이스

임의 값을 추가하지 않고 카카오 담당자와 사전 협의합니다.

play_mode로 표현하기 어려운 게임
metrics.type으로 표현하기 어려운 기록값
2개 이상의 기록값 조합이 필요한 경우
WEEKLY·MONTHLY 외 기간 랭킹이 필요한 경우
실시간·시즌·보상 지급용 등 별도 랭킹 정책이 필요한 경우

사전 협의 없이 정의되지 않은 값을 전달하면 랭킹 노출이 제한되거나 데이터가 정상 집계되지 않을 수 있습니다.

참고 문서

액션데이터 API: 사용자별 실제 랭킹 기록값 전송
게임플레이 파트너센터오픈 예정: 신규 게임 정보 등록·수정 및 심사 요청
데이터 샘플 카탈로그: 기존 파트너용 게임 유형별 등록 요청 본문 예시
계정 상태 변경 웹훅 연동
심사 가이드
기술 문의: 카카오디벨로퍼스 데브톡

메타데이터 API (사용 중지 예정) ​

API 목록 ​

공통 ​

Base URL ​

헤더 ​

인증 ​

Rate Limit ​

공통 에러 코드 ​

게임 메타 신규 등록 ​

Request Body ​

thumbnail ​

genre ​

display_info ​

Response ​

에러 ​

게임 메타 수정 ​

Response ​

에러 ​

게임 메타 단건 조회 ​

Path Parameter ​

Response ​

에러 ​

게임 메타 목록 조회 ​

Response ​

에러 ​

랭킹 데이터 스펙 ​

play_mode ​

ranking ​

metrics ​

period_types ​

사전 문의 필요 케이스 ​

참고 문서 ​

메타데이터 API (사용 중지 예정)

API 목록

공통

Base URL

헤더

인증

Rate Limit

공통 에러 코드

게임 메타 신규 등록

Request Body

thumbnail

genre

display_info

Response

에러

게임 메타 수정

Response

에러

게임 메타 단건 조회

Path Parameter

Response

에러

게임 메타 목록 조회

Response

에러

랭킹 데이터 스펙

`play_mode`

`ranking`

`metrics`

`period_types`

사전 문의 필요 케이스

참고 문서