프로젝트와 권한을 지정한 API 키
콘솔의 프로젝트 → Open API → API 키에서 이름·범위·만료를 지정해 발급합니다. 키는 한 번만 표시되며 해시만 저장합니다. 계정의 현재 권한과 프로젝트 범위를 호출마다 검사하고 키를 해제할 수 있습니다.
Developers / Open API v1
비용 데이터를 연결하는하나의 열린 API.
외부 수집기의 비용·사용량을 OneCloud로 입력하고, 비용 원장·집계·연결·알림·이상 탐지·예측을 사내 시스템으로 가져오세요.
2026년 10월 25일 · Open API v1
API 기본 주소
https://dash.onecloud.im/api/v1필요한 API 권한만 선택
비용·사용량 조회, 수집 소스 쓰기, 비용 입력, 연결·입력 이력·알림·이상 탐지·예측 조회를 별도로 허용합니다. 키 발급에는 프로젝트 설정 쓰기와 선택한 범위의 현재 권한이 필요합니다.
호출과 입력 한도
키당 분당 120회(IP당 300회), 입력당 1–200건·100 KB. 날짜는 UTC 기준이고 한 번에 최대 366일을 조회합니다. 429 응답은 Retry-After에 따라 재시도합니다.
외부 자동화를 연결하는 순서
- 01
프로젝트에서 필요한 권한의 API 키를 발급합니다.
- 02
외부 수집 소스를 등록하고 반환된 sourceId를 저장합니다.
- 03
원본 ID·사용일·서비스·통화·금액·사용량을 JSON으로 변환합니다.
- 04
dryRun으로 검증하고 Idempotency-Key와 함께 입력합니다. complete 확인 후 체크포인트를 갱신합니다.
조회 API
| HTTP / Endpoint | OneCloud Open API | 필요한 API 권한 |
|---|---|---|
| GET/me | 키 정보 | — |
| GET/projects | 프로젝트 | — |
| GET/providers | 서비스 디렉터리 | — |
| GET/projects/{projectId}/connections | 연결 상태 | connections:read |
| GET/projects/{projectId}/sources | 수집 소스 | connections:read |
| GET/projects/{projectId}/costs | 비용 원장 | costs:read |
| GET/projects/{projectId}/costs/summary | 비용 집계 | costs:read |
| GET/projects/{projectId}/usage | 사용량 | usage:read |
| GET/projects/{projectId}/imports | 입력 이력 | imports:read |
| GET/projects/{projectId}/imports/{importId} | 입력 이력 | imports:read |
| GET/projects/{projectId}/alerts | 알림 규칙 | alerts:read |
| GET/projects/{projectId}/anomalies | 이상 탐지 | anomalies:read |
| GET/projects/{projectId}/forecasts | 예측 | forecasts:read |
입력 API
| HTTP / Endpoint | OneCloud Open API | 필요한 API 권한 |
|---|---|---|
| POST/projects/{projectId}/sources | 수집 소스 등록·이름 변경 | sources:write |
| POST/projects/{projectId}/costs/import | 비용·사용량 일괄 입력 | costs:write |
| POST/projects/{projectId}/sources/{sourceId}/records/delete | 원본 ID별 논리 삭제 | costs:write |
필요한 데이터를 사내 도구로
ERP·ETL·n8n·예약 작업이 비용과 사용량을 조회하고 커서로 다음 페이지를 가져올 수 있습니다. 증분 내보내기는 updatedSince·고정된 updatedBefore·includeDeleted=true를 사용하며, 모든 페이지가 성공한 뒤 체크포인트를 갱신합니다.
같은 원본은 갱신하고, 재시도는 안전하게
sourceId와 externalId로 원본 행을 식별합니다. 같은 요청은 동일한 본문과 Idempotency-Key로 재시도합니다. 실패 시 부분 작업과 집계를 복구하고, 완료된 요청은 중복 입력하지 않습니다. 날짜·통화가 바뀌어도 이전 집계를 다시 계산합니다.
통화와 단위를 보존합니다
KRW·USD 같은 통화, 요청 수·토큰·GB 같은 단위를 섞어 합산하지 않습니다. 사용량만 있으면 billedCost=0을 사용하고 환불은 음수로 기록합니다. 잔액·충전액·매출·결제 원금은 서비스 비용으로 입력하지 않습니다.
조회·입력 예제
아래 환경 변수는 콘솔에서 발급한 키와 프로젝트·수집 소스 ID로 설정하세요. 예제에는 실제 인증 정보가 들어 있지 않습니다.
조회 API
curl "https://dash.onecloud.im/api/v1/projects/$ONECLOUD_PROJECT_ID/costs?from=2026-10-01&to=2026-10-25&limit=100" \
-H "Authorization: Bearer $ONECLOUD_API_KEY"수집 소스 등록·이름 변경
curl -X POST "https://dash.onecloud.im/api/v1/projects/$ONECLOUD_PROJECT_ID/sources" \
-H "Authorization: Bearer $ONECLOUD_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"externalId":"billing-production","provider":"KakaoCloud","name":"Production collector"}'costs.json
{
"sourceId": "SOURCE_ID",
"records": [
{
"externalId": "invoice-202610-row-001",
"usageDate": "2026-10-24",
"service": "API requests",
"currency": "KRW",
"billedCost": 1200,
"usageQuantity": 1000,
"usageUnit": "requests",
"tags": {
"environment": "production"
}
}
]
}비용·사용량 일괄 입력
curl -X POST "https://dash.onecloud.im/api/v1/projects/$ONECLOUD_PROJECT_ID/costs/import" \
-H "Authorization: Bearer $ONECLOUD_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: billing-2026-10-batch-001' \
--data-binary @costs.json