업무 환경

업무 환경은 한 도입사 안에서 데이터를 나누는 범위입니다. 같은 도입사라도 테스트 환경에 만든 고객, 미터, 이벤트는 실제 환경에서 보이지 않습니다. 콘솔에서는 화면 위 ‘업무 환경’ 선택 상자로, API에서는 요청에 쓴 API 키로 환경이 정해집니다.

MeterEngine은 지금 미리 보기 단계라 테스트 환경에서 연동을 검증하는 용도로 씁니다. 자세한 내용은 MeterEngine 소개를 보세요.

업무 환경의 종류

화면 표기	요청 값	이 환경에서 발급하는 API 키	결제	쓰는 곳
테스트 환경	`test`	`me_test_`로 시작	테스트 결제만	연동을 만들고 검증할 때
실제 환경	`live`	`me_live_`로 시작	실결제만	실제 고객에게 청구할 때
기존 데이터	헤더 생략	쓰지 않습니다	아래 기존 데이터 절 참고	쓰지 않습니다

테스트 환경은 실제 환경과 데이터가 분리되고 실결제가 일어나지 않는 업무 환경입니다. 결제는 토스페이먼츠 테스트 키로만 이루어집니다. 다만 연습용 공간이 아니므로 보낸 이벤트는 지울 수 없고, 확정한 인보이스는 되돌릴 수 없으며, 등록한 웹훅 주소로 실제 요청이 나갑니다. 테스트 환경에서 발급한 API 키(me_test_)는 테스트 환경에 고정되어 실제 환경 데이터에 접근할 수 없습니다.

테스트 환경을 마음대로 지우고 다시 만드는 연습 공간으로 다루지 마세요. 테스트 환경에서 이벤트가 들어온 미터는 계산 기준을 바꿀 수 없고, 확정한 인보이스는 그대로 남습니다. 시험할 때는 시험 전용 고객, 미터 code, 이벤트 type을 따로 정해 쓰세요. 되돌릴 수 없는 일의 목록은 전체 흐름에 있습니다.

콘솔에서 업무 환경 고르기

로그인하면 화면 위 ‘업무 환경’이 ‘기존 데이터’로 열립니다. 새로 가입한 도입사의 기존 데이터에는 아무 자료가 없으니, 작업을 시작하기 전에 테스트 환경으로 바꿉니다.

업무 환경을 고른다

화면 위 ‘업무 환경’ 선택 상자에서 ‘테스트 환경’을 고릅니다.

전환을 확인한다

‘테스트 환경으로 전환할까요?’ 창에서 ‘전환’을 누릅니다. 지금 화면에 입력하던 값과 선택은 초기화되고, 보던 메뉴의 첫 화면이 새 업무 환경으로 다시 열립니다.

표시를 확인한다

화면 본문 위에 ‘테스트 환경입니다.‘로 시작하는 안내가 나오고, 주소에 environment=test가 붙어 있으면 테스트 환경입니다. 메뉴를 옮겨 다녀도 이 값은 유지됩니다.

주소에 environment가 없으면 기존 데이터로 열립니다. 로그인 화면에서 새로 로그인한 직후, 북마크나 주소 직접 입력으로 들어온 경우가 그렇습니다. 미터를 만들거나 키를 발급하기 전에 화면 위 ‘업무 환경’ 표시를 확인하세요.

실제 환경을 고르면 ‘업무 환경’ 선택 상자가 경고 색으로 바뀝니다. 실제 환경으로 바꿀 때도 같은 확인 창을 거칩니다.

API에서 업무 환경이 정해지는 방식

API 요청의 업무 환경은 요청에 쓴 API 키가 정합니다. 테스트 환경에서 발급한 키는 테스트 환경에, 실제 환경에서 발급한 키는 실제 환경에 고정되어 있어 X-MeterEngine-Environment 헤더를 따로 넣지 않아도 됩니다. 주소는 테스트 환경과 실제 환경이 같습니다.

헤더를 넣는다면 값은 test 또는 live이고 키의 환경과 같아야 합니다. 다르면 403 environment_mismatch로 거절됩니다.
그 밖의 값을 넣거나 헤더를 두 번 넣으면 400 validation_error로 거절됩니다.
응답 헤더 X-MeterEngine-Environment에 그 요청이 처리된 환경이 실립니다. 연동을 처음 붙일 때 이 값으로 키가 맞는지 확인하세요.

curl -i https://meterengine.com/v1/organization/environments \
  -H "Authorization: Bearer me_test_xxxxxxxx"

const response = await fetch("https://meterengine.com/v1/organization/environments", {
  headers: { Authorization: "Bearer me_test_xxxxxxxx" },
});
console.log(response.status, response.headers.get("x-meterengine-environment"));
console.log(await response.json());

GET /v1/organization/environments는 read 권한 키로 부를 수 있고, 도입사의 테스트 환경과 실제 환경 id를 돌려줍니다.

응답

HTTP/2 200
x-meterengine-environment: test

{
  "environments": [
    { "id": "5d2e7b1a-3c4f-4a8e-9b6d-1f0a2c3e4d5f", "mode": "test" },
    { "id": "a7c9e1b3-5d2f-4b6a-8c0e-2f4a6b8c0d1e", "mode": "live" }
  ]
}

테스트 환경 키에 X-MeterEngine-Environment: live를 붙이면 403으로 이렇게 거절됩니다.

403 응답 본문

{
  "code": "environment_mismatch",
  "message": "API 키의 환경과 요청 환경이 다릅니다"
}

