이용기관 관리

이 문서는 카카오톡 인증 서비스의 이용기관 관리 API 사용 방법을 안내합니다.

기능 소개

이용기관 관리 API는 딜러사의 이용기관 관리를 위한 기능을 제공합니다.

이용기관 정보 조회
서명 상태별 건수 조회

이용기관 등록 및 관리 방식

이용기관과 상품 계약 등록은 기존의 파트너 아지트에서 등록 요청 방식을 유지합니다. 이용기관 등록 및 관리 API는 추후 제공 예정입니다.

이용기관 등록 및 관리 과정

이용기관 등록 및 관리

시작하기 전에

딜러사 앱 키 확인

이용기관 관리 API는 딜러사 앱의 어드민(Admin) 키를 사용해 호출합니다. 기존에 등록된 앱이 있는 경우, 해당 앱의 어드민 키를 사용합니다. 아직 등록된 앱이 없다면 앱 관리 페이지에서 딜러사의 앱을 생성합니다. 앱의 어드민 키는 앱 관리 페이지의 [앱] > [어드민 키]에서 확인할 수 있습니다. 어드민 키를 참고합니다.

사용 권한 신청

이용기관 관리 API는 사용 권한이 있는 딜러사 앱에서만 사용할 수 있습니다. 아래 안내에 따라 사용 권한을 신청합니다.

파트너 아지트의 [딜러사 등록] 글양식으로 딜러사 등록을 신청합니다.
딜러사 등록이 완료되면 계약 내용이 포함된 시스템 메일이 발송됩니다.
시스템 메일 수신 후, 딜러사 앱의 어드민 키를 사용해 이용기관 관리 API를 호출할 수 있습니다.

이용기관 정보 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://sign-contract.kakao.com/dealer-api/cert/v1/partners`	딜러사 앱 어드민 키

권한	사전 설정	카카오 로그인	동의항목
필요	어드민 키	-	-

특정 사업자등록번호로 등록된 모든 이용기관 정보를 조회합니다.

딜러사가 직접 등록한 이용기관의 정보만 조회할 수 있습니다.

헤더(Header)에 딜러사 앱 어드민 키를 담아 GET으로 요청합니다. 이용기관 정보를 조회할 사업자등록번호를 쿼리 문자열(Query string)로 전달해야 합니다.

