청구 월
청구 월은 한국 시간(KST) 기준 달력 월입니다. 한 달은 1일 00:00 KST에 시작하고 다음 달 1일 00:00 KST 직전에 끝납니다. 이벤트가 어느 달에 드는지는 이벤트의timestamp로 정합니다.
timestamp는 어떤 오프셋으로 보내도 됩니다. MeterEngine은 오프셋으로 순간을 정한 뒤 그 순간을 KST로 바꿔 달을 정하므로, 같은 순간이면 오프셋과 관계없이 같은 달에 듭니다.
API의 month 값(YYYY-MM)도 KST 달력 월입니다. month를 생략할 수 있는 API에서 생략하면 지금 KST 기준 이번 달입니다.
이벤트를 받는 기간
이벤트는 MeterEngine이 받은 시각을 기준으로timestamp가 35일보다 오래되지 않았으면 받습니다. 하루는 24시간으로 세고, 정확히 35일 전인 이벤트는 받습니다. 한 건씩 보낼 때와 묶어 보낼 때 기준이 같습니다.
35일보다 오래된 이벤트는 event_too_old로 거절되고 저장되지 않습니다. 한 건씩 보내면 400 응답을 받고, 묶어 보내면 그 원소의 결과가 rejected이고 error.code가 event_too_old입니다. 같은 이벤트를 다시 보내도 받지 않으니 재전송 대상에서 빼세요. 사용량 이벤트 보내기
400 응답 본문(한 건씩 보낼 때)
transaction_id로 다시 보낸 경우에는 timestamp가 35일을 넘었어도 거절하지 않고 200과 "duplicate": true로 답합니다.
timestamp가 미래 시각인 이벤트도 받아서 저장합니다. 다만 그 시각이 지나기 전에는 사용량과 청구 예정액에 들지 않습니다. 조회한 달에 든 미래 시각 이벤트 가운데 아직 집계되지 않은 수는 GET /v1/unbilled-events의 future_timestamp로 볼 수 있습니다.
집계 마감
한 달의 사용량은 다음 달 1일 13:00 KST까지 MeterEngine이 받은 이벤트로 셉니다. 기준은timestamp가 아니라 서버가 받은 시각(received_at)입니다. 이 시각을 집계 마감이라고 부릅니다. 콘솔의 ‘사용량’ 화면과 ‘청구 검토’ 화면 위에는 마감 전에는 ‘집계 마감’으로 마감 예정 시각이, 마감 뒤에는 ‘집계 기준’으로 그 시각까지 받은 사용량이라는 표시가 나옵니다.
마감 뒤에 받은 그 달 이벤트는 저장되지만 사용량, 청구 예정액, 인보이스 어디에도 들지 않습니다. 다음 달로 넘어가지도 않습니다.
마감 뒤에 받은 이벤트를 찾으려면 콘솔의 ‘수집 로그’ 화면에서 정렬 기준을 ‘수신 시각’으로 바꾸거나, GET /v1/events 응답의 received_at을 봅니다. 재전송 설계는 재전송 설계를 보세요.
단가와 요금제를 넣을 수 있는 달
단가는 이번 달 이후에만 넣을 수 있습니다. 매달 1일 00:00 KST가 되면 지난달은 “지난 달”이 되어, 시작 월(effective_from)이 지난달 이전인 단가를 넣거나 바꾸려 하면 409 price_rate_history_immutable을 받습니다. 기본료와 최소 사용료(요금제)도 같고, 이때는 409 price_plan_history_immutable을 받습니다.
단가 버전과 적용 월은 단가 모델과 버전에서 다룹니다.
확정 시각
수동 확정은 언제든 할 수 있습니다. 집계 마감 전에 확정하면 그 순간까지 받은 이벤트로 확정하고, 그 뒤에 들어온 그 고객의 그 달 이벤트는 청구되지 않습니다. 그래서 지난달은 다음 달 1일 13:00 KST가 지난 뒤 확정하는 것이 안전합니다. 인보이스 수동 확정 자동 확정은 켜져 있을 때 다음 달 1일 14:00 KST 이후에 돕니다. 서버에서 켜져 있으면 14:00 KST 정시부터 매시 정각에 확정 시각이 지난 달을 확정합니다. 지금 쓰는 서버에서 켜져 있는지는 청구 예정액 응답(GET /v1/invoices/draft)의 auto_finalize_enabled로 확인합니다. 동작은 자동 확정과 보류를 보세요.
월말 타임라인
10월 사용량을 예로 들면 다음과 같습니다.예약 작업
MeterEngine이 정해진 시각에 스스로 하는 일입니다.
웹훅 발송이 실패했을 때 다시 보내는 간격은 전송, 재전송, 중복 처리에 있습니다.
자리마다 뜻이 다른 cutoff_at
응답에 나오는cutoff_at은 자리에 따라 뜻이 다릅니다.