청구 정보 조회¶
GET /api/v1/billing/detail/list
개요¶
날짜별로 현재 워크스페이스의 청구 센터 청구 내역을 조회합니다.
호출 전 및 사용 단계¶
대상 워크스페이스의 API Key를 사용합니다. Key가 속한 워크스페이스에 대응하는 청구 센터 사이트의 데이터만 읽을 수 있으며, 추가 workspaceUUID/brandKey/사이트 매개변수로 전환할 수 없습니다. 인터페이스는 과금, 충전, 정산 또는 요금제 수정을 수행하지 않습니다. 청구 센터 데이터에는 생성 또는 정산 지연이 있을 수 있으며, 빈 결과가 소비가 발생하지 않았음을 의미하지 않습니다. 실제 청구 기간과 청구 센터를 함께 확인하십시오. 금액, 통화, 정밀도 및 집계 기준은 해당 워크스페이스의 청구 센터를 따르며, Studio는 환산하거나 통화 필드를 보완하지 않습니다. 예시 값을 가격으로 간주해서는 안 됩니다.
billing.billingRead 또는 billing.workspaceUpgrade 중 하나의 권한이 필요합니다. startDate/endDate는 각각 생략 시 Studio 서버의 당일(로컬 date.today)이 기본값이며, 워크스페이스 시간대나 브라우저 시간대가 아닙니다. 항상 동일한 형식의 시작일과 종료일을 함께 명시적으로 제출하는 것이 좋습니다. 페이징 매개변수가 없으며, pageSize/date/billingKey 등의 매개변수를 임의로 추가할 수 없습니다.
공개 검증은 문자열만 요구하며 실제 날짜, 8자리 형식 또는 선후 순서를 검증하지 않습니다. 청구 센터가 최종 수락/거부와 경계 기준을 담당하며, Studio가 날짜를 자동으로 교환, 정규화 또는 보완한다고 보장할 수 없습니다. 명시적 빈 문자열은 생략과 다릅니다. SDK는 두 값이 모두 비어 있지 않을 때만 시작일과 종료일을 업스트림으로 전송하며, 둘 중 하나라도 빈 값이면 날짜 범위 전체를 전송하지 않습니다. 빈 값으로 과거 청구 기간을 요청하지 마십시오.
요청 헤더¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Query 요청 매개변수¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| endDate | string | 선택적 문자열입니다. 생략 시 서버의 당일이 기본값이며, 빈 값이면 SDK가 전체 날짜 범위를 전달하지 않습니다. Studio는 선후 순서를 검증하지 않습니다. null 허용: False 예시: 20260731가져오기 또는 입력 방법: 대상 종료일을 선택하며, startDate보다 이르지 않게 지정하는 것이 좋습니다. 범위 경계는 청구 센터를 따릅니다. |
|
| startDate | string | 선택적 문자열입니다. 생략 시 서버의 당일이 기본값입니다. 빈 문자열에는 기본 날짜가 적용되지 않으며, 공개 선언에는 형식 정규식이 없습니다. null 허용: False 예시: 20260730가져오기 또는 입력 방법: 대상 청구 기간에 따라 YYYYMMDD 날짜를 선택하며, endDate와 함께 명시적으로 입력하는 것이 좋습니다. |
매개변수 추가 설명¶
청구 센터 상세 목록을 반환합니다. 필드 표와 예시는 업스트림의 실제 구조에 따라 설명합니다. 제품 식별자, 필드 유형 및 빈 값은 Studio가 브랜드 표시명으로 대체하거나 기본값을 보완하지 않습니다.
요청 예시¶
curl --get 'https://openapi.guance.com/api/v1/billing/detail/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode startDate=20260730 \
--data-urlencode endDate=20260731
응답¶
HTTP 200, application/json. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | array 또는 object | 청구 센터 청구 내역 목록이 그대로 반환되며, 예시의 각 항목은 객체입니다. 빈 배열일 수 있습니다. 업스트림에 content가 없으면 SDK는 빈 객체 {}로 폴백하며, Studio의 페이징 래핑은 없습니다. |
| content[] | object | 하나의 청구 상세 항목입니다. 필드는 청구 센터에서 제공되며, 모든 필드가 각 항목에 항상 존재한다고 보장하지 않습니다. |
| content[].consumeTimeOfDay | JSON | 소비 날짜이며 예시는 YYYY-MM-DD이고 호출 시각이 아닙니다. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].orgName | JSON | 청구 센터 조직 이름이며 워크스페이스 UUID가 아닙니다. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].productName | JSON | 업스트림 제품 식별자/이름이며, 고정된 브랜드 표시명으로 가정할 수 없고 실제 반환 값을 재작성하지 않습니다. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].productDetail | JSON | 과금 항목 표시 이름입니다. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].billingKey | JSON | 과금 카테고리 식별자이며, 일부 과거 응답에는 tag6만 있을 수 있습니다. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].billingCycle | JSON | 정산 주기 표시이며, 예: Day/Month/Year/Single. 실제 반환 값에 따라 처리합니다. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].billingResult | JSON | 결제 예정 금액이며 청구 센터 기준입니다. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].deductionAmount | JSON | 차감 금액입니다. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].oweAmount | JSON | 미납 금액입니다. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].originAmount | JSON | 정가 금액입니다. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].serviceBillingAmount | JSON | 서비스 요금 금액입니다. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].couponAmount | JSON | 바우처 차감 금액입니다. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].storedCardAmount | JSON | 충전식 카드 차감 금액입니다. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].cashAmount | JSON | 현금 차감 금액입니다. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].cashCouldAmount | JSON | 클라우드 마켓 차감 금액이며, 과거 필드 철자를 유지합니다. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].commodityCategory | JSON | 제품 유형/과금 모델이며 업스트림에서 정의합니다. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].consumePlatform | JSON | 정산 채널 표시입니다. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].customerIdentifier | JSON | 클라우드 마켓 고객 식별자이며, 다른 API에 사용할 수 있는 자격 증명이 아닙니다. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].consumption | JSON | 업스트림 소비 부가 정보이며 Studio는 가공하지 않습니다. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].workspaceUuid | JSON | 소비가 귀속된 워크스페이스 식별자입니다. 필드의 소문자 uid 철자가 workspaceUUID와 다르다는 점에 유의하십시오. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].workspaceName | JSON | 소비가 귀속된 워크스페이스 이름입니다. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].consumeTime | JSON | 소비 시간이며 유형과 단위는 업스트림에서 결정합니다. 고정 초 타임스탬프로 간주하지 마십시오. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].billingResultDetails | JSON | 청구 센터의 추가 과금 상세입니다. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].count | JSON | 사용량이며 단위는 과금 항목에 따라 달라지고, 과금 항목 간에 직접 합산할 수 없습니다. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].tag6 | JSON | 과거 과금 항목 식별자이며, 예: session_replay. 과거 빈 값은 null, 빈 문자열 또는 리터럴 문자열 None일 수 있으므로 실제 유형에 따라 처리해야 합니다. |
| content[].declaration | object | 객체 목록을 직접 반환할 때 비어 있지 않은 행에 추가되는 워크스페이스 선언입니다. |
{
"code": 200,
"content": [
{
"consumeTimeOfDay": "2023-07-31",
"orgName": "None",
"productName": "None",
"productDetail": "Session Replay",
"billingCycle": "None",
"billingResult": 0,
"deductionAmount": "None",
"oweAmount": "None",
"originAmount": 0,
"serviceBillingAmount": "None",
"couponAmount": "None",
"storedCardAmount": "None",
"cashAmount": "None",
"cashCouldAmount": "None",
"commodityCategory": "None",
"consumePlatform": "None",
"customerIdentifier": "None",
"consumption": "None",
"workspaceUuid": "None",
"workspaceName": "None",
"consumeTime": "None",
"tag6": "session_replay",
"billingResultDetails": "None",
"count": 0,
"declaration": {}
}
],
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
청구 센터 SDK는 먼저 ft.CloudCareApiError로 매핑하고 업스트림 HTTP/비즈니스 code로 덮어씁니다. 해당 SDK에는 패스스루 플래그가 설정되어 있지 않으므로 최종 code가 500 이상이면 HTTP500, ft.InternalServerError 및 일반 텍스트로 전역 래핑되며, 외부에 503 또는 원본 5xx 메시지가 유지된다고 가정할 수 없습니다. 최종 code가 500 미만이면 CloudCareApiError와 실제 message를 유지합니다. 연결 예외는 기본적으로 400입니다. 여기서는 확인된 Studio 매핑만 나열하며, 청구 센터의 각 비즈니스 오류나 프록시 오류를 모두 열거하지는 않습니다.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 선언되지 않은 Query 매개변수를 사용했거나 매개변수가 규칙을 위반함 | 매개변수 파싱 실패 | Query 매개변수 표 및 예시를 확인하십시오. |
| 404 | ft.ObjectNotExists | 현재 Key에 해당하는 워크스페이스 레코드를 찾을 수 없음 | 지정한 객체가 존재하지 않음 | 대상 워크스페이스와 Key의 유효 상태를 확인하십시오. |
| 406 | ft.InvalidBossNode | 워크스페이스에 바인딩된 청구 센터 브랜드/노드가 구성되지 않았거나 사용할 수 없음 | 유효하지 않은 Boss 노드 | 관리자에게 문의하여 워크스페이스 청구 센터 바인딩과 사이트 설정을 점검하고, 날짜 변경으로 우회하지 마십시오. |
| 400 | ft.CloudCareApiError | 청구 센터 요청 연결 실패(기본 400) 또는 매핑 후 code가 500 미만인 업스트림 HTTP/비즈니스 오류 | 내부 인터페이스 호출 실패 | HTTP, message 및 traceId를 보존하고 청구 센터 가용성과 구체적인 오류를 확인하십시오. 최종 4xx는 달라질 수 있으며, code가 500 이상이면 전역적으로 ft.InternalServerError로 래핑됩니다. |
| 500 | ft.InternalServerError | 청구 센터가 예상하지 못한 유형/누락 필드, 유효하지 않은 JSON 또는 기타 저장 및 형식 지정 오류를 반환함 | 내부 오류 | traceId를 보존하여 관리자에게 문의하고 업스트림 응답을 확인한 후, 나중에 다시 조회하여 재시도하십시오. |