요청 성공 시 응답은 사업자등록번호에 해당하는 이용기관 정보 목록의 JSON 객체입니다. 각 이용기관 정보는 정산 ID(settle_id)별 계약 정보를 포함합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DEALER_ADMIN_KEY}` 인증 방식, 서비스 앱에서 딜러사 어드민 키로 인증 요청	O

쿼리 파라미터

이름	타입	설명	필수
business_number	`String`	사업자등록번호	O

응답

본문

이름	타입	설명	필수
data	`PartnerData`	이용기관 정보	X
error	`String`	에러 코드	X
error_description	`String`	에러 문구	X
error_detail	`String`	에러 상세	X

PartnerData

이름	타입	설명	필수
dealer_name	`String`	담당 딜러사명	O
partner_list	`Partner[]`	이용기관 정보 목록	O

Partner

이름	타입	설명	필수
company_name	`String`	이용기관 회사명(상호, 법인 또는 단체명)	O
business_number	`String`	이용기관 사업자등록번호	O
app_id	`Long`	이용기관 앱 ID	O
ci_permission	`Boolean`	이용기관 앱의 CI 제공 권한 보유 여부 `true`: 보유 `false`: 미보유	O
use_partner_channel	`Boolean`	카카오톡 인증 서비스 이용 시, 파트너 채널(이용기관의 카카오톡 채널) 사용 여부 `true`: 사용 `false`: 미사용 (기본값: `false`)	O
partner_channel_url	`String`	파트너 채널 URL 중요: `use_partner_channel`이 `true`인 경우에만 제공	X
cs_center_type	`String`	이용기관 고객센터 유형, 아래 중 하나 `PHONE_NUMBER`: 전화번호 `PARTNER_CHANNEL`: 파트너 채널	O
cs_center_phone_number	`String`	이용기관의 고객센터 전화번호 중요: `cs_center_type`이 `PHONE_NUMBER`인 경우에만 제공	X
cs_center_channel_url	`String`	이용기관의 고객센터 카카오톡 채널 URL 중요: `cs_center_type`이 `PARTNER_CHANNEL`인 경우에만 제공	X
request_organization_name	`String`	사용자 인증 요청 안내문에 노출되는 요청기관명	O
dev_ips	`String[]`	이용기관 서비스의 개발 서버 IP 목록	X
real_ips	`String[]`	이용기관 서비스의 운영 서버 IP 목록	X
settle_list	`SettleInfo[]`	이용기관의 정산 정보	O

SettleInfo

이름	타입	설명	필수
id	`String`	정산 ID	O
ci_permission	`Boolean`	CI 수집 화면 노출 여부	O
test	`Boolean`	테스트용 정산 ID인지 여부 `true`: 테스트용 `false`: 운영용	O
contract_list	`ContractInfo[]`	계약 정보	O

ContractInfo

이름	타입	설명	필수
product_code	`String`	상품 코드	O
started_at	`String`	계약 시작 일자 `YYYY-MM-DD` 형식	O
finished_at	`String`	계약 종료 일자 `YYYY-MM-DD` 형식	O
status	`String`	계약 상태, 아래 중 하나 `READY`: 이용 대기 `USE`: 이용 중 `STOP`: 이용 정지 `FINISH`: 만료	O

예제

요청

curl -v -G GET "https://sign-contract.kakao.com/dealer-api/cert/v1/partners?business_number=${BUSINESS_NUMBER}" \
  -H "Authorization: KakaoAK ${DEALER_APP_ADMIN_KEY}"

응답

{
  "data": {
    "dealer_name": "담당 딜러사명",
    "partner_list": [
      {
        "company_name": "이용기관 회사명",
        "business_number": "123-45-67890",
        "app_id": 123456,
        "ci_permission": false,
        "use_partner_channel": false,
        "cs_center_type": "PHONE_NUMBER",
        "cs_center_phone_number": "02-0000-0000",
        "request_organization_name": "이용기관 서비스명",
        "dev_ips": ["127.0.0.1"],
        "real_ips": ["1.1.1.1"],
        "settle_list": [
          {
            "id": "${SETTLE_ID}",
            "ci_permission": false,
            "test": false,
            "contract_list": [
              {
                "product_code": "K1120",
                "started_at": "2023-01-09",
                "finished_at": "2023-01-10",
                "status": "USE"
              }
            ]
          },
          {
            "id": "${SETTLE_ID}",
            "ci_permission": false,
            "test": false,
            "contract_list": [
              {
                "product_code": "K1120",
                "started_at": "2022-12-21",
                "finished_at": "2022-12-29",
                "status": "FINISH"
              },
              {
                "product_code": "K2100",
                "started_at": "2023-01-04",
                "finished_at": "2023-01-06",
                "status": "FINISH"
              },
              {
                "product_code": "K2100",
                "started_at": "2023-01-07",
                "finished_at": "2024-01-06",
                "status": "USE"
              },
              {
                "product_code": "K3511",
                "started_at": "2022-12-21",
                "finished_at": "2023-01-31",
                "status": "USE"
              }
            ]
          },
          {
            "id": "${SETTLE_ID}",
            "ci_permission": false,
            "test": true,
            "contract_list": [
              {
                "product_code": "K1110T",
                "started_at": "2022-12-20",
                "finished_at": "2022-12-21",
                "status": "FINISH"
              },
              {
                "product_code": "K1110T",
                "started_at": "2022-12-22",
                "finished_at": "2022-12-23",
                "status": "FINISH"
              },
              {
                "product_code": "K1110T",
                "started_at": "2022-12-26",
                "finished_at": "2022-12-30",
                "status": "FINISH"
              },
              {
                "product_code": "K1110T",
                "started_at": "2022-12-31",
                "finished_at": "2023-12-30",
                "status": "USE"
              }
            ]
          }
        ]
      }
    ]
  }
}

서명 상태별 건수 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://sign-contract.kakao.com/dealer-api/cert/v1/usages`	딜러사 앱 어드민 키

권한	사전 설정	카카오 로그인	동의항목
필요	어드민 키	-	-

특정 이용기관의 정산에 필요한 서명 상태별 건수를 조회합니다.

요청일로부터 1일 전(D-1)까지의 정보를 일 단위로 조회할 수 있습니다. 실시간 집계 정보는 제공하지 않습니다.

헤더(Header)에 딜러사 앱 어드민 키를 담아 GET으로 요청합니다. 조회 일자(date)과 함께 아래 중 한 가지의 조회 조건을 쿼리 문자열(Query string)로 전달해야 합니다.

앱 ID(app_id)
정산 ID(settle_id)
앱 ID와 정산 ID

