> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meterengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MeterEngine 소개

> MeterEngine이 맡는 일과 도입사가 할 일을 나누고 다음에 읽을 페이지를 고릅니다.

MeterEngine은 도입사 서비스에서 생긴 사용량 이벤트를 받아 고객별 월 청구액을 계산하고, 확정한 인보이스를 토스페이먼츠 카드 결제로 수납하는 사용량 기반 과금 서비스입니다. 이 가이드는 MeterEngine을 자기 서비스의 과금에 붙이는 도입사의 개발자와 운영자를 위한 문서입니다.

> [!NOTE]
>
> MeterEngine은 지금 미리 보기 단계로 운영합니다. [https://meterengine.com/signup](https://meterengine.com/signup) 에서 누구나 가입을 신청할 수 있고, MeterEngine 팀이 신청을 확인해 승인하면 로그인해 쓸 수 있습니다. 미리 보기 기간에는 테스트 환경에서 연동을 검증하는 용도로 쓰고, 실제 고객의 개인정보를 넣거나 실결제를 받는 일에는 쓰지 마세요. 가입 신청은 콘솔의 가입 화면에서 합니다.

## 접속 주소

콘솔은 [https://meterengine.com](https://meterengine.com) 이고, API는 같은 도메인의 `https://meterengine.com/v1/` 아래에 있습니다. 어느 업무 환경에 기록될지는 요청에 쓴 API 키가 정합니다. 자세한 내용은 [API 참조 읽는 법](https://docs.meterengine.com/api-reference/introduction.md)과 [업무 환경](https://docs.meterengine.com/concepts/environments.md)을 보세요.

## MeterEngine이 맡는 일

* **사용량 수집**: 도입사 서버가 보낸 이벤트를 저장합니다. 한 건씩(`POST /v1/events`) 또는 한 요청에 100건까지 묶어서(`POST /v1/event-batches`) 받고, 같은 `transaction_id`로 다시 온 이벤트는 새로 저장하지 않습니다. [사용량 이벤트 보내기](https://docs.meterengine.com/integration/events.md)
* **미터별 집계**: 이벤트의 `type`과 속성 값으로 청구할 수량을 뽑습니다. 합계, 이벤트 수, 고유 값 수, 최댓값, 백분위수 같은 집계 방식과 과금 단위, 반올림을 미터마다 정합니다. [미터 설계](https://docs.meterengine.com/pricing/meters.md)
* **월 단가와 청구 예정액**: 미터와 속성 조합마다 월 단위로 단가를 등록하면, 조회할 때마다 고객별 청구 예정액을 계산합니다. 청구 월은 한국 시간(KST) 기준 달력 월입니다. [단가 모델과 버전](https://docs.meterengine.com/pricing/price-models.md), [시간 규칙](https://docs.meterengine.com/concepts/time-rules.md)
* **인보이스 확정**: 고객별 청구 예정액을 인보이스로 확정해 세금을 포함한 금액을 고정합니다. 금액은 원 단위입니다. [인보이스 수동 확정](https://docs.meterengine.com/billing/finalize-invoices.md), [예정액, 확정액, 수납액](https://docs.meterengine.com/concepts/amounts.md)
* **카드 결제와 결과 확인**: 도입사가 저장한 토스페이먼츠 키로, 고객이 MeterEngine 카드 등록 화면에서 등록한 카드에 결제합니다. 결과가 확인되지 않은 결제를 다시 조회하고, 조건에 맞는 실패 결제를 자동으로 다시 시도하고, 매일 대사합니다. [결제 연동 한눈에 보기](https://docs.meterengine.com/payments/overview.md)
* **고객용 화면**: 고객이 인보이스를 보는 조회 화면과 카드를 등록하는 화면을 MeterEngine이 제공합니다. [고객에게 인보이스 보여 주기](https://docs.meterengine.com/payments/invoice-links.md), [고객 카드 등록 링크](https://docs.meterengine.com/payments/card-registration.md)
* **웹훅**: 결제 성공, 결제 실패, 결제 취소, 과금 제외 사용량을 도입사 서버로 통보합니다. 콘솔에서는 '처리 결과 통보'라고 부릅니다. [웹훅 받기 시작하기](https://docs.meterengine.com/webhooks/overview.md)

## 도입사가 할 일

* **가격 설계**: 미터를 만들고 단가와 요금제를 등록합니다. 미터와 단가를 먼저 만들고 이벤트를 보내세요. [전체 흐름](https://docs.meterengine.com/concepts/how-it-works.md)
* **고객 등록과 id 보관**: 고객을 등록하고 응답의 `id`(UUID)를 도입사 시스템의 고객 ID와 함께 저장합니다. 이벤트의 `customer_id`에는 이 `id`를 넣습니다. [고객 등록과 ID 대응](https://docs.meterengine.com/integration/customers.md)
* **이벤트 전송과 재전송**: 사용량이 생길 때 이벤트를 보내고, 응답을 받지 못하면 같은 `transaction_id`로 다시 보냅니다. [재전송 설계](https://docs.meterengine.com/integration/retries.md)
* **확정과 첫 결제 요청**: 달이 끝나면 인보이스를 확정하고, 확정한 인보이스마다 결제를 요청합니다. 확정해도 결제는 자동으로 시작되지 않습니다. [첫 결제 요청과 결과 확인](https://docs.meterengine.com/payments/charging.md)
* **링크 전달**: 인보이스 조회 링크와 카드 등록 링크를 만들어 고객에게 직접 전달합니다.
* **웹훅 수신**: 통보를 받을 주소를 등록하고, 받은 요청의 서명을 검증합니다. [웹훅 서명 검증](https://docs.meterengine.com/webhooks/verify-signatures.md)

## 지금 하지 않는 일

* **메일 발송**: MeterEngine은 메일을 보내지 않습니다. 가입 승인, 구성원 초대, 인보이스 확정 뒤 청구 안내, 인보이스 조회 링크와 카드 등록 링크 모두 메일로 나가지 않으니 필요한 안내와 링크는 도입사가 직접 전달합니다. 고객에게 `billing_email`을 등록해도 그 주소로 메일이 발송되지 않습니다.
* **전자세금계산서 발행**: MeterEngine은 전자세금계산서를 발행하지 않습니다. [공급자 정보](https://docs.meterengine.com/account/supplier.md)
* **SDK 배포**: MeterEngine은 SDK를 배포하지 않습니다. 이 가이드의 예시는 HTTP 요청(curl)과 그대로 옮겨 쓸 수 있는 짧은 코드 조각입니다. 어떤 언어든 HTTPS 요청과 HMAC-SHA256을 쓸 수 있으면 연동할 수 있습니다.

## 다음에 읽을 페이지

> [card] [빠른 시작](https://docs.meterengine.com/quickstart.md)
>
> 가입부터 테스트 환경에서 이벤트를 보내 청구 예정액을 확인하기까지 따라 합니다.

> [card] [전체 흐름](https://docs.meterengine.com/concepts/how-it-works.md)
>
> 이벤트에서 청구와 결제까지의 흐름과 되돌릴 수 없는 제약을 먼저 봅니다.

> [card] [업무 환경](https://docs.meterengine.com/concepts/environments.md)
>
> 테스트 환경, 실제 환경, 기존 데이터가 무엇을 나누는지 봅니다.

> [card] [API 키 발급과 첫 호출](https://docs.meterengine.com/authentication/api-keys.md)
>
> 서버 연동 키를 발급하고 첫 요청으로 연결을 확인합니다.

> [card] [사용량 이벤트 보내기](https://docs.meterengine.com/integration/events.md)
>
> 이벤트 형식과 응답, 묶어 보내기를 봅니다.

> [card] [결제 연동 한눈에 보기](https://docs.meterengine.com/payments/overview.md)
>
> 토스페이먼츠 키 저장부터 결제 요청까지의 순서를 봅니다.

> [card] [웹훅 받기 시작하기](https://docs.meterengine.com/webhooks/overview.md)
>
> 처리 결과 통보를 받는 방법을 봅니다.

> [card] [API 참조 읽는 법](https://docs.meterengine.com/api-reference/introduction.md)
>
> 엔드포인트별 요청과 응답 형식을 봅니다.

## 문의

가입 승인 요청과 문의는 GitHub 이슈로 받습니다: [https://github.com/asm17-ms2/meterengine/issues/new](https://github.com/asm17-ms2/meterengine/issues/new) (GitHub 계정이 필요합니다).

> [!WARNING]
>
> 이슈는 누구나 볼 수 있는 공개 게시물입니다. 이메일, 비밀번호, API 키, 토스페이먼츠 키, 고객 정보는 적지 마세요.

| 용도 | 제목 | 본문에 적을 것 |
| - | - | - |
| 가입 승인 요청 | `[가입 승인] 도입사 이름` | 신청한 날짜와 시각(KST) |
| API 문의 | `[문의] 한 줄 요약` | 요청한 시각, 응답의 `code`, 응답 헤더 `X-Request-ID`, 이벤트라면 `transaction_id` |
| 보안 문제 | `[보안 문의]` | 세부 내용은 적지 않습니다. 팀이 따로 연락할 방법을 이슈에 답합니다 |


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