> ## 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.

# API 참조 읽는 법

> API 참조의 접속 주소, 인증, 시험 화면 사용법, 참조에 싣지 않은 경로를 설명합니다.

이 탭의 엔드포인트 페이지는 MeterEngine 서버 코드에서 만든 API 명세로 생성됩니다. 요청과 응답의 필드 이름, 형식, 필수 여부를 확인할 때 씁니다. 처음 연동한다면 [빠른 시작](https://docs.meterengine.com/quickstart.md)을 먼저 따라 해 보세요.

MeterEngine은 지금 미리 보기 단계라 테스트 환경에서 연동을 검증하는 용도로 씁니다([MeterEngine 소개](https://docs.meterengine.com/index.md)).

## 접속 주소

MeterEngine 콘솔은 [https://meterengine.com](https://meterengine.com) 이고, API는 같은 도메인의 `https://meterengine.com/v1/` 아래에 있습니다.

이 참조의 모든 요청은 `https://meterengine.com` 으로 갑니다. 엔드포인트 경로는 모두 `/v1/` 로 시작하므로, 참조에 `GET /v1/customers` 라고 적혀 있으면 요청 주소는 `https://meterengine.com/v1/customers` 입니다. 기준 주소에 `/v1` 을 한 번 더 붙이지 마세요.

테스트 환경과 실제 환경은 주소가 같습니다. 어느 환경에 기록될지는 요청에 쓴 API 키가 정합니다. 테스트 환경에서 발급한 키(`me_test_` 로 시작)는 테스트 환경에, 실제 환경에서 발급한 키(`me_live_` 로 시작)는 실제 환경에 기록됩니다.

콘솔의 '기존 데이터'에서 발급한 키도 같은 접두사가 붙지만 어느 환경에도 속하지 않으니, 기존 데이터에서는 API 키를 발급하지 마세요([업무 환경](https://docs.meterengine.com/concepts/environments.md)).

## 인증

모든 요청의 `Authorization` 헤더에 API 키를 Bearer 값으로 넣습니다.

```http theme={null}
Authorization: Bearer me_test_xxxxxxxx
```

* 헤더가 없으면 401 `authentication_required`, 키가 틀렸거나 폐기 또는 만료된 키면 401 `invalid_credentials` 를 받습니다. 두 응답 모두 `WWW-Authenticate: Bearer` 헤더가 붙습니다.
* 참조의 설명에 로그인 세션이 함께 나오는 곳이 있습니다. 로그인 세션은 콘솔 화면이 쓰는 방식이고, 도입사 서버는 API 키로만 요청합니다.
* `X-MeterEngine-Organization-Id` 헤더는 콘솔 화면이 쓰는 헤더입니다. API 키로 요청할 때는 보내지 않습니다.

키 발급 방법은 [API 키 발급과 첫 호출](https://docs.meterengine.com/authentication/api-keys.md)에 있습니다.

### 연결 확인

**1. 키 없이 보내 본다**

키 없이 요청을 보내 401과 함께 `{"code":"authentication_required"}` 가 오면 주소가 맞습니다.

```bash theme={null}
curl -i https://meterengine.com/v1/customers
```

```http theme={null}
HTTP/2 401
content-type: application/json
www-authenticate: Bearer
x-request-id: 6a89dee4-32a4-4dba-9e76-20bd409acfbd

{"code":"authentication_required","message":"인증 정보가 없습니다"}
```

**2. 테스트 환경 키로 보낸다**

read(조회) 권한이 있는 테스트 환경 키로 고객 목록을 조회합니다. 고객을 아직 등록하지 않았다면 `customers` 가 빈 배열로 옵니다.

```bash curl theme={null}
curl -i https://meterengine.com/v1/customers \
  -H "Authorization: Bearer me_test_xxxxxxxx"
```

```javascript Node theme={null}
const response = await fetch("https://meterengine.com/v1/customers", {
  headers: { Authorization: "Bearer me_test_xxxxxxxx" },
});
console.log(response.status, response.headers.get("x-request-id"));
console.log(await response.json());
```

```http theme={null}
HTTP/2 200
content-type: application/json
x-meterengine-environment: test
x-request-id: 3f1d2c4b-8a7e-4f60-9b1a-2d5c7e9f0a13

{"customers":[]}
```

응답 헤더 `X-MeterEngine-Environment` 에 요청이 처리된 업무 환경이 나옵니다. 테스트 환경 키라면 `test` 입니다.

**3. 오류가 오면 code를 본다**

401이면 키 값과 `Bearer ` 접두사를 다시 확인합니다. 403 `permission_denied` 면 키에 필요한 권한이 없는 것이고, 403 `organization_not_active` 면 도입사가 아직 승인되지 않았거나 정지된 상태입니다([가입과 승인](https://docs.meterengine.com/account/signup.md)).

## 권한

엔드포인트 페이지에는 그 요청에 필요한 권한이 따로 표시되지 않습니다. 조회는 read, 고객 등록과 이벤트 전송은 ingest, 그 밖의 변경은 admin 권한이 필요합니다. 예외와 요청별 표는 [화면과 API, 권한](https://docs.meterengine.com/authentication/scopes.md)을 보세요.

API 키 관리, 토스페이먼츠 키 저장, 구성원 관리처럼 콘솔에 로그인한 상태에서만 되는 기능은 API 키로 부르면 거절됩니다. 이 기능들은 참조 목록에 보이지 않으며, 각 가이드 페이지에서 콘솔 절차로 안내합니다.

## 업무 환경

테스트 환경과 실제 환경에서 발급한 키는 그 업무 환경에 고정되어 `X-MeterEngine-Environment` 헤더를 따로 넣지 않아도 됩니다. 참조의 요청 입력란에도 이 헤더가 없습니다. 헤더를 넣을 때의 규칙과 거절되는 경우는 [업무 환경](https://docs.meterengine.com/concepts/environments.md)에 있습니다.

테스트 환경도 보낸 이벤트와 확정한 인보이스는 되돌릴 수 없습니다. 환경별로 따로인 것과 공통인 것은 [업무 환경](https://docs.meterengine.com/concepts/environments.md)에 있습니다.

## 시험 화면 사용

엔드포인트 페이지의 시험 화면에서 실제 요청을 보내고 응답을 볼 수 있습니다.

> [!WARNING]
>
> API 참조의 시험 화면에서 보낸 요청은 Mintlify 서버를 거쳐 MeterEngine으로 갑니다. 입력한 키도 Mintlify 서버를 지나갑니다. 시험 화면에는 테스트 환경 키(`me_test_` 로 시작)만 넣으세요. 실제 환경 키(`me_live_`)는 넣지 마세요.

**1. 시험용 키를 따로 발급한다**

콘솔 화면 위 '업무 환경'이 '테스트 환경'인지 확인한 뒤 'API 키와 통보' 화면에서 시험 전용 키를 발급합니다. 'API 권한'은 시험할 요청에 필요한 것만 고르세요. 키 원문은 발급 직후 한 번만 보이니 바로 비밀 저장소에 옮깁니다. 발급 절차는 [API 키 발급과 첫 호출](https://docs.meterengine.com/authentication/api-keys.md)에 있습니다.

**2. 시험용 고객과 미터를 쓴다**

시험 화면에서 보낸 요청은 테스트 환경에 실제로 기록됩니다. 테스트 환경에 보낸 이벤트는 지울 수 없으니 시험 전용 고객과 미터를 따로 만들어 쓰세요.

**3. 키를 넣고 보낸다**

엔드포인트 페이지의 인증 입력란에 테스트 환경 키를 넣고 요청을 보냅니다. 키는 `Authorization: Bearer` 헤더로 실립니다.

**4. 시험이 끝나면 키를 폐기한다**

'API 키와 통보' 화면에서 시험에 쓴 키를 '키 폐기'로 폐기하세요. 폐기한 키로 보낸 요청은 401 `invalid_credentials` 를 받습니다.

## 참조에 싣지 않은 경로

API 참조에는 API 키로 부를 수 있는 기능을 싣습니다. 로그인, 가입, 초대 수락처럼 콘솔이 내부에서 부르는 경로와 MeterEngine 운영자 전용 경로, 카드 등록 화면과 인보이스 조회 화면이 쓰는 공개 경로, 콘솔 입력란의 자동 완성처럼 화면을 돕는 경로는 싣지 않습니다. 도입사 서버에서는 이 경로들을 직접 부르지 말고 아래 표의 페이지가 안내하는 방법을 쓰세요.

| 하려는 일 | 볼 곳 |
| - | - |
| 가입과 로그인 | [가입과 승인](https://docs.meterengine.com/account/signup.md) |
| 구성원 초대와 수락 | [구성원과 권한](https://docs.meterengine.com/account/members.md) |
| API 키 발급, 권한 변경, 폐기 | [API 키 발급과 첫 호출](https://docs.meterengine.com/authentication/api-keys.md), [키 교체, 권한 변경, 폐기](https://docs.meterengine.com/authentication/key-rotation.md) |
| 토스페이먼츠 키 저장과 결제 결과 수신 주소 | [토스페이먼츠 상점 준비와 키 저장](https://docs.meterengine.com/payments/toss-setup.md) |
| 고객의 카드 등록 | [고객 카드 등록 링크](https://docs.meterengine.com/payments/card-registration.md) |
| 고객에게 인보이스 보여 주기 | [고객에게 인보이스 보여 주기](https://docs.meterengine.com/payments/invoice-links.md) |
| 실패한 결제를 고객이 다시 결제하기 | [결제 실패와 재시도](https://docs.meterengine.com/payments/retries.md) |

자체 서비스 화면에 청구 내용을 보여 주려면 도입사 서버에서 read 권한 API 키로 `GET /v1/invoices/{id}` 를 부릅니다. 자세한 내용은 [고객에게 인보이스 보여 주기](https://docs.meterengine.com/payments/invoice-links.md)를 보세요.

## 가이드와 참조가 다를 때

API 참조는 서버 코드에서 만들어집니다. 가이드의 예시와 API 참조의 필드 이름, 형식, 필수 여부가 다르면 API 참조를 따르세요.

목록의 `page` 는 경로마다 시작 번호가 다릅니다. 자원의 `/search` 는 1부터 세고, 이벤트 목록과 수집 거절, 이벤트 매핑 진단, 웹훅 전송 기록은 0부터 셉니다([서버 조회와 CSV 내보내기](https://docs.meterengine.com/reference/search-and-export.md)).

> [!NOTE]
>
> 참조에서 성공 응답의 형식이 `*/*` 로 표시된 곳이 있습니다. 실제 응답은 JSON(`application/json`)이고, 내보내기 경로만 CSV(`text/csv`)입니다.

> [!NOTE]
>
> 엔드포인트 페이지의 오류 목록에는 모든 요청에 생길 수 있는 오류가 다 실려 있지 않습니다. 예를 들어 업무 환경이 맞지 않을 때의 403 `environment_mismatch` 는 엔드포인트 페이지의 오류 목록에 나오지 않습니다. 오류 처리는 페이지에 적힌 목록이 아니라 응답의 `code` 로 나누세요. 403 `consent_required` 는 콘솔 로그인에만 해당하며 API 키 요청에는 오지 않습니다.

## 함께 볼 페이지

> [card] [오류 응답과 X-Request-ID](https://docs.meterengine.com/api-basics/errors.md)
>
> 오류는 `code` 로 분기하고, 문의할 때는 응답 헤더 `X-Request-ID` 를 남깁니다.

> [card] [요청 한도와 429](https://docs.meterengine.com/api-basics/rate-limits.md)
>
> 한도를 넘으면 429를 받으니 `Retry-After` 만큼 기다렸다가 다시 보냅니다.

> [card] [멱등 규칙](https://docs.meterengine.com/api-basics/idempotency.md)
>
> 같은 `transaction_id` 로 다시 보내면 처음 것이 남습니다.

> [card] [화면과 API, 권한](https://docs.meterengine.com/authentication/scopes.md)
>
> 요청별 필요 권한과 콘솔 로그인으로만 되는 기능을 정리했습니다.


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