# MeterEngine

> MeterEngine 도입사를 위한 연동 가이드와 API 참조

- [MeterEngine 소개](https://docs.meterengine.com/index.md): MeterEngine이 맡는 일과 도입사가 할 일을 나누고 다음에 읽을 페이지를 고릅니다.
- [빠른 시작](https://docs.meterengine.com/quickstart.md): 가입부터 테스트 환경에서 사용량 이벤트를 보내 청구 예정액을 확인하기까지 따라 합니다.
- [전체 흐름](https://docs.meterengine.com/concepts/how-it-works.md): 이벤트에서 청구와 결제까지의 흐름과 되돌릴 수 없는 제약, 안전한 준비 순서를 설명합니다.
- [업무 환경](https://docs.meterengine.com/concepts/environments.md): 테스트 환경과 실제 환경이 무엇을 나누는지, 기존 데이터는 무엇인지 설명합니다.
- [시간 규칙](https://docs.meterengine.com/concepts/time-rules.md): 청구 월, 수집 허용 기간, 집계 마감, 예약 작업의 기준 시각을 한곳에 모았습니다.
- [예정액, 확정액, 수납액](https://docs.meterengine.com/concepts/amounts.md): 화면과 API에 나오는 금액의 뜻과 세액, 절사 규칙을 설명합니다.
- [가입과 승인](https://docs.meterengine.com/account/signup.md): 가입 신청부터 승인 요청, 승인 확인, 첫 로그인까지의 절차와 그 사이에 만나는 오류를 설명합니다.
- [구성원과 권한](https://docs.meterengine.com/account/members.md): 구성원의 역할과 업무 권한, 초대 링크와 계정 직접 생성으로 구성원을 추가하고 관리하는 방법을 설명합니다.
- [공급자 정보](https://docs.meterengine.com/account/supplier.md): 도입사 설정의 공급자 정보를 저장하는 방법과 지금 그 정보가 쓰이는 곳을 설명합니다.
- [API 키 발급과 첫 호출](https://docs.meterengine.com/authentication/api-keys.md): 콘솔에서 서버 연동 키를 발급하고 첫 요청으로 키와 업무 환경을 확인합니다.
- [화면과 API, 권한](https://docs.meterengine.com/authentication/scopes.md): 콘솔 로그인과 API 키의 차이, read, ingest, admin 권한이 허용하는 일과 콘솔에서만 되는 기능을 설명합니다.
- [키 교체, 권한 변경, 폐기](https://docs.meterengine.com/authentication/key-rotation.md): API 키를 끊김 없이 교체하고, 권한만 바꾸거나, 즉시 폐기하는 방법과 키가 새어 나갔을 때의 대응을 설명합니다.
- [오류 응답과 X-Request-ID](https://docs.meterengine.com/api-basics/errors.md): 오류 응답 형식과 code별 처리, 다시 보낼지 판단하는 기준, X-Request-ID로 요청을 찾는 방법을 설명합니다.
- [요청 한도와 429](https://docs.meterengine.com/api-basics/rate-limits.md): API 키의 분당 요청 한도를 정하는 방법, 한도를 세는 방식, 429 응답을 처리하는 방법을 설명합니다.
- [멱등 규칙](https://docs.meterengine.com/api-basics/idempotency.md): 응답을 받지 못해 같은 요청을 다시 보내도 결과가 한 번만 반영되게 하는 규칙을 요청별로 정리했습니다.
- [미터 설계](https://docs.meterengine.com/pricing/meters.md): 이벤트에서 청구할 수량을 뽑는 미터를 정의하고, 이벤트가 들어온 뒤에도 안전하게 운영하는 방법을 설명합니다.
- [차원과 속성 조합](https://docs.meterengine.com/pricing/dimensions.md): 모델이나 지역처럼 이벤트 속성 값마다 다른 단가를 매기는 방법과, 단가가 빠진 조합을 찾는 방법을 설명합니다.
- [단가 모델과 버전](https://docs.meterengine.com/pricing/price-models.md): per_unit, graduated, volume 단가를 등록하는 방법과 월 단위 버전, 고객 단가 규칙을 설명합니다.
- [기본료와 최소 사용료](https://docs.meterengine.com/pricing/price-plans.md): 요금제로 월 기본료와 월 최소 사용료를 더하는 방법과 계산 순서, 적용 대상, 조회할 때의 함정을 설명합니다.
- [금액 계산 따라가기](https://docs.meterengine.com/pricing/calculation-example.md): 구간 단가, 최소 사용료, 기본료가 있는 예시 하나로 청구 금액을 직접 계산하고 응답 값과 맞춰 봅니다.
- [바꾸기, 보관, 복원](https://docs.meterengine.com/pricing/changes-and-archiving.md): 고객, 미터, 단가, 요금제를 바꾸거나 보관하고 복원할 때 언제부터 무엇이 달라지는지 설명합니다.
- [고객 등록과 ID 대응](https://docs.meterengine.com/integration/customers.md): 고객을 등록하고 도입사 시스템의 ID와 MeterEngine 고객 id를 대응시키는 방법을 설명합니다.
- [사용량 이벤트 보내기](https://docs.meterengine.com/integration/events.md): 사용량 이벤트를 한 건씩 또는 묶어서 보내는 방법과 응답을 설명합니다.
- [재전송 설계](https://docs.meterengine.com/integration/retries.md): 이벤트 전송이 실패했을 때 다시 보낼 것과 멈출 것을 가르는 방법을 설명합니다.
- [보낸 데이터 확인하기](https://docs.meterengine.com/integration/verify-usage.md): 보낸 이벤트가 저장되고 사용량으로 집계되어 청구 예정액에 반영됐는지 순서대로 확인합니다.
- [이벤트가 청구에 안 보일 때](https://docs.meterengine.com/troubleshooting/events-not-billed.md): 보낸 사용량이 사용량이나 청구 예정액에 나오지 않을 때 원인을 찾는 순서와 증상별 조치를 정리했습니다.
- [서버 조회와 CSV 내보내기](https://docs.meterengine.com/reference/search-and-export.md): 목록을 조건으로 검색하고, 같은 조건의 전체 결과를 CSV로 내려받아 자기 기록과 맞추는 방법을 설명합니다.
- [인보이스 수동 확정](https://docs.meterengine.com/billing/finalize-invoices.md): 한 달의 청구 예정액을 고객별 인보이스로 확정하는 방법과 확정 결과를 읽는 법을 설명합니다.
- [자동 확정과 보류](https://docs.meterengine.com/billing/auto-finalization.md): 서버의 자동 확정이 켜져 있는지 확인하는 법과 켜져 있을 때의 시각, 결과, 보류 조건을 설명합니다.
- [확정 뒤 바뀌는 것과 안 바뀌는 것](https://docs.meterengine.com/billing/after-finalization.md): 확정한 인보이스에서 고정되는 값, 확정 뒤에도 바뀌는 것, 확정 전에 점검할 것을 정리했습니다.
- [결제 연동 한눈에 보기](https://docs.meterengine.com/payments/overview.md): 토스페이먼츠로 확정 인보이스를 결제받기까지 도입사와 MeterEngine이 나눠 맡는 일과 순서를 설명합니다.
- [토스페이먼츠 상점 준비와 키 저장](https://docs.meterengine.com/payments/toss-setup.md): 토스페이먼츠 키를 준비해 콘솔에 저장하고 토스페이먼츠 웹훅을 등록하는 방법을 설명합니다.
- [테스트 결제와 실결제](https://docs.meterengine.com/payments/test-and-live.md): 테스트 환경의 테스트 결제와 실제 환경의 실결제가 어떻게 나뉘고, 테스트 환경에서 무엇을 확인한 뒤 실제 환경으로 옮기는지 설명합니다.
- [고객 카드 등록 링크](https://docs.meterengine.com/payments/card-registration.md): 고객이 결제 카드를 등록하는 링크를 만들어 전달하고, 등록 결과를 확인하는 방법을 설명합니다.
- [첫 결제 요청과 결과 확인](https://docs.meterengine.com/payments/charging.md): 확정 인보이스의 결제를 요청하고, 응답과 결제 시도, 수납 상태로 결과를 확인하는 방법을 설명합니다.
- [결제 실패와 재시도](https://docs.meterengine.com/payments/retries.md): 결제가 실패했을 때 MeterEngine의 자동 재시도, 고객의 링크 재시도, 도입사의 재요청이 각각 언제 일어나는지 설명합니다.
- [결제 취소](https://docs.meterengine.com/payments/cancellations.md): 승인된 결제를 전부 또는 일부 취소하는 방법과 취소 뒤 인보이스와 수납 상태가 어떻게 되는지 설명합니다.
- [고객에게 인보이스 보여 주기](https://docs.meterengine.com/payments/invoice-links.md): 고객이 로그인 없이 확정 인보이스와 결제 상태를 보는 조회 링크를 발급하고 전달하고 폐기하는 방법을 설명합니다.
- [수납 상태와 대사 확인](https://docs.meterengine.com/payments/reconciliation.md): 인보이스별 수납 상태를 조회하고, MeterEngine 결제 기록과 토스페이먼츠 거래를 맞춰 본 대사 결과를 확인하는 방법을 설명합니다.
- [웹훅 받기 시작하기](https://docs.meterengine.com/webhooks/overview.md): 웹훅 수신 주소를 등록하고, 서명 비밀값을 보관하고, 시험 웹훅으로 연결을 확인하는 방법을 설명합니다.
- [웹훅 서명 검증](https://docs.meterengine.com/webhooks/verify-signatures.md): 받은 웹훅이 MeterEngine이 보낸 것인지 webhook-signature 헤더로 확인하는 방법과 그대로 옮겨 쓸 수 있는 검증 코드를 설명합니다.
- [웹훅 이벤트 유형과 data](https://docs.meterengine.com/webhooks/events.md): 모든 웹훅에 공통인 본문 형식과 유형별 data 필드, 유형마다 보내는 때를 설명합니다.
- [전송, 재전송, 중복 처리](https://docs.meterengine.com/webhooks/delivery-and-retries.md): 웹훅 전송의 성공 기준과 시간 제한, 자동 재전송 일정, 실패한 전송을 다시 보내는 방법, 중복과 순서 문제를 다루는 방법을 설명합니다.
- [용어 대응표](https://docs.meterengine.com/reference/glossary.md): 가이드 용어를 콘솔 화면 표기, API 값과 나란히 정리하고 자세히 설명한 페이지로 잇습니다.
- [API 참조 읽는 법](https://docs.meterengine.com/api-reference/introduction.md): API 참조의 접속 주소, 인증, 시험 화면 사용법, 참조에 싣지 않은 경로를 설명합니다.
- [미터별 가격 목록 조회](https://docs.meterengine.com/api-reference/billable-metric-price-controller/미터별-가격-목록-조회.md): 지정 월에 유효한 조합별 최신 단가를 돌려준다. 월은 기본 이번 달이며 customer_id가 없으면 도입사 공통 단가만 조회한다.
- [미터별 가격 검색 결과 CSV](https://docs.meterengine.com/api-reference/workspace-query-controller/미터별-가격-검색-결과-csv.md)
- [단가 버전이 시작된 월 목록](https://docs.meterengine.com/api-reference/workspace-query-controller/단가-버전이-시작된-월-목록.md)
- [월별 가격 검색과 서버 페이지 조회](https://docs.meterengine.com/api-reference/workspace-query-controller/월별-가격-검색과-서버-페이지-조회.md): month, customer_id, billable_metric_code, q, status(미터 보관 상태), sort(code/name/rate_count/archived_at), order, page, size를 받는다. 미터 이름과 단가 수, 조건 전체 no_rate_count를 포함한다. summary는 month, metric_count, no_rate_count다.
- [미터 검색 결과 CSV](https://docs.meterengine.com/api-reference/workspace-query-controller/미터-검색-결과-csv.md)
- [미터 검색과 서버 페이지 조회](https://docs.meterengine.com/api-reference/workspace-query-controller/미터-검색과-서버-페이지-조회.md): q, billable_metric_code, status(active/archived/all), sort(code/name/event_type/aggregation/archived_at), order, page, size를 받는다. summary는 active_count, archived_count다.
- [고객 검색 결과 CSV](https://docs.meterengine.com/api-reference/workspace-query-controller/고객-검색-결과-csv.md): 현재 페이지가 아니라 같은 검색 조건의 전체 결과를 내보낸다. 최대 10000행이며 초과하면 범위를 좁히도록 400을 반환한다.
- [고객 검색과 서버 페이지 조회](https://docs.meterengine.com/api-reference/workspace-query-controller/고객-검색과-서버-페이지-조회.md): q, external_id, customer_id, status(active/archived/all), sort(name/external_id/created_at/archived_at/id/billing_email), order, page, size를 받는다. total은 조건 전체, total_unfiltered는 현재 조직과 환경의 전체 건수다. 페이지는 1부터, size 기본 25/최대 200이다. summary는 active_count, archived_count다.
- [청구 예정액 검색 결과 CSV](https://docs.meterengine.com/api-reference/workspace-query-controller/청구-예정액-검색-결과-csv.md)
- [청구 예정액 검색과 페이지 독립 요약](https://docs.meterengine.com/api-reference/workspace-query-controller/청구-예정액-검색과-페이지-독립-요약.md): month, customer_id, billable_metric_code, q, min_amount, max_amount, sort(customer_name/customer_id/amount/line_count), order, page, size를 받는다. amount는 선택 조건 전체 합계이며 month_amount는 월 전체다. 기존 확정 요청은 검색 조건과 관계없이 월 전체를 확정하므로 finalization_scope는 month다. summary는 month, calculated_at, amount, customer_cou…
- [인보이스 검색 결과 CSV](https://docs.meterengine.com/api-reference/workspace-query-controller/인보이스-검색-결과-csv.md)
- [확정 인보이스가 있는 월 목록](https://docs.meterengine.com/api-reference/workspace-query-controller/확정-인보이스가-있는-월-목록.md)
- [인보이스와 결제 상태 검색](https://docs.meterengine.com/api-reference/workspace-query-controller/인보이스와-결제-상태-검색.md): customer_id, month, from/to(확정 시각, 날짜 종료일 포함/KST), status, mode, min_amount, max_amount, billable_metric_code, q, sort(month/customer_name/total_amount/finalized_at/invoice_number/status), order, page, size를 받는다. mode 기본은 현재 결제 설정이다. 조건 전체 금액과 결제 상태 건수는 페이지와 독립이며 pending이 있으면 outstanding_amount는 nul…
- [고객별 사용량 검색 결과 CSV](https://docs.meterengine.com/api-reference/workspace-query-controller/고객별-사용량-검색-결과-csv.md)
- [이벤트가 있는 월 목록](https://docs.meterengine.com/api-reference/workspace-query-controller/이벤트가-있는-월-목록.md): KST 발생 시각 기준의 월을 중복 없이 내림차순으로 반환한다.
- [고객 단위 사용량 검색과 서버 페이지 조회](https://docs.meterengine.com/api-reference/workspace-query-controller/고객-단위-사용량-검색과-서버-페이지-조회.md): month, customer_id, billable_metric_code, q, status(고객 보관 상태, 기본 all), sort(customer_name/customer_id/line_count), order, page, size를 받는다. 한 고객의 모든 미터를 같은 페이지에 둔다. summary는 month, customer_count, metric_count, line_count, nonzero_customer_count다.
- [미터 목록 조회](https://docs.meterengine.com/api-reference/billable-metric-controller/미터-목록-조회.md)
- [집계 미터 등록](https://docs.meterengine.com/api-reference/billable-metric-controller/집계-미터-등록.md): 미터를 등록한다. type이 미터의 event_type과 같은 사용량 이벤트가 이 미터의 집계 대상이다. aggregation은 sum, count, count_distinct, min, max, avg, first, last, median, percentile을 받으며 대소문자를 구분하지 않는다. count는 전체 이벤트 수이며 target_property를 지정하지 않는다. count_distinct는 대상 속성의 숫자, 문자열, 불리언 고유값 수다. 나머지는 숫자 속성만 집계한다. first와 last는 occurred_at,…
- [미터 상세 조회](https://docs.meterengine.com/api-reference/billable-metric-controller/미터-상세-조회.md)
- [집계 미터 수정](https://docs.meterengine.com/api-reference/billable-metric-controller/집계-미터-수정.md): 미터를 요청 값으로 덮어쓰고 바뀐 미터를 돌려준다. code는 바꿀 수 없다. 현재 event_type의 이벤트가 한 건이라도 있으면 이름만 바꿀 수 있다. 집계, 대상 속성, 차원, 단위, 반올림, 백분위 변경은 409다.
- [미터 보관](https://docs.meterengine.com/api-reference/billable-metric-controller/미터-보관.md): 현재 월까지 집계를 유지하고 다음 달부터 중단한다. 이벤트와 단가는 유지한다. 반복 요청은 204다.
- [버전을 확인한 미터 수정](https://docs.meterengine.com/api-reference/billable-metric-controller/버전을-확인한-미터-수정.md): 조회한 version을 큰따옴표로 감싼 If-Match 헤더가 필수다. 다른 요청이 먼저 수정했으면 409다. PUT과 같은 전체 필드를 보낸다.
- [미터 복원](https://docs.meterengine.com/api-reference/billable-metric-controller/미터-복원.md): 다음 달부터 집계를 재개한다. 보관한 기간을 소급 집계하지 않는다.
- [미터 단가 이력 조회](https://docs.meterengine.com/api-reference/price-rate-controller/미터-단가-이력-조회.md)
- [단가 등록](https://docs.meterengine.com/api-reference/price-rate-controller/단가-등록.md): 미터에 속성 값 조합별 단가를 넣는다. dimension_values의 키 집합은 미터의 dimension_properties와 같아야 하고, 키가 없는 미터는 빈 객체 하나만 받는다. 청구는 조합이 정확히 같은 단가만 쓰고 폴백은 없다. 같은 시작 월과 고객 범위의 버전은 갱신한다. 지난달 이전 버전은 바꿀 수 없다. 종료 월은 포함하지 않으며 고객 단가가 공통 단가보다 우선한다.
- [단가 조합 보관](https://docs.meterengine.com/api-reference/price-rate-controller/단가-조합-보관.md): 미터에서 속성 값 조합 하나의 공통 단가(customer_id 없음) 가운데 이번 달(Asia/Seoul)에 적용 중인 버전을 보관하고 다음 달부터 효력을 중단한다. 현재 월 계산과 버전 이력, 미래 예약은 유지하고 고객 단가는 그대로 둔다. dimension_values는 JSON 객체 문자열이고, 빈 객체 {}는 기본 단가다. 같은 조합인지는 키 순서와 상관없이 본다.
- [단가 버전 보관](https://docs.meterengine.com/api-reference/price-rate-controller/단가-버전-보관.md): 현재 월 효력은 유지하고 다음 달부터 중단한다. 미래 예약은 시작 전 보관되며 버전 이력은 유지한다.
- [단가 버전 복원](https://docs.meterengine.com/api-reference/price-rate-controller/단가-버전-복원.md): 보관 효력이 시작되기 전이고 대체 버전이 없을 때만 복원한다. 그 밖에는 새 버전을 등록한다.
- [고객 목록 조회](https://docs.meterengine.com/api-reference/customer-controller/고객-목록-조회.md): 등록한 고객을 이름 오름차순으로 전부 돌려준다. 이름이 같으면 id 순이다. 사용량 조회, 청구 예정액 조회의 고객 순서와 같다. 페이지를 나누지 않는다.
- [고객 등록](https://docs.meterengine.com/api-reference/customer-controller/고객-등록.md): 고객을 등록하고 서버가 발급한 id와 함께 돌려준다. 사용량 이벤트를 보낼 때 이 id를 customer_id에 싣는다. external_id는 도입사 안에서 유일하다. 같은 external_id를 다시 보내면 기존 고객을 200으로 돌려주고 이름과 이메일은 바꾸지 않는다. external_id를 생략하면 매번 새 고객을 만든다. Idempotency-Key 헤더를 사용하면 같은 조직/환경/작업의 같은 요청을 재전송해도 최초 생성 응답을 돌려준다. 같은 키와 다른 본문은 409다. billing_email은 선택 입력이다. 확정한…
- [고객 조회](https://docs.meterengine.com/api-reference/customer-controller/고객-조회.md)
- [고객 수정](https://docs.meterengine.com/api-reference/customer-controller/고객-수정.md): 고객 이름과 청구 이메일을 바꾸고 바뀐 고객을 돌려준다. 보낸 값으로 통째로 바꾼다. billing_email을 빼거나 null로 보내면 청구 이메일이 지워진다.
- [고객 보관](https://docs.meterengine.com/api-reference/customer-controller/고객-보관.md): 새 수집과 신규 등록을 중단한다. 기존 이벤트, 청구, 결제 이력은 유지한다. 반복 요청은 204다.
- [버전을 확인한 고객 수정](https://docs.meterengine.com/api-reference/customer-controller/버전을-확인한-고객-수정.md): 조회한 version을 If-Match 헤더에 큰따옴표로 감싸 보낸다. 바뀐 버전이면 409이며 원래 데이터는 유지한다. 이름/이메일을 모두 보내는 조건부 수정이다.
- [고객 복원](https://docs.meterengine.com/api-reference/customer-controller/고객-복원.md)
- [고객 카드 조회](https://docs.meterengine.com/api-reference/payment-method-controller/고객-카드-조회.md): 고객이 지금 결제 모드로 등록한 카드를 돌려준다. 빌링키 원문은 싣지 않는다. authenticated_at은 KST(+09:00)로 나온다.
- [고객 카드 보관](https://docs.meterengine.com/api-reference/payment-method-controller/고객-카드-보관.md): 새 자동 결제를 중단한다. 복원하려면 고객이 카드를 다시 인증해야 한다. 기존 결제와 취소 이력은 유지한다.
- [고객 카드 목록 조회](https://docs.meterengine.com/api-reference/payment-method-controller/고객-카드-목록-조회.md): 지금 결제 모드로 등록한 고객 카드를 customer_id 오름차순으로 전부 돌려준다. customer_id를 주면 그 고객의 카드만 돌려준다. 빌링키 원문은 싣지 않는다. 페이지를 나누지 않는다. authenticated_at은 KST(+09:00)로 나온다. status가 archived나 all이면 교체나 보관으로 물러난 이전 카드를 현재 행 뒤에 물러난 시각 내림차순으로 붙이고, archived_at에 물러난 시각을 담는다. 이전 카드는 새 결제에 다시 쓰이지 않는다.
- [카드 등록 링크 생성](https://docs.meterengine.com/api-reference/payment-method-registration-controller/카드-등록-링크-생성.md): 고객이 카드를 등록할 일회용 링크를 만든다. 본문은 받지 않는다. token은 이 응답에만 실린다. 서버는 token 원문을 저장하지 않으므로 다시 조회할 수 없다. 링크는 지금 결제 모드로 만들고 24시간 뒤 만료된다. 카드 등록에 한 번 쓰면 다시 쓸 수 없다. API 키로 부르면 키의 모드가 지금 결제 모드와 같아야 하고, 다르면 409다. expires_at은 KST(+09:00)로 나온다.
- [월별 과금과 수납 현황 조회](https://docs.meterengine.com/api-reference/dashboard-controller/월별-과금과-수납-현황-조회.md): 로그인 세션 또는 read API 키의 도입사 현황을 조회한다. 예정액은 공급가액이고, 확정액과 수납액은 세금 포함 금액이다. 취소는 결제 대기액으로 다시 잡지 않는다.
- [사용량 이벤트 일괄 수집](https://docs.meterengine.com/api-reference/event-batch-controller/사용량-이벤트-일괄-수집.md): 1건부터 100건까지 받아 입력 순서대로 stored, duplicate, rejected 결과를 돌려준다. 원소의 형식 오류는 다른 원소의 저장을 막지 않는다. 봉투 오류는 400이다.
- [수집된 이벤트의 매핑 문제 조회](https://docs.meterengine.com/api-reference/event-issue-controller/수집된-이벤트의-매핑-문제-조회.md): 현재 월 정의와 단가로 cutoff 이전 원본을 진단한다. total과 summary는 고객/검색/사유 필터 전체의 문제 행 수이며 한 이벤트에 여러 미터 문제가 있을 수 있다. warnings는 조직/월 전체다. 고객을 찾지 못해 수집이 거절된 이벤트는 저장되지 않아 포함하지 않는다. 원본 properties는 반환하지 않는다. 페이지는 0부터 시작한다. 모르는 조회 조건은 400 validation_error로 거절한다.
- [수집 업무 거절 메타데이터 조회](https://docs.meterengine.com/api-reference/event-rejection-controller/수집-업무-거절-메타데이터-조회.md): month는 거절을 기록한 달이다. 신규 기록 시작 이후 파싱된 단건 업무 거절과 배치 rejected 행만 포함한다. 최상위 JSON 파싱/입력 검증, 인증/한도 거절과 과거 거절은 포함하지 않는다. 원본 properties, 오류 원문과 행위자 ID는 반환하지 않는다. 페이지는 0부터 시작한다. 모르는 조회 조건은 400 validation_error로 거절한다.
- [사용량 이벤트 조회](https://docs.meterengine.com/api-reference/event-controller/사용량-이벤트-조회.md): 지정한 달의 이벤트를 occurred_at 최신순으로 한 페이지씩 돌려준다. occurred_at이 같으면 transaction_id 내림차순이다. 기간은 KST 기준의 달이다. occurred_at 2026-08-31T23:59:59+09:00 이벤트는 8월에, 2026-09-01T00:00:00+09:00 이벤트는 9월에 든다. 사용량 조회와 기준이 같다. customer_id, month, type을 함께 주면 모두 만족하는 이벤트만 나오고, total은 조건을 적용한 뒤의 건수다. from과 to를 함께 주면 월 대신 자유…
- [사용량 이벤트 수집](https://docs.meterengine.com/api-reference/event-controller/사용량-이벤트-수집.md): 사용량 이벤트 한 건을 저장한다. transaction_id가 같은 이벤트를 다시 보내면 저장하지 않고 처음 저장한 이벤트를 유지한다. 이때도 응답은 200이고 duplicate가 true다. 응답을 받지 못했으면 같은 transaction_id로 다시 보내면 된다. properties는 키나 문자열 값에 NUL 문자나 짝이 없는 UTF-16 서로게이트가 있거나 숫자가 소수점 앞 131072자리나 소수점 뒤 16383자리를 넘으면 거절하고, 그 밖의 내용은 검증하지 않는다. 키 순서와 공백은 보존되지 않고, 숫자는 정수와 소수 모두…
- [이벤트 단건 조회](https://docs.meterengine.com/api-reference/event-controller/이벤트-단건-조회.md): transaction_id 원문으로 조회한다. 목록의 페이지나 기간에 포함되지 않아도 상세 정보를 열 수 있다. 모르는 조회 조건은 무시한다.
- [이벤트가 있는 월 조회](https://docs.meterengine.com/api-reference/event-controller/이벤트가-있는-월-조회.md): 현재 도입사와 업무 환경에 저장된 이벤트의 occurred_at을 KST 월로 구분한다. 중복 없이 최신 월부터 반환하며 목록의 고객, 유형과 검색 조건에 관계없이 환경 전체의 월을 보여 준다. 모르는 조회 조건은 400 validation_error로 거절한다.
- [수집된 이벤트 유형 조회](https://docs.meterengine.com/api-reference/event-controller/수집된-이벤트-유형-조회.md): 미터 정의와 관계없이 조회 기간에 실제로 수집된 유형을 돌려준다. month 또는 from/to를 사용한다. 모르는 조회 조건은 무시한다.
- [사용량 이벤트 CSV 내보내기](https://docs.meterengine.com/api-reference/event-export-controller/사용량-이벤트-csv-내보내기.md): 이벤트 목록과 같은 월 또는 자유 기간, 고객, 유형, 검색, 속성 조건과 정렬을 적용한다. page와 size는 목록 링크 호환을 위해 받지만 내보내기에는 적용하지 않는다. 조건 전체가 10000행을 넘거나, include_properties=true일 때 원본 properties 합계가 32MB를 넘으면 400 validation_error로 거절한다. UTF-8 BOM과 CRLF를 사용하며 문자열의 스프레드시트 수식을 이스케이프한다. include_properties=true를 선택한 경우에만 원본 properties JSON…
- [인보이스별 결제 상태 목록](https://docs.meterengine.com/api-reference/invoice-payment-controller/인보이스별-결제-상태-목록.md): 인보이스마다 도입사의 현재 결제 모드(test 또는 live)로 본 결제 상태를 한 줄씩 돌려준다. 다른 결제 모드의 시도는 보지 않는다. 상태는 그 모드에서 가장 늦게 요청한 시도로 정한다. total_amount가 0원이면 not_required, 시도가 없으면 unpaid, 시도가 pending이면 pending, failed면 failed다. 시도가 done이면 그 시도에서 취소를 마친 금액의 합이 0원이면 paid, 결제 금액보다 적으면 partially_canceled, 결제 금액과 같으면 canceled다. 순서와 거르…
- [인보이스 목록 조회](https://docs.meterengine.com/api-reference/invoice-controller/인보이스-목록-조회.md): 확정된 인보이스를 (고객, 달)마다 한 줄씩 돌려준다. 확정 전의 금액은 청구 예정액 조회로 본다. customer_id와 month를 함께 주면 둘 다 만족하는 인보이스만 나온다. month를 생략하면 모든 달이다. 달 내림차순이고, 같은 달은 고객 이름 오름차순, 이름이 같으면 고객 id 순이다. supply_amount, tax_amount, total_amount는 확정할 때 저장한 공급가액, 세액, 합계(공급가액 + 세액)이고 원 단위 정수다. lines는 확정할 때 저장한 조합별 수량, 단가, 금액이고 미터 code 오름…
- [인보이스 일괄 확정](https://docs.meterengine.com/api-reference/invoice-controller/인보이스-일괄-확정.md): 그 달 청구 예정액이 0원이 아닌 고객을 한 번에 확정한다. 세액은 공급가액의 10%다. 그 달에 발생했고 집계 마감 시각(다음 달 1일 13:00 KST) 전에 받은 이벤트로 확정해서, 마감이 지난 달의 확정 금액과 라인은 그 시점의 청구 예정액과 같다. 마감 시각 전에 확정하면 확정 시각까지 받은 이벤트로 확정하고 그 시각을 인보이스의 cutoff_at에 남긴다. 수량이 0인 라인은 인보이스에 싣지 않는다. 확정한 고객은 그 달 청구 예정액에서 빠진다. 확정한 고객마다 같은 트랜잭션에서 보낼 청구 메일을 남긴다. 고객에 청구 이…
- [인보이스 조회](https://docs.meterengine.com/api-reference/invoice-controller/인보이스-조회.md): 확정된 인보이스 하나를 돌려준다. 응답은 인보이스 목록 조회의 같은 인보이스 원소와 같다. cutoff_at과 finalized_at은 KST(+09:00)로 나온다.
- [청구 예정액 조회](https://docs.meterengine.com/api-reference/draft-invoice-controller/청구-예정액-조회.md): 아직 확정하지 않은 고객의 청구 예정액을 미터의 속성 값 조합별 사용량 x 그 조합의 단가로 계산해 돌려준다. 그 달이 확정된 고객은 나오지 않고 total_amount는 남은 고객의 합이다. 확정된 금액은 인보이스 목록 조회로 본다. 조회할 때마다 계산하며 저장하지 않는다. 기간은 KST 기준의 달이다. 그 달 이벤트 중 집계 마감 시각(다음 달 1일 13:00 KST) 전에 서버가 받은(received_at) 것만 집계한다. 마감 뒤에 받은 그 달 이벤트는 저장되지만 집계와 청구에 들지 않는다. 금액은 원 단위 정수다. 라인(고…
- [인보이스 결제 시도 목록](https://docs.meterengine.com/api-reference/payment-attempt-controller/인보이스-결제-시도-목록.md): 인보이스의 결제 시도를 모든 결제 모드에 걸쳐 요청 시각이 늦은 것부터 돌려준다. requested_at과 completed_at은 KST(+09:00)로 나온다.
- [인보이스 결제 요청](https://docs.meterengine.com/api-reference/payment-attempt-controller/인보이스-결제-요청.md): 인보이스의 total_amount를 그 고객의 등록 카드로 토스페이먼츠 자동결제 승인을 요청한다. 본문은 받지 않는다. 도입사의 현재 결제 모드(test 또는 live)의 토스페이먼츠 키와 그 모드로 등록한 카드를 쓴다. 승인되면 status=done과 payment_key, 거절되면 status=failed와 failure_code, failure_message가 남고 둘 다 201이다. 토스페이먼츠 응답으로 결과를 확인하지 못하면 status=pending인 시도를 201로 돌려준다. 결제 모드마다 인보이스 하나에 결제 중이거나…
- [고객 인보이스 조회 링크 목록](https://docs.meterengine.com/api-reference/invoice-view-link-controller/고객-인보이스-조회-링크-목록.md): 원문 token을 제외한 발급 이력을 조회한다.
- [고객 인보이스 조회 링크 발급](https://docs.meterengine.com/api-reference/invoice-view-link-controller/고객-인보이스-조회-링크-발급.md): 로그인 없이 인보이스 하나를 조회하는 링크를 만든다. token은 발급 응답에만 제공하고 해시만 저장한다. 기본 30일, 최대 90일이며 폐기할 수 있다. 결제 상태는 발급 당시 test/live 모드로 조회한다. 링크를 가진 사람이 조회할 수 있으므로 고객에게만 전달한다. 재시도를 허용하는 링크를 API 키로 만들면 키의 모드가 지금 결제 모드와 같아야 하고, 다르면 409 payment_mode_mismatch다.
- [고객 인보이스 조회 링크 폐기](https://docs.meterengine.com/api-reference/invoice-view-link-controller/고객-인보이스-조회-링크-폐기.md): 폐기한 링크는 다시 사용할 수 없다. 반복 폐기는 같은 결과다.
- [현재 도입사 조회](https://docs.meterengine.com/api-reference/current-organization-controller/현재-도입사-조회.md): 요청에 실은 키나 로그인 세션의 도입사를 돌려준다.
- [공급자 정보 조회](https://docs.meterengine.com/api-reference/current-organization-controller/공급자-정보-조회.md)
- [공급자 정보 수정](https://docs.meterengine.com/api-reference/current-organization-controller/공급자-정보-수정.md)
- [도입사의 테스트와 실제 환경 조회](https://docs.meterengine.com/api-reference/organization-environment-controller/도입사의-테스트와-실제-환경-조회.md): 기존 미분류 데이터는 두 환경에 복사하거나 귀속시키지 않는다.
- [결제 취소 목록](https://docs.meterengine.com/api-reference/payment-cancellation-controller/결제-취소-목록.md): 결제 시도의 취소를 요청 시각이 늦은 것부터 돌려준다. requested_at과 completed_at은 KST(+09:00)로 나온다.
- [결제 취소 요청](https://docs.meterengine.com/api-reference/payment-cancellation-controller/결제-취소-요청.md): done인 결제 시도의 금액 전부나 일부를 토스페이먼츠에 취소 요청한다. amount를 빼면 남은 결제 금액 전부를 취소한다. 남은 결제 금액은 시도 금액에서 done인 취소의 합을 뺀 값이다. 시도의 결제 모드 키로 토스페이먼츠를 부른다. 취소되면 status=done, 거절되면 status=failed와 failure_code, failure_message가 남고 둘 다 201이다. 토스페이먼츠 응답으로 결과를 확인하지 못하면 status=pending인 취소를 201로 돌려준다. 시도 하나에 pending인 취소는 하나뿐이다.…
- [결제 대사 불일치 목록](https://docs.meterengine.com/api-reference/payment-reconciliation-mismatch-controller/결제-대사-불일치-목록.md): 하루치 토스페이먼츠 거래 목록과 MeterEngine의 done 결제 시도, done 취소를 맞춰 보고 남긴 불일치를 돌려준다. 선택한 환경의 기록만 담고, 기존 범위에서는 두 결제 모드를 담는다. 기간은 불일치를 찾은 시각(detected_at)의 KST 날짜로 거르고, from 날짜 0시부터 to 날짜가 끝날 때까지다. detected_at 내림차순이다. transacted_at과 detected_at은 KST(+09:00)로 나온다. 페이지를 나누지 않는다.
- [결제 모드 조회](https://docs.meterengine.com/api-reference/payment-setting-controller/결제-모드-조회.md): 선택한 환경의 결제 모드를 돌려준다. test/live 환경의 모드는 고정이며 updated_at=null이다. 기존 범위는 저장한 모드를 쓰고, 바꾼 적 없으면 mode=test다. updated_at은 KST(+09:00)로 나온다.
- [요금제 이력 조회](https://docs.meterengine.com/api-reference/price-plan-controller/요금제-이력-조회.md): customer_id를 주면 그 고객의 요금제만, 생략하면 도입사 공통 요금제만 돌려준다. 고객 요금제는 customer_id로 따로 조회한다. month를 주면 시작 월부터 종료 월 전까지에 그 달이 드는 버전만, 생략하면 기간과 상관없이 버전 이력을 돌려준다. 보관 여부는 month와 상관없이 status로 고른다. 시작 월 내림차순이다. 청구는 보관 효력(archived_from)까지 따져 버전을 고르므로, 그 달 청구에 쓰이는 요금제는 status=all 목록에서 시작 월이 가장 늦은 버전을 보고 고른다. 그 버전이 arch…
- [기본료와 최소 과금 요금제 등록](https://docs.meterengine.com/api-reference/price-plan-controller/기본료와-최소-과금-요금제-등록.md): 사용료에 최소 과금을 적용한 뒤 기본료를 더한다. 수량이 없는 고객에게는 적용하지 않는다. 청구할 때 기본료와 최소 사용료는 10원 미만을 버린 값을 쓰며, 버린 기본료가 0원이면 기본료 라인이 생기지 않는다.
- [요금제 버전 보관](https://docs.meterengine.com/api-reference/price-plan-controller/요금제-버전-보관.md): 현재 월 효력은 유지하고 다음 달부터 중단한다. 버전 이력은 유지한다.
- [요금제 버전 복원](https://docs.meterengine.com/api-reference/price-plan-controller/요금제-버전-복원.md): 보관 효력이 시작되기 전이고 대체 버전이 없을 때만 복원한다. 그 밖에는 새 버전을 등록한다.
- [토스페이먼츠 키 목록 조회](https://docs.meterengine.com/api-reference/toss-payments-credential-controller/토스페이먼츠-키-목록-조회.md): 선택한 환경에 저장한 토스페이먼츠 키를 mode 오름차순으로 돌려준다. 저장한 모드만 나온다. 시크릿 키 원문은 돌려주지 않고 마지막 네 자만 secret_key_last_four로 준다. verified_at과 updated_at은 KST(+09:00)로 나온다. status가 archived나 all이면 교체나 보관으로 물러난 이전 키를 현재 행 뒤에 물러난 시각 내림차순으로 붙이고, archived_at에 물러난 시각을 담는다. 이전 키는 새 결제에 다시 쓰이지 않는다.
- [청구 제외와 정정 이벤트 조회](https://docs.meterengine.com/api-reference/unbilled-event-controller/청구-제외와-정정-이벤트-조회.md): 미매칭 유형, 숫자가 아닌 값, 미래 시각과 음수 수량 이벤트를 센다. 음수 수량은 거절하거나 집계에서 빼지 않는다. 미래 시각은 cutoff_at 이상이며 시각이 지나면 집계에 들어간다. 수량 판정은 미터별이라 같은 이벤트가 여러 미터에 잡힐 수 있다.
- [고객별 월 사용량 조회](https://docs.meterengine.com/api-reference/billable-metric-usage-controller/고객별-월-사용량-조회.md): 미터마다 event_type이 같은 이벤트를 설정한 집계 방식으로 계산한다. 기간은 KST 기준의 달이다. occurred_at 2026-08-31T23:59:59+09:00 이벤트는 8월에, 2026-09-01T00:00:00+09:00 이벤트는 9월에 든다. 지금 이후 시각의 이벤트는 집계에 들지 않는다. 그 달 이벤트 중 집계 마감 시각(다음 달 1일 13:00 KST) 전에 서버가 받은(received_at) 것만 집계한다. 마감 뒤에 받은 그 달 이벤트는 저장되지만 집계와 청구에 들지 않는다. 모든 고객이 응답에 나오며,…
- [웹훅 엔드포인트 목록 조회](https://docs.meterengine.com/api-reference/webhook-endpoint-controller/웹훅-엔드포인트-목록-조회.md)
- [웹훅 엔드포인트 등록](https://docs.meterengine.com/api-reference/webhook-endpoint-controller/웹훅-엔드포인트-등록.md): 서명 비밀값은 이 응답에서만 한 번 돌려준다. 등록 한도는 도입사의 환경마다 10개다. 운영에서는 HTTPS와 공개 주소만 허용한다.
- [웹훅 엔드포인트 조회](https://docs.meterengine.com/api-reference/webhook-endpoint-controller/웹훅-엔드포인트-조회.md)
- [웹훅 엔드포인트 수정](https://docs.meterengine.com/api-reference/webhook-endpoint-controller/웹훅-엔드포인트-수정.md)
- [웹훅 엔드포인트 보관](https://docs.meterengine.com/api-reference/webhook-endpoint-controller/웹훅-엔드포인트-보관.md): 발송을 중지하고 비활성으로 보관한다. 기본 목록에서는 빠지지만 GET /v1/webhook-endpoints/{id}와 status=archived 목록으로 조회된다. 과거 전송 기록은 보존한다. 반복 요청은 204다.
- [웹훅 전송 기록 조회](https://docs.meterengine.com/api-reference/webhook-endpoint-controller/웹훅-전송-기록-조회.md)
- [실패한 웹훅 전송 재시도](https://docs.meterengine.com/api-reference/webhook-endpoint-controller/실패한-웹훅-전송-재시도.md): 실패한 전송을 같은 webhook-id로 다시 대기시킨다. 엔드포인트가 활성 상태여야 한다. 이전 시도 이력은 보존한다.
- [웹훅 엔드포인트 복원](https://docs.meterengine.com/api-reference/webhook-endpoint-controller/웹훅-엔드포인트-복원.md): 비활성 상태로 복원한다. 주소와 등록 한도를 확인하며 과거 전송 기록을 유지한다.
- [웹훅 시험 이벤트 발행](https://docs.meterengine.com/api-reference/webhook-endpoint-controller/웹훅-시험-이벤트-발행.md): 선택한 엔드포인트에 webhook_test를 발송 대기 상태로 만든다. 수신 여부는 전송 기록에서 확인한다.

## OpenAPI Specs

- [openapi](https://raw.githubusercontent.com/asm17-ms2/meterengine/main/backend/openapi.yaml)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.