계정 잔액 조회¶
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 | 충전 카드 잔액 |
요청 예시¶
응답¶
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를 보존하여 관리자에게 문의하고 업스트림 응답을 확인한 후 잠시 후 다시 조회하십시오. |