[GET] 계약 정산 정보 조회 API

엔터프라이즈 플랜에서만 지원하는 기능입니다.

요청하신 시점을 기준으로 활성화된 계약에 관하여 정산 정보를 조회합니다.

Request

GET https://admin-api.hackle.io/v1/contracts/settlements

X-HACKLE-ADMIN-API-KEY를 통해 인증을 진행합니다. 해당 키를 HTTP 헤더로 전송해야 합니다.

X-HACKLE-ADMIN-API-KEY: {X-HACKLE-ADMIN-API-KEY}

Example

curl -i -X GET \
  'https://admin-api.hackle.io/v1/contracts/settlements' \
  -H 'X-HACKLE-ADMIN-API-KEY: X-HACKLE-ADMIN-API-KEY_HERE' \
  -H 'Content-Type: application/json'

---

Response

200 OK

성공적인 요청인 경우 200 응답과 조회 결과를 반환합니다.

용어 설명

용어	설명
계약 그룹 (ContractGroup)	하나 이상의 계약을 묶는 단위입니다. 같은 기간 안에 서로 다른 계약이 묶이는 경우 계약 그룹 단위로 관리됩니다.
계약 (Contract)	실제 계약서에 대응하는 단위입니다. 계약 금액(originalAmount)이 설정되어 있습니다. 하나의 계약에 여러 워크스페이스가 매핑될 수 있습니다.
선차감 금액(priorDeductionAmount)	현재 정산과 무관한 사유로 계약 금액에서 미리 차감된 금액입니다. 이전 계약의 초과 사용분 이월 CRM 사용을 위한 캐시 충전 등 음수인 경우 이전 계약의 잔액이 이월되어 사용 가능 금액이 계약 금액보다 많은 상태를 의미합니다.
정산 (Settlement)	일 단위로 생성되는 사용량 기반 정산 스냅샷입니다. 각 워크스페이스와 이벤트 카테고리 조합별로 사용량과 금액이 계산됩니다.
계산 금액 (calculatedAmount)	사용량 * 단가로 산출된 금액입니다. 크레딧, 프로모션 등 무료 차감 전 원래 금액을 의미합니다.
실 정산 금액 (settledAmount)	크레딧, 프로모션 등 차감 혜택을 적용한 후 실제로 정산되는 금액입니다.
차감 출처 (deductionSource)	해당 정산 항목의 금액이 어디서 차감되는지를 나타냅니다. 계약 자체, 크레딧, 프로모션 등 다양한 출처가 있습니다.

이벤트 카테고리

정산은 이벤트 카테고리별 사용량을 집계합니다. 이벤트 카테고리는 건당 단가를 구분하는 기준이 되며, 카테고리에 따라 서로 다른 단가가 적용됩니다. 각 카테고리의 의미는 다음과 같습니다.

카테고리	설명	포함 이벤트
AB	A/B 테스트 이벤트	A/B 테스트 실험 노출
FF	기능플래그 이벤트	기능 플래그 기능 노출
RC	원격 구성 이벤트	원격구성 요청
CUSTOM_TRACK	사용자 정의 이벤트	고객이 직접 전송하는 사용자 정의 이벤트
SYSTEM_TRACK	자동 수집 이벤트 (CRM 제외 이벤트)	https://docs.hackle.io/event-management/hackle-event
CRM_SYSTEM_TRACK	자동수집 이벤트 (CRM 이벤트)	https://docs.hackle.io/event-management/hackle-event
IMPORT	데이터 import 이벤트

Response Body

Field	Type	Nullable	Description
contractGroupSettlements	List(ContractGroupSettlement)	X	계약 정산 내역 리스트

ContractGroupSettlement

Field	Type	Nullable	Description
contractGroupName	String	X	계약 그룹명
startDate	String(date)	X	계약 그룹 시작일
endDate	String(date)	X	계약 그룹 종료일
contracts	List(Contract)	X	계약 그룹에 속한 계약 목록
settlement	Settlement	O	정산 정보

