Kia 개인정보 제공 동의 및 철회 API

openapi: 3.2.0
info:
  title: KIA Developers Connected Car 개인정보 제공 동의 및 철회 API
  version: v1
  description: 'Kia connected-car data API (Korea) published on KIA Developers: OAuth2 account APIs, consent APIs, and vehicle profile, status and warning-lamp data. GENERATED by API Evangelist from the provider documentation markdown served by developer.kia.com/api/v1/specification/contents/{group}/{api}; not a provider-published contract.'
  x-generated-from: documentation
  x-ae-authored: true
  x-last-validated: '2026-10-13'
servers:
- url: https://prd.kr-ccapi.kia.com
  description: Production (per docs)
- url: https://dev.kr-ccapi.kia.com
  description: Development (docs domain substitution)
tags:
- name: 개인정보 제공 동의 및 철회
paths:
  /api/v1/car-service/terms/agreement:
    post:
      operationId: service_agreement
      summary: 개인정보 제공 동의 요청
      description: 사용자에게 개인정보 제 3자 제공 동의 페이지를 연결하기 위한 API입니다. 사용자 동의 시, Redirect URL로 userId, state 값이 전달됩니다.
      tags:
      - 개인정보 제공 동의 및 철회
      x-docs-url: https://developer.kia.com/web/v1/kia/specification/data/service_agreement
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
                  description: Bearer {access_token}
                state:
                  type: string
                  description: 애플리케이션에서 요청한 상태 토큰 값
              required:
              - token
              - state
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  userId:
                    type: string
                    description: 당사 발급 사용자 고유 식별자
                  state:
                    type: string
                    description: 애플리케이션에서 요청한 상태 토큰 값
        4XX:
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties: {}
      security:
      - bearerAuth: []
  /api/v1/car-service/terms/reject:
    get:
      operationId: service_termreject
      summary: 개인정보 제공 철회 요청
      description: 개인정보 제3자 제공 동의 여부가 미동의 상태로 변경되었을 때, 이 정보를 Developers 서버에 업데이트하기 위한 API입니다.
      tags:
      - 개인정보 제공 동의 및 철회
      x-docs-url: https://developer.kia.com/web/v1/kia/specification/data/service_termreject
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  msgId:
                    type: string
                    description: 요청 결과 확인을 위한 메시지 ID
        4XX:
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errCode:
                    type: string
                    description: 에러 코드
                  errMsg:
                    type: string
                    description: 에러에 대한 상세 설명
                  errId:
                    type: string
                    description: 에러 ID
      security:
      - bearerAuth: []
  /api/v1/car/status/warning/{carId}/breakOil:
    get:
      operationId: statuswarning_breakoil
      summary: 브레이크 오일 경고등 상태 조회
      description: 브레이크 오일 경고등 상태를 조회하는 API입니다. 시동 종료, EV/PHEV 충전 종료 시점을 기준으로 업데이트됩니다.
      tags:
      - 개인정보 제공 동의 및 철회
      x-docs-url: https://developer.kia.com/web/v1/kia/specification/data/statuswarning_breakoil
      parameters:
      - name: carId
        in: path
        required: true
        schema:
          type: string
        description: 당사 발급 차량 고유 식별자
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    description: '브레이크 오일 경고등 상태 (true : on / false : off)'
                  msgId:
                    type: string
                    description: 요청 결과 확인을 위한 메시지 ID
        4XX:
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errCode:
                    type: string
                    description: 에러 코드
                  errMsg:
                    type: string
                    description: 에러에 대한 상세 설명
                  errId:
                    type: string
                    description: 에러 ID
      security:
      - bearerAuth: []
  /api/v1/car/status/warning/{carId}/engineOil:
    get:
      operationId: statuswarning_engineoil
      summary: 엔진 오일 경고등 상태 조회
      description: 엔진 오일 경고등 상태를 조회하는 API입니다. 시동 종료, EV/PHEV 충전 종료 시점을 기준으로 업데이트됩니다.
      tags:
      - 개인정보 제공 동의 및 철회
      x-docs-url: https://developer.kia.com/web/v1/kia/specification/data/statuswarning_engineoil
      parameters:
      - name: carId
        in: path
        required: true
        schema:
          type: string
        description: 당사 발급 차량 고유 식별자
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    description: '엔진 오일 경고등 상태 (true : on / false : off)'
                  msgId:
                    type: string
                    description: 요청 결과 확인을 위한 메시지 ID
        4XX:
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errCode:
                    type: string
                    description: 에러 코드
                  errMsg:
                    type: string
                    description: 에러에 대한 상세 설명
                  errId:
                    type: string
                    description: 에러 ID
      security:
      - bearerAuth: []
  /api/v1/car/status/warning/{carId}/lampWire:
    get:
      operationId: statuswarning_lampwire
      summary: Lamp wire 경고등 상태 조회
      description: Lamp wire 경고등 상태를 조회하는 API입니다. 시동 종료, EV/PHEV 충전 종료 시점을 기준으로 업데이트됩니다.
      tags:
      - 개인정보 제공 동의 및 철회
      x-docs-url: https://developer.kia.com/web/v1/kia/specification/data/statuswarning_lampwire
      parameters:
      - name: carId
        in: path
        required: true
        schema:
          type: string
        description: 당사 발급 차량 고유 식별자
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    description: 'Lamp wire 경고등 상태 (true : Lamp Wire ON / false : Lamp Wire OFF)'
                  msgId:
                    type: string
                    description: 요청 결과 확인을 위한 메시지 ID
        4XX:
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errCode:
                    type: string
                    description: 에러 코드
                  errMsg:
                    type: string
                    description: 에러에 대한 상세 설명
                  errId:
                    type: string
                    description: 에러 ID
      security:
      - bearerAuth: []
  /api/v1/car/status/warning/{carId}/lowFuel:
    get:
      operationId: statuswarning_lowfuellight
      summary: 주유 경고등 상태 조회
      description: 주유 경고등 상태를 조회하는 API입니다. 시동 종료 시점을 기준으로 업데이트됩니다.
      tags:
      - 개인정보 제공 동의 및 철회
      x-docs-url: https://developer.kia.com/web/v1/kia/specification/data/statuswarning_lowfuellight
      parameters:
      - name: carId
        in: path
        required: true
        schema:
          type: string
        description: 당사 발급 차량 고유 식별자
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    description: 경고등 on/off 상태
                  msgId:
                    type: string
                    description: 요청 결과 확인을 위한 메시지 ID
        4XX:
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errCode:
                    type: string
                    description: 에러 코드
                  errMsg:
                    type: string
                    description: 에러에 대한 상세 설명
                  errId:
                    type: string
                    description: 에러 ID
      security:
      - bearerAuth: []
  /api/v1/car/status/warning/{carId}/smartKeyBattery:
    get:
      operationId: statuswarning_smartkeybattery
      summary: 스마트키 배터리 상태 조회
      description: 스마트키 배터리 상태를 조회하는 API입니다. 시동 종료, EV/PHEV 충전 종료 시점을 기준으로 업데이트됩니다.
      tags:
      - 개인정보 제공 동의 및 철회
      x-docs-url: https://developer.kia.com/web/v1/kia/specification/data/statuswarning_smartkeybattery
      parameters:
      - name: carId
        in: path
        required: true
        schema:
          type: string
        description: 당사 발급 차량 고유 식별자
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    description: '스마트키 배터리 경고 상태 (true : warning voltage level / false : normal)'
                  msgId:
                    type: string
                    description: 요청 결과 확인을 위한 메시지 ID
        4XX:
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errCode:
                    type: string
                    description: 에러 코드
                  errMsg:
                    type: string
                    description: 에러에 대한 상세 설명
                  errId:
                    type: string
                    description: 에러 ID
      security:
      - bearerAuth: []
  /api/v1/car/status/warning/{carId}/tirePressure:
    get:
      operationId: statuswarning_tirepressurelamp
      summary: 타이어 공기압 경고등 상태 조회
      description: 타이어 공기압 경고등 상태를 조회하는 API입니다. 시동 종료, EV/PHEV 충전 종료 시점을 기준으로 업데이트됩니다.
      tags:
      - 개인정보 제공 동의 및 철회
      x-docs-url: https://developer.kia.com/web/v1/kia/specification/data/statuswarning_tirepressurelamp
      parameters:
      - name: carId
        in: path
        required: true
        schema:
          type: string
        description: 당사 발급 차량 고유 식별자
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    description: '타이어 공기압 경고등 상태 (true : Tire Pressure Lamp ON / false : Tire Pressure Lamp OFF)'
                  msgId:
                    type: string
                    description: 요청 결과 확인을 위한 메시지 ID
        4XX:
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errCode:
                    type: string
                    description: 에러 코드
                  errMsg:
                    type: string
                    description: 에러에 대한 상세 설명
                  errId:
                    type: string
                    description: 에러 ID
      security:
      - bearerAuth: []
  /api/v1/car/status/warning/{carId}/washerFluid:
    get:
      operationId: statuswarning_washerfluid
      summary: 워셔액 경고등 상태 조회
      description: 워셔액 경고등 상태를 조회하는 API입니다. 시동 종료, EV/PHEV 충전 종료 시점을 기준으로 업데이트됩니다.
      tags:
      - 개인정보 제공 동의 및 철회
      x-docs-url: https://developer.kia.com/web/v1/kia/specification/data/statuswarning_washerfluid
      parameters:
      - name: carId
        in: path
        required: true
        schema:
          type: string
        description: 당사 발급 차량 고유 식별자
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    description: '워셔액 경고등 상태 (true : on / false : off)'
                  msgId:
                    type: string
                    description: 요청 결과 확인을 위한 메시지 ID
        4XX:
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errCode:
                    type: string
                    description: 에러 코드
                  errMsg:
                    type: string
                    description: 에러에 대한 상세 설명
                  errId:
                    type: string
                    description: 에러 ID
      security:
      - bearerAuth: []
  /api/v1/car/profile/carlist:
    get:
      operationId: carprofile_carlist
      summary: 내 차량 리스트 조회
      description: 사용자가 소유하고 있는 차량 리스트를 조회합니다. 로그인 시점 접근 권한을 승인한 차량만 조회 가능합니다.
      tags:
      - 개인정보 제공 동의 및 철회
      x-docs-url: https://developer.kia.com/web/v1/kia/specification/data/carprofile_carlist
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  cars:
                    type: object
                    description: 차량 리스트
                    properties:
                      carId:
                        type: string
                        description: 당사 발급 차량 고유 식별자
                      carNickname:
                        type: string
                        description: 사용자가 커넥티드 서비스 앱에서 설정한 닉네임
                      carType:
                        type: string
                        description: '차량 타입 (GN:내연기관, EV:전기, HEV:하이브리드, PHEV: 플러그인하이브리드, FCEV:수소전기)'
                      carSellname:
                        type: string
                        description: 차량 판매 모델명
                  msgId:
                    type: string
                    description: 요청 결과 확인을 위한 메시지 ID
        4XX:
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errCode:
                    type: string
                    description: 에러 코드
                  errMsg:
                    type: string
                    description: 에러에 대한 상세 설명
                  errId:
                    type: string
                    description: 에러 ID
      security:
      - bearerAuth: []
  /api/v1/car/profile/{carId}/contract:
    get:
      operationId: carprofile_contract
      summary: 커넥티드 서비스 가입일/무료 종료일 조회
      description: 차량의 커넥티드 서비스(KIA Connect) 가입일과 무료 서비스 종료일 정보를 조회합니다. 2020년 기준 신차 구입 이후 최초 서비스 가입에 한해 5년 동안 무료 서비스가 제공됩니다.
      tags:
      - 개인정보 제공 동의 및 철회
      x-docs-url: https://developer.kia.com/web/v1/kia/specification/data/carprofile_contract
      parameters:
      - name: carId
        in: path
        required: true
        schema:
          type: string
        description: 당사 발급 차량 고유 식별자
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  subscribeDate:
                    type: string
                    description: 커넥티드 서비스 가입일(YYYYMMDD) (date)
                  endDate:
                    type: string
                    description: 무료 서비스 종료일(YYYYMMDD) (date)
                  msgId:
                    type: string
                    description: 요청 결과 확인을 위한 메시지 ID
        4XX:
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errCode:
                    type: string
                    description: 에러 코드
                  errMsg:
                    type: string
                    description: 에러에 대한 상세 설명
                  errId:
                    type: string
                    description: 에러 ID
      security:
      - bearerAuth: []
  /api/v1/car/status/{carId}/dte:
    get:
      operationId: status_dte
      summary: 주행 가능 거리 조회
      description: 차량의 주행 가능 거리를 조회하는 API 입니다. 시동 종료 시점을 기준으로 업데이트되며, 2개월 미운행 차량의 데이터는 조회 불가합니다.
      tags:
      - 개인정보 제공 동의 및 철회
      x-docs-url: https://developer.kia.com/web/v1/kia/specification/data/status_dte
      parameters:
      - name: carId
        in: path
        required: true
        schema:
          type: string
        description: 당사 발급 차량 고유 식별자
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    description: 차량 전송 시간(YYYYMMDDHHmmSS) (datetime)
                  value:
                    type: number
                    description: 거리 수치
                  unit:
                    type: number
                    description: '단위(0: feet, 1: km, 2: meter, 3: miles)'
                  phevTotalValue:
                    type: number
                    description: PHEV 차량의 Battery + Engine 주행가능거리 거리 수치
                  phevTotalUnit:
                    type: number
                    description: 'PHEV 차량의 Battery + Engine 주행가능거리 단위(0: feet, 1: km, 2: meter, 3: miles)'
                  msgId:
                    type: string
                    description: 요청 결과 확인을 위한 메시지 ID
        4XX:
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errCode:
                    type: string
                    description: 에러 코드
                  errMsg:
                    type: string
                    description: 에러에 대한 상세 설명
                  errId:
                    type: string
                    description: 에러 ID
      security:
      - bearerAuth: []
  /api/v1/car/status/{carId}/ev/battery:
    get:
      operationId: status_evbattery
      summary: 전기차 배터리 잔량 조회
      description: 전기차 차량의 배터리 잔량 정보를 조회하는 API입니다.
      tags:
      - 개인정보 제공 동의 및 철회
      x-docs-url: https://developer.kia.com/web/v1/kia/specification/data/status_evbattery
      parameters:
      - name: carId
        in: path
        required: true
        schema:
          type: string
        description: 당사 발급 차량 고유 식별자
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  soc:
                    type: number
                    description: '배터리 잔량(단위: %)'
                  timestamp:
                    type: string
                    description: 차량 전송 시간 (datetime)
                  msgId:
                    type: string
                    description: 요청 결과 확인을 위한 메시지 ID
        4XX:
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errCode:
                    type: string
                    description: 에러 코드
                  errMsg:
                    type: string
                    description: 에러에 대한 상세 설명
                  errId:
                    type: string
                    description: 에러 ID
      security:
      - bearerAuth: []
  /api/v1/car/status/{carId}/ev/charging:
    get:
      operationId: status_evcharging
      summary: 전기차 충전 상태 조회
      description: 전기차 차량의 충전 중 정보를 조회하는 API입니다.
      tags:
      - 개인정보 제공 동의 및 철회
      x-docs-url: https://developer.kia.com/web/v1/kia/specification/data/status_evcharging
      parameters:
      - name: carId
        in: path
        required: true
        schema:
          type: string
        description: 당사 발급 차량 고유 식별자
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  batteryPlugin:
                    type: number
                    description: '플러그 연결 여부 (0: 연결 안됨, 1: 급속 충전기 연결, 2: 일반 충전기 연결)'
                  batteryCharge:
                    type: boolean
                    description: 충전 여부
                  soc:
                    type: number
                    description: '배터리 잔량(단위: %)'
                  targetSOC:
                    type: object
                    description: 목표 충전 설정값
                    properties:
                      plugType:
                        type: number
                        description: '충전기 타입 (0 : DC charger, 1 : AC w/ 240V, 2 : AC w/ 120V)'
                      targetSOClevel:
                        type: number
                        description: 충전 목표 배터리 잔량
                  remainTime:
                    type: object
                    description: '목표 충전까지 남은 시간 -충전 연결 상태: 잔여 충전 시간 - 충전 미연결 상태: 240V 충전 시 잔여 충전 시간'
                    properties:
                      value:
                        type: number
                        description: 시간 간격 수치
                      unit:
                        type: number
                        description: '단위 (0: hour, 1: min, 2: msec, 3: sec)'
                  timestamp:
                    type: string
                    description: 차량 전송 시간 (datetime)
                  msgId:
                    type: string
                    description: 요청 결과 확인을 위한 메시지 ID
        4XX:
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errCode:
                    type: string
                    description: 에러 코드
                  errMsg:
                    type: string
                    description: 에러에 대한 상세 설명
                  errId:
                    type: string
                    description: 에러 ID
      security:
      - bearerAuth: []
  /api/v1/car/status/{carId}/odometer:
    get:
      operationId: status_odometer
      summary: 누적 운행 거리 조회
      description: 차량의 누적 운행 거리를 조회하는 API 입니다. 시동 종료 시점을 기준으로 업데이트됩니다.
      tags:
      - 개인정보 제공 동의 및 철회
      x-docs-url: https://developer.kia.com/web/v1/kia/specification/data/status_odometer
      parameters:
      - name: carId
        in: path
        required: true
        schema:
          type: string
        description: 당사 발급 차량 고유 식별자
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  odometers:
                    type: object
                    description: 누적 운행 거리
                    properties:
                      date:
                        type: string
                        description: 조회일자(YYYYMMDD) (date)
                      timestamp:
                        type: string
                        description: 차량 전송 시간(YYYYMMDDHHmmSS) (datetime)
                      value:
                        type: number
                        description: 거리 수치 (소수점 절사)
                      unit:
                        type: number
                        description: '단위 (0: feet, 1: km, 2: meter, 3: miles)'
                  msgId:
                    type: string
                    description: 요청 결과 확인을 위한 메시지 ID
        4XX:
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errCode:
                    type: string
                    description: 에러 코드
                  errMsg:
                    type: string
                    description: 에러에 대한 상세 설명
                  errId:
                    type: string
                    description: 에러 ID
      security:
      - bearerAuth: []