요청 성공 시 응답은 조회 일자의 서명 상태별 건수를 담은 JSON 객체입니다. 서명 상태별 건수는 정산 ID, 상품 코드별로 취합되어 제공됩니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DEALER_ADMIN_KEY}` 인증 방식, 서비스 앱에서 딜러사 어드민 키로 인증 요청	O

쿼리 파라미터

이름	타입	설명	필수
date	`String`	조회 일자, `YYYY-MM-DD` 형식	O
app_id	`Long`	이용기관 앱 ID	O(Optional)
settle_id	`String`	정산 ID	O(Optional)
product_code	`String`	상품 코드(기본값: 전체)	X

응답

본문

이름	타입	설명	필수
data	`UsageData`	서명 상태별 건수 조회 결과	X
error	`String`	에러 코드	X
error_description	`String`	에러 문구	X
error_detail	`String`	에러 상세	X

UsageData

이름	타입	설명	필수
partner_company_name	`String`	이용기관 회사명(상호, 법인 또는 단체명)	O
settle_list	`SettleUsage[]`	정산 정보 목록	O

SettleUsage

이름	타입	설명	필수
settle_id	`String`	정산 ID	O
product_list	`Product[]`	상품별 정산 정보 목록	O

Product

이름	타입	설명	필수
product_code	`String`	상품 코드	O
price	`Integer`	제공 단가	O
charging_status	`String`	정산 기준 상태값, 아래 중 하나 `REQUEST`: 서명 요청 `SIGN`: 서명 완료	O
usage_count_list	`Usage[]`	서명 상태별 건수	O

Usage

이름	타입	설명	필수
status	`String`	서명 상태, 아래 중 하나 `REQUEST`: 서명 요청 `SIGN`: 서명 완료	O
count	`Long`	조회된 건수	O

예제

요청

curl -v -G GET "https://sign-contract.kakao.com/dealer-api/cert/v1/usages?date=2023-01-05&app_id=${APP_ID}" \
  -H "Authorization: KakaoAK ${DEALER_APP_ADMIN_KEY}"

응답: 성공

{
  "data": {
    "partner_company_name": "이용기관 회사명",
    "settle_list": [
      {
        "settle_id": "${SETTLE_ID}",
        "product_list": [
          {
            "product_code": "K1120",
            "price": 10,
            "charging_status": "SIGN",
            "usage_count_list": [
              {
                "status": "REQUEST",
                "count": 0
              },
              {
                "status": "SIGN",
                "count": 0
              }
            ]
          },
          {
            "product_code": "K2100",
            "price": 15,
            "charging_status": "SIGN",
            "usage_count_list": [
              {
                "status": "REQUEST",
                "count": 0
              },
              {
                "status": "SIGN",
                "count": 0
              }
            ]
          }
        ]
      }
    ]
  }
}

응답: 실패, date가 오늘 또는 오늘 이후인 경우

// HTTP/1.1 400
{
  "error": "CDE40001",
  "error_description": "invalid request parameter value",
  "error_detail": "date should be less than 2023-02-10"
}

응답: 실패, app_id와 settle_id 중 하나도 주어지지 않은 경우

// HTTP/1.1 400
{
  "error": "CDE40000",
  "error_description": "invalid request format",
  "error_detail": "either app_id or settle_id should not be null"
}

에러 코드

이 외에 에러 코드는 공통 에러 코드를 참고합니다.

`error`	`error_description`	`error_detail`	설명	HTTP 상태 코드
`CDE40000`	`invalid request format`	`-`	필수 파라미터가 누락되었거나, 요청값의 형식이 올바르지 않은 경우	400
`CDE40000`	`invalid request format`	`either app_id or settle_id should not be null`	필수 파라미터인 `app_id`와 `settle_id` 중 한 가지도 요청에 포함하지 않은 경우	400
`CDE40001`	`invalid request parameter value`	`date should be less than ${DATE}`	서명 상태별 건수 조회 요청 시, 조회 불가능한 기간에 대해 요청한 경우	400
`CDE40100`	`failed to authenticate`	`-`	헤더의 인증 정보가 올바르지 않아 딜러사 인증에 실패한 경우	401
`CDE40300`	`not allowed client ip`	`request ip: ${IP}`	요청한 IP가 카카오톡 인증 서비스 서버의 접근제어목록(Access Control List, ACL)에 등록되어있지 않은 경우 (파트너 아지트에서 이용기관 IP 등록 요청 필요)	403
`CDE40301`	`not allowed client ip`	`request ip: ${IP}`	요청한 IP가 카카오디벨로퍼스 앱에 등록돼 있지 않은 경우 (참고: 호출 허용 IP 주소)	403
`CDE40400`	`request url does not exists`	`-`	요청한 API가 존재하지 않는 경우	404
`CDE40402`	`partner does not exists`	`-`	심사 승인된 이용기관이 존재하지 않거나, 해당 이용기관에 대한 요청 권한이 없는 경우	404
`CDE50000`	`internal server error`	`-`	서버나 네트워크 이슈가 발생한 경우	500

사이드 메뉴

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

카카오맵

내비게이션

광고

검색

더 보기

이용기관 관리

기능 소개

이용기관 등록 및 관리 과정

시작하기 전에

딜러사 앱 키 확인

사용 권한 신청

이용기관 정보 조회

기본 정보

요청

헤더

쿼리 파라미터

응답

본문

PartnerData

Partner

SettleInfo

ContractInfo

예제

요청

응답

서명 상태별 건수 조회

기본 정보

요청

헤더

쿼리 파라미터

응답

본문

UsageData

SettleUsage

Product

Usage

예제

요청

응답: 성공

응답: 실패, date가 오늘 또는 오늘 이후인 경우

응답: 실패, app_id와 settle_id 중 하나도 주어지지 않은 경우

에러 코드

더 보기

도움이 되었나요?

이용기관 관리