콘텐츠로 이동

계정 잔액 조회



GET /api/v1/billing/balance/get

개요

현재 워크스페이스에 해당하는 청구 센터 계정의 세 가지 잔액을 조회합니다.

호출 전 준비 및 사용 단계

대상 워크스페이스의 API Key를 사용합니다. Key가 속한 워크스페이스에 대응하는 청구 센터 사이트의 데이터만 조회할 수 있으며, 추가 workspaceUUID/brandKey/사이트 파라미터로 전환할 수 없습니다. 이 인터페이스는 과금, 충전, 정산 또는 요금제 변경을 수행하지 않습니다. 청구 센터 데이터에는 생성 또는 정산 지연이 있을 수 있으므로, 빈 결과가 소비가 발생하지 않았음을 의미하지는 않습니다. 실제 청구 기간과 청구 센터를 함께 확인하십시오. 금액, 통화, 정밀도 및 집계 기준은 해당 워크스페이스의 청구 센터를 따르며, Studio는 환산하거나 통화 필드를 보완하지 않으므로 예시 수치를 가격으로 간주해서는 안 됩니다.

billing.billingRead, billing.billingWrite 또는 billing.workspaceUpgrade 중 하나의 권한이 필요합니다. 비즈니스 동작을 제어할 수 있는 Query 파라미터는 없으며, workspaceUUID/accountUUID 또는 청구 기간으로 조회 대상을 전환할 수 없습니다. 추가 Query는 무시되며 워크스페이스나 청구 기간을 변경하지 않습니다. 잔액은 청구 센터 계정에 귀속되므로 이를 근거로 다른 워크스페이스의 소비 한도를 추론해서는 안 됩니다. Studio는 청구 센터 잔액 결과에서 cashBalance/couponBalance/storedCardBalance 세 키만 추출하며, 그 외 업스트림 필드는 자동으로 노출되지 않습니다. 청구 센터에서 어느 한 키가 누락되면 0으로 보정하지 않고 500이 됩니다.

요청 헤더

파라미터명 유형 필수 설명
DF-API-KEY string Y 워크스페이스의 OpenAPI 인증 자격 증명입니다.
예시: <DF-API-KEY>
획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 발급받습니다.

파라미터 추가 설명

반환 파라미터 설명:

주요 필드

파라미터명 파라미터 설명
cashBalance 현금 계정 잔액
couponBalance 바우처 잔액
storedCardBalance 충전 카드 잔액

요청 예시

curl --get 'https://openapi.guance.com/api/v1/billing/balance/get' \
  -H 'DF-API-KEY: <DF-API-KEY>'

응답

HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.

필드 유형 설명
content object 현재 청구 센터 계정 잔액 뷰이며, 충전 금액 또는 인보이스 발행 가능 금액이 아닙니다.
content.cashBalance JSON 현금 계정 잔액으로, 예시는 number입니다. 업스트림 값을 그대로 전달하며 고정된 정밀도/통화 또는 자동 환산을 보장하지 않습니다.
content.couponBalance JSON 바우처 잔액으로, 업스트림 값을 그대로 반환하며 현금 인출 가능 잔액을 의미하지 않습니다.
content.storedCardBalance JSON 충전 카드 잔액으로, 업스트림 값을 그대로 반환하며 현금 잔액을 의미하지 않습니다.
content.declaration object 워크스페이스 선언으로, 잔액과 무관합니다.
{
  "code": 200,
  "content": {
    "cashBalance": 1000.25,
    "couponBalance": 20.0,
    "storedCardBalance": 0.0,
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

인증, 요청 제한 및 공통 요청 오류는 공통 오류 정의를 참고하십시오.

청구 센터 SDK는 먼저 ft.CloudCareApiError를 매핑하며, 업스트림 HTTP/비즈니스 code로 덮어씁니다. 이 SDK에는 전달(passthrough) 플래그가 설정되어 있지 않으므로, 최종 code가 500 이상이면 전역적으로 HTTP 500, ft.InternalServerError 및 일반 텍스트로 래핑되며, 외부에 503 또는 원본 5xx 메시지가 유지된다고 가정할 수 없습니다. 최종 code가 500 미만이면 CloudCareApiError와 실제 message가 유지됩니다. 연결 예외는 기본적으로 400입니다. 여기서는 확인된 Studio 매핑만 나열하며, 청구 센터의 각 비즈니스 오류나 프록시 오류를 모두 열거하지는 않습니다.

HTTP 상태 errorCode 트리거 조건 메시지 또는 응답 설명 처리 방법
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를 보존하여 관리자에게 문의하고 업스트림 응답을 확인한 후 잠시 후 다시 조회하십시오.

문서 평가

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