webhooks:
  partner_deletecallback:
    post:
      operationId: partner_deletecallback
      summary: 데이터 조회 불가 상태 알림
      description: 디지털키 서비스 예약결과 전달 또는 커넥티드 서비스 해지, 차량 삭제, 제3자 제공 동의 철회 등 고객 요청에 의한 예약 결과값이나 요청에 의해 데이터를 더 이상 제공할 수 없는 경우, 이 정보를 전달받기 위한 규격입니다 Callback URL은 '설정 - 데이터 API' 페이지에서 등록 가능합니다. 개인정보보호법 및 개인정보보호법시행령에 따라 해당 알림을 받은 즉시, API를 통해 제공된 데이터를 일괄 삭제하고 서비스에서 지속 표출되지 않도록 조치해야 합니다.
      tags:
      - 개인정보 제공 동의 및 철회
      x-docs-url: https://developer.kia.com/web/v1/kia/specification/data/partner_deletecallback
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: 알림 대상 (account, vehicle, agreement)
                  action:
                    type: string
                    description: callback event (delete, reject)
                  userId:
                    type: string
                    description: 당사 발급 사용자 고유 식별자
                  carId:
                    type: string
                    description: 당사 발급 차량 고유 식별자
                  vin:
                    type: string
                    description: VIN(차대번호) VIN(차대번호) 데이터 접근 권한이 있는 서비스에 한하여 제공
        4XX:
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties: {}
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Access token from /api/v1/user/oauth2/token
externalDocs:
  url: https://developer.kia.com/web/v1/kia/specification/account