Skip to navigation
ClawOps APIUsage

사용량 집계 조회

View as Markdown

계정의 사용량을 집계된 형태로 돌려줍니다. 통화 목록을 받아 직접 합산하는 것과 다릅니다 —

  • 사후 정정이 반영됩니다. 통화 시간은 종료 후에도 정정될 수 있고(durationOverride, 늦은 finalize, 운영 보정), 이 API 는 호출 시점에 원장을 다시 집계하므로 그 정정이 항상 반영됩니다. 목록을 긁어 직접 쌓으면 이미 받아간 건의 정정이 반영되지 않아 청구서와 계속 어긋납니다.
  • 청구 주기 경계가 맞습니다. 주기 시작은 일 경계가 아니라 가입 순간의 시각입니다. 달력 월로 합산하면 어긋납니다.
  • 통화 목록에 없는 미터도 포함됩니다. 문자·전사·요약은 call_logs 에 없습니다.

정산에 쓰는 축

groupBy=linkId 가 관리번호 파트너의 정산 단위입니다. 이 값은 assignment.completed webhook 의 LinkId 와 같아서 파트너가 자기 사용자와 바로 조인할 수 있습니다. 관리번호로 발급되지 않은 번호는 linkId 가 null 로 묶입니다.

⚠️ 번호(groupBy=number)를 정산 단위로 쓰지 마십시오. 번호는 반납 후 재배정됩니다. 같은 번호에 이전 이용자의 사용량이 섞이지 않도록 이 API 는 배정 구간으로 잘라 집계하지만, 수신측에서 번호를 키로 누적하면 그 구분이 사라집니다.

단위 — 초로 돌려줍니다

통화·전사·요약은 초입니다. 청구는 계정 합계에 올림을 한 번만 겁니다 (ceil((발신+전환)/60)). 축을 쪼갠 값을 각각 올림해 더하면 합계가 청구서보다 커지므로, 올림한 분은 totals[].billableMinutes 에만 담습니다.

금액

records 에는 수량만 담깁니다. 단가가 누진 구간(발신 60 → 45 → 25원)이라 축별로 금액을 나눌 수 없습니다 — 합계에만 정의됩니다.

⚠️ 현재 amount 와 totals[].unitPriceHint 는 항상 null 입니다. 금액 계산은 플랜 포함량·누진 구간·애드온을 함께 봐야 해서 청구 경로를 재사용하는 후속 작업으로 남았습니다. 지금은 수량에 자사 단가를 적용해 사용하십시오.

Authentication

AuthorizationBearer

API Key를 Bearer 토큰으로 전달

Path parameters

accountIdstringRequired

계정 ID

Query parameters

fromdatetimeOptional

집계 시작(UTC, 포함). to 와 함께 주어야 합니다 — 한쪽만 주면 400. 생략하면 현재 청구 주기 전체를 집계합니다.

todatetimeOptional

집계 끝(UTC, 미포함). 구간 최대 92일.

groupBylist of enumsOptional

쪼갤 축. 반복 지정으로 조합합니다(?groupBy=day&groupBy=linkId). ⚠️ 콤마 구분(?groupBy=day,linkId)은 받지 않습니다 — 값 검증을 유지하기 위한 선택이라, 오타는 조용히 무시되지 않고 400 이 됩니다. 생략하면 미터별 합계만 돌려줍니다.

Allowed values:
meterlist of enumsOptional

특정 미터만 조회. 반복 지정(?meter=a&meter=b). 생략 시 전체.

includeTodaybooleanOptionalDefaults to false

진행 중인 오늘(UTC) 구간을 포함할지. 오늘 구간은 다시 조회할 때마다 값이 달라지고 스캔 구간도 그만큼 늘어납니다. 정산은 확정 구간만 쓰는 것이 정상이므로 기본은 false 입니다.

pageSizeintegerOptional1-1000

페이지당 항목 수(기본 200, 최대 1000).

page_sizeintegerOptional1-1000Deprecated

pageSize 의 별칭(하위호환). 신규 연동은 pageSize 를 사용하세요.

limitintegerOptional1-1000Deprecated

pageSize 의 별칭(하위호환). 신규 연동은 pageSize 를 사용하세요.

pageintegerOptional>=1Defaults to 1

1-based 페이지 번호.

Response

집계 결과

metaobject

페이징 상태. 다른 목록 API 의 meta 와 같은 모양이다.

total 은 records 를 쪼갠 전체 행 수이며, 축을 지정할수록 커진다. totals(사용량 합계)와는 다른 것이다.

periodobject

집계 구간. from/to 를 주지 않으면 현재 청구 주기가 들어간다.

⚠️ 경계는 전부 UTC 다. 청구 주기 시작은 일 경계가 아니라 가입 순간의 시각이 그대로 쓰인다(실측: 03:56:49, 11:21:39). 달력 월로 직접 합산하면 우리 청구서와 어긋나므로 정산에는 이 응답의 from/to 를 그대로 쓸 것.

recordslist of objects

groupBy 축으로 쪼갠 사용량. 수량만 담는다.

  • 통화·전사·요약은 초다. 분 올림은 여기서 하지 않는다(축마다 올림하면 합계가 커진다).
  • 금액도 담지 않는다 — 단가가 누진 구간이라 축별로 나눌 수 없다.
totalslist of objects

축과 무관한 계정 전체 합계. records 를 미터별로 합한 값과 일치한다.

amountobject or nullOptional

이번 구간의 종량 예상액.

⚠️ 현재는 어떤 조회에서도 항상 null 이다 — 금액 계산은 플랜 포함량·누진 구간· 애드온을 함께 봐야 해서 청구 경로를 재사용하는 후속 작업으로 남았다. 아래는 채워졌을 때의 계약이다.

다음 두 경우에는 그때에도 null 이다.

  • groupBy 에 linkId·number·day 중 하나라도 지정한 조회 — 축별 금액은 제공하지 않는다.
  • from/to 로 청구 주기가 아닌 임의 구간을 조회한 경우.

⚠️ 확정 청구액이 아니다. 정기 결제 시점의 플랜료·애드온·일할 계산은 포함되지 않는다.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error