콘텐츠로 이동

청구 정보 조회



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를 보존하여 관리자에게 문의하고 업스트림 응답을 확인한 후, 나중에 다시 조회하여 재시도하십시오.

문서 평가

이 페이지가 도움이 되었나요?