콘솔 로그인으로 보내는 요청은 키가 없으므로 요청마다 X-MeterEngine-Environment 헤더로 환경을 고르고, 헤더가 없으면 기존 데이터를 씁니다. 도입사 서버의 연동은 API 키로 하므로 이 헤더를 신경 쓸 필요가 없습니다.

환경마다 따로인 것과 공통인 것

환경마다 따로
도입사 공통

고객과 고객 카드
사용량 이벤트, 수집 거절 기록
미터, 단가, 요금제
사용량 집계, 청구 예정액, 확정 인보이스
결제, 취소, 대사 결과
인보이스 조회 링크, 카드 등록 링크
API 키
토스페이먼츠 키
공급자 정보
웹훅 수신 주소와 발송 기록
업무 감사 기록과 진단 화면

같은 외부 고객 ID(external_id), 미터 code, transaction_id, Idempotency-Key 값을 환경마다 따로 쓸 수 있습니다. 테스트 환경에서 쓴 값을 실제 환경에서 다시 써도 충돌하지 않습니다.

테스트 환경에서 실제 환경으로 옮길 때

환경을 바꿔도 데이터는 복사되지 않습니다. 테스트 환경에서 만든 것은 실제 환경에서 처음부터 다시 만듭니다.

업무 환경을 실제 환경으로 바꾼다

콘솔 위 ‘업무 환경’에서 ‘실제 환경’을 고르고 ‘전환’을 누릅니다.

미터와 단가를 다시 만든다

테스트 환경과 같은 미터 code와 단가를 실제 환경에 다시 만듭니다. 순서는 전체 흐름의 준비 순서를 따릅니다.

고객을 다시 등록하고 새 id를 저장한다

실제 환경에 고객을 등록하면 테스트 환경과 다른 id가 나옵니다. 이벤트의 customer_id에는 실제 환경의 id를 넣어야 합니다. 테스트 환경의 id로 보내면 404 customer_not_found가 납니다. 고객 등록과 ID 대응

실제 환경 키를 발급해 서버에 넣는다

실제 환경에서 API 키를 발급하면 me_live_로 시작하는 키가 나옵니다. 도입사 서버의 키를 이 키로 바꿉니다. API 키 발급과 첫 호출

결제와 통보 설정을 다시 한다

토스페이먼츠 실결제 키, 공급자 정보, 웹훅 수신 주소를 실제 환경에 다시 등록합니다. 웹훅 수신 주소를 등록하면 새 서명 비밀값이 나오니 수신 서버의 값도 바꿉니다. 토스페이먼츠 상점 준비와 키 저장, 웹훅 받기 시작하기

도입사 서버에서 환경별 설정(API 키, 고객 id 대응표, 웹훅 서명 비밀값)을 한 묶음으로 관리하면 테스트 환경 값과 실제 환경 값이 섞이지 않습니다.

테스트 결제와 실결제의 차이는 테스트 결제와 실결제를 보세요.

기존 데이터

기존 데이터는 테스트 환경과 실제 환경이 나뉘기 전에 저장한 자료를 보존하는 범위입니다. 새로 가입한 도입사는 쓰지 않습니다. 콘솔에서 ‘기존 데이터’를 고르면 화면 본문 위에 ‘기존에 저장한 업무 데이터입니다.‘라는 안내가 나옵니다.

기존 데이터에서 API 키를 발급하지 마세요. 이때 ‘기존 키 구분’에서 고르는 대로 me_live_나 me_test_ 키가 나오지만, 이 키는 테스트 환경과 실제 환경 어느 쪽에도 접근하지 못하며 접두사가 데이터 격리를 뜻하지 않습니다. 이 키에 X-MeterEngine-Environment: test나 live를 붙이면 403 environment_mismatch로 거절됩니다.

기존 데이터에서만 되는 일

결제 모드 변경은 업무 환경이 ‘기존 데이터’일 때만 ‘도입사 설정’ 화면에서 할 수 있습니다. 테스트 환경은 테스트 결제, 실제 환경은 실결제로 고정되어 바꿀 필요가 없습니다. 테스트 결제와 실결제

기존 데이터의 자료를 테스트 환경이나 실제 환경으로 옮길 수 있나요

옮길 수 없습니다. 기존 데이터의 자료는 테스트 환경이나 실제 환경에 복사되거나 배정되지 않습니다. 필요한 고객, 미터, 단가는 쓸 환경에서 새로 만듭니다.

시작하기

개념

계정과 조직

인증

API 사용 기본

가격 설계

고객과 이벤트 연동

확인과 진단

청구 확정

결제 연동

웹훅

참고

업무 환경의 종류

콘솔에서 업무 환경 고르기

API에서 업무 환경이 정해지는 방식

환경마다 따로인 것과 공통인 것

테스트 환경에서 실제 환경으로 옮길 때

기존 데이터

다음에 읽을 페이지

API 키 발급과 첫 호출

시간 규칙

​업무 환경의 종류

​콘솔에서 업무 환경 고르기

​API에서 업무 환경이 정해지는 방식

​환경마다 따로인 것과 공통인 것

​테스트 환경에서 실제 환경으로 옮길 때

​기존 데이터

​다음에 읽을 페이지

API 키 발급과 첫 호출

시간 규칙

업무 환경의 종류

콘솔에서 업무 환경 고르기

API에서 업무 환경이 정해지는 방식

환경마다 따로인 것과 공통인 것

테스트 환경에서 실제 환경으로 옮길 때

기존 데이터

다음에 읽을 페이지