Contract

Field	Type	Nullable	Description
contractName	String	X	계약명
startDate	string(date)	X	계약 시작일
endDate	string(date)	X	계약 종료일
originalAmount	BigDecimal	X	계약 금액 (계약서상 금액)
priorDeductionAmount	BigDecimal	X	선차감 금액

Settlement

Field	Type	Nullable	Description
snapshotDate	string(date)	X	정산 기준일
totalCalculatedAmount	BigDecimal	X	전체 계산 금액 합계
totalSettledAmount	BigDecimal	X	실 정산 금액 합계
items	List(Settlement.item)	X	워크스페이스 * 이벤트 별 정산 상세 목록

Settlement.item

Field	Type	Nullable	Description
workspaceName	String	X	워크스페이스 이름
eventCategoryName	String	X	이벤트 카테고리명
usageCount	Long	X	사용량 (건수)
unitPrice	BigDecimal	X	건당 단가
calculatedAmount	BigDecimal	X	계산 금액 (usageCount * unitPrice)
deductionSource	String	X	차감 출처 표시명
settledAmount	BigDecimal	X	실 정산 금액 (무료 차감 제외)
startDate	string(date)	X	정산 적용 시작일

Example

{
  "contractGroupSettlements": [
    {
      "contractGroupName": "핵클_2026년 계약",
      "startDate": "2026-01-01",
      "endDate": "2026-12-31",
      "contracts": [
        {
          "contractName": "2026년 계약",
          "startDate": "2026-01-01",
          "endDate": "2026-12-31",
          "originalAmount": 50000000.0,
          "priorDeductionAmount": 5000000.0
        }
      ],
      "settlement": {
        "snapshotDate": "2026-06-29",
        "totalCalculatedAmount": 12000000.0,
        "totalSettledAmount": 7000000.0,
        "items": [
          {
            "workspaceName": "핵클 워크스페이스",
            "eventCategoryName": "AB",
            "usageCount": 5000000,
            "unitPrice": 0.12,
            "calculatedAmount": 600000.0,
            "deductionSource": "2026년 계약_크레딧_3,000,000원",
            "settledAmount": 0.0,
            "startDate": "2026-01-01"
          },
          {
            "workspaceName": "핵클 워크스페이스",
            "eventCategoryName": "FF",
            "usageCount": 8000000,
            "unitPrice": 0.05,
            "calculatedAmount": 400000.0,
            "deductionSource": "2026년 계약_프로모션_5,000,000원",
            "settledAmount": 0.0,
            "startDate": "2026-01-01"
          },
          {
            "workspaceName": "핵클 워크스페이스",
            "eventCategoryName": "CUSTOM_TRACK",
            "usageCount": 50000000,
            "unitPrice": 0.12,
            "calculatedAmount": 6000000.0,
            "deductionSource": "2026년 계약",
            "settledAmount": 6000000.0,
            "startDate": "2026-01-01"
          },
          {
            "workspaceName": "핵클 워크스페이스",
            "eventCategoryName": "SYSTEM_TRACK",
            "usageCount": 50000000,
            "unitPrice": 0.1,
            "calculatedAmount": 5000000.0,
            "deductionSource": "2026년 계약",
            "settledAmount": 1000000.0,
            "startDate": "2026-01-01"
          }
        ]
      }
    }
  ]
}

400 Bad Request

유효하지 않은 요청 정보인 경우 400 상태를 반환합니다.

Response Body

{
    "code": "BAD_REQUEST",
    "message": "Bad Request"
}

401 Unauthorized

X-HACKLE-ADMIN-API-KEY 헤더값이 없거나 유효하지 않은 키인 경우 401 상태를 반환합니다.

{
    "code": "UNAUTHORIZED",
    "message": "Unauthorized"
}

403 Forbidden

권한이 없는 API를 호출할 경우 403 상태를 반환합니다.

{
    "code": "FORBIDDEN",
    "message": "Forbidden"
}