서비스와 계정
| 용어 | 콘솔 표기 | API 값 | 뜻 | 자세히 |
|---|---|---|---|---|
| 도입사 | 도입사 | 경로의 organization | MeterEngine을 도입해 자기 서비스의 사용량 과금에 쓰는 회사 | MeterEngine 소개 |
| 고객 | 고객 | customer | 도입사가 사용료를 청구하는 상대 | MeterEngine 소개 |
| 미리 보기 단계 | 지금 MeterEngine의 운영 단계. 테스트 환경에서 연동을 검증하는 용도로 씁니다 | MeterEngine 소개 | ||
| 도입사 상태 | 승인 대기, 사용 중, 가입 거절, 이용 정지 | pending, active, rejected, suspended | 도입사를 쓸 수 있는지 나타내는 상태. MeterEngine 운영자가 바꿉니다 | 가입과 승인 |
| 필수 동의 | 이용 안내, 개인정보 처리 안내 | terms_of_service, privacy_policy | 가입, 초대 수락, 첫 로그인 때 체크해야 하는 안내. 지금 안내는 검증용이며 정식 약관이 아닙니다 | 가입과 승인 |
| 도입사 id | GET /v1/organization 응답의 id | 도입사마다 하나인 UUID. 업무 환경과 관계없이 같고 토스페이먼츠 웹훅 주소에 넣습니다 | 토스페이먼츠 상점 준비와 키 저장 | |
| 공급자 정보 | 공급자 정보: 사업자등록번호, 대표자명, 사업장 주소 | business_registration_number, representative_name, business_address | 도입사의 사업자 정보. 업무 환경마다 저장하며 개요 화면의 준비 목록 표시에만 쓰입니다 | 공급자 정보 |
| 대표관리자 | 대표관리자 | owner | 모든 업무와 사용자, 초대를 관리하는 역할. 가입을 신청한 사람이 처음 대표관리자가 됩니다 | 구성원과 권한 |
| 관리자 | 관리자 | 역할 admin | 전체 관리 (admin) 권한으로 모든 업무를 하지만 사용자와 초대는 관리하지 못하는 역할 | 구성원과 권한 |
| 일반 사용자 | 일반 사용자 | member | 조회 (read), 수집 (ingest) 가운데 받은 권한 안의 업무만 하는 구성원 | 구성원과 권한 |
| 초대 링크 | 초대 링크 만들기, 초대 링크 발급 | me_invite_로 시작하는 토큰 | 지정한 이메일로 48시간 안에 한 번 수락할 수 있는 참여 링크. 메일 없이 직접 전달합니다 | 구성원과 권한 |
| 초대 상태 | 초대 대기, 수락 완료, 초대 취소, 만료 | pending, accepted, revoked, expired | 초대 이력의 상태 | 구성원과 권한 |
| 계정 직접 생성 | 계정 직접 생성, 사용자 계정 생성 | 대표관리자가 초기 비밀번호로 계정을 만들고, 본인이 첫 로그인 때 비밀번호를 바꾸고 동의하는 방법 | 구성원과 권한 | |
| 소속 보관 | 소속 보관, 접근 중단하고 보관 | 구성원의 도입사 접근을 멈추는 것. 기록은 남고 다시 초대하면 복원됩니다 | 구성원과 권한 | |
| 도입사 선택 | 도입사 선택, 접근할 도입사, 도입사로 이동 | 여러 도입사에 속한 계정이 작업할 도입사를 바꾸는 화면 | 구성원과 권한 |
업무 환경
| 용어 | 콘솔 표기 | API 값 | 뜻 | 자세히 |
|---|---|---|---|---|
| 업무 환경 | 업무 환경 | X-MeterEngine-Environment 헤더 | 한 도입사 안에서 데이터를 나누는 범위. 콘솔은 화면 위 선택 상자로, API는 키로 정합니다 | 업무 환경 |
| 테스트 환경 | 테스트 환경 | test | 실제 환경과 데이터가 분리되고 실결제가 없는 업무 환경. 보낸 이벤트, 확정, 웹훅은 실제로 일어나고 되돌릴 수 없습니다 | 업무 환경 |
| 실제 환경 | 실제 환경 | live | 실제 고객에게 실결제로 청구하는 업무 환경 | 업무 환경 |
| 기존 데이터 | 기존 데이터 | 웹훅 environment 값 legacy | 테스트 환경과 실제 환경이 나뉘기 전의 자료를 보존하는 범위. 로그인 직후 기본으로 열리며 새 도입사는 쓰지 않습니다 | 업무 환경 |
| 기존 키 구분 | 기존 키 구분 | mode | 기존 데이터에서 키를 발급할 때만 보이는 입력란. 데이터 격리를 뜻하지 않습니다 | 업무 환경 |
인증과 권한
| 용어 | 콘솔 표기 | API 값 | 뜻 | 자세히 |
|---|---|---|---|---|
| API 키 | 서버 연동 키, API 키 발급 | Authorization: Bearer 헤더의 값 | 도입사 서버가 MeterEngine API를 부를 때 쓰는 비밀값. 발급한 업무 환경에 고정됩니다 | API 키 발급과 첫 호출 |
| 테스트 환경 키 | ’API 키 구분’ 열의 테스트 키 | me_test_ 접두사, mode test | 테스트 환경에서 발급해 테스트 환경에 고정된 API 키. API 참조의 시험 화면에는 이 키만 넣습니다 | API 키 발급과 첫 호출 |
| 실제 환경 키 | ’API 키 구분’ 열의 운영 키 | me_live_ 접두사, mode live | 실제 환경에서 발급해 실제 환경에 고정된 API 키 | API 키 발급과 첫 호출 |
| 키 원문 | 비밀값, 비밀값 복사 | secret | 발급 직후 한 번만 보이는 키 전체 값 | API 키 발급과 첫 호출 |
| 끝 네 글자 | 끝 네 글자 | last_four | 키를 알아보는 데 쓰는 원문의 끝 네 글자 | API 키 발급과 첫 호출 |
| 키 상태 | 사용 중, 폐기됨, 만료됨 | active, revoked, expired | API 키를 지금 쓸 수 있는지 나타내는 상태 | API 키 발급과 첫 호출 |
| 분당 요청 한도 | 분당 요청 한도, 목록 열 ‘분당 한도’(빈 값은 ‘무제한’) | rate_limit_per_minute | 키마다 발급할 때 정하는 분당 요청 수 상한. 비우면 제한이 없습니다 | 요청 한도와 429 |
| API 권한 | API 권한 | scopes | API 키에 준 권한. 값은 read, ingest, admin입니다 | 화면과 API, 권한 |
| 업무 권한 | 업무 권한 | scopes | 콘솔 구성원에게 준 권한. API 키 권한과 같은 값을 쓰지만 따로 관리합니다 | 화면과 API, 권한 |
| read(조회) | 조회 (read) | read | 업무 데이터를 조회하는 권한 | 화면과 API, 권한 |
| ingest(수집) | 수집 (ingest) | ingest | 고객을 등록하고 이벤트를 보내는 권한 | 화면과 API, 권한 |
| admin(전체 관리) | 전체 관리 (admin) | admin | read와 ingest를 포함해 모든 데이터를 바꾸는 권한 | 화면과 API, 권한 |
| 콘솔 로그인 | 로그인 | 사람이 콘솔에서 쓰는 인증. 로그인한 때부터 12시간 유지됩니다 | 화면과 API, 권한 | |
| 키 교체 | 교체할 기존 키 | replaced_api_key_id | 새 키를 발급하면서 고른 기존 키가 24시간 뒤 만료되게 하는 것. 분당 한도를 바꿀 때도 씁니다 | 키 교체, 권한 변경, 폐기 |
| 만료 시각 | 만료 시각 | expires_at | 교체된 키가 더는 쓰이지 않게 되는 시각 | 키 교체, 권한 변경, 폐기 |
| 키 권한 변경 | 키 권한 변경, 키 권한 저장 | 키 원문을 그대로 두고 권한만 바꾸는 것 | 키 교체, 권한 변경, 폐기 | |
| 키 폐기 | 키 폐기, 폐기 시각 | revoked_at | 키를 즉시 쓸 수 없게 하는 것. 되돌릴 수 없습니다 | 키 교체, 권한 변경, 폐기 |
API 사용 기본
| 용어 | 콘솔 표기 | API 값 | 뜻 | 자세히 |
|---|---|---|---|---|
| 기준 주소 | https://meterengine.com | API 요청이 가는 주소. 경로가 /v1/로 시작하므로 기준 주소에 /v1을 붙이지 않습니다 | API 참조 읽는 법 | |
| 오류 code | 오류 응답 본문의 code | 오류 종류를 나타내는 값. 연동 코드의 분기는 이 값으로 합니다 | 오류 응답과 X-Request-ID | |
| 요청 ID | 감사 요청 ID(‘수집 거절’ 열) | X-Request-ID 응답 헤더, request_id 필드 | 모든 /v1/ 응답에 붙는 요청 UUID. 감사 기록, 저장된 이벤트, 수집 거절 기록의 request_id와 같은 값이며 문의할 때 남깁니다 | 오류 응답과 X-Request-ID |
| 감사 기록 | 감사 기록, 행동 또는 대상 검색 | GET /v1/audit-logs(콘솔 로그인 전용) | API 요청 결과와 업무 변경이 남는 콘솔 화면. 업무 환경마다 따로 보이고 이벤트 수집 요청은 남지 않습니다 | 오류 응답과 X-Request-ID |
| authentication_required | 401 authentication_required | Authorization 헤더가 없습니다 | API 참조 읽는 법 | |
| invalid_credentials | 401 invalid_credentials | 키가 틀렸거나 폐기 또는 만료됐습니다 | API 참조 읽는 법 | |
| environment_mismatch | 403 environment_mismatch | 키의 업무 환경과 요청 헤더의 업무 환경이 다릅니다 | 업무 환경 | |
| consent_required | 403 consent_required | 콘솔에 로그인한 사용자가 필수 안내에 동의하지 않았습니다. API 키 요청에는 오지 않습니다 | API 참조 읽는 법 | |
| Retry-After | Retry-After 응답 헤더 | 429 응답에 붙는, 다시 보내기 전에 기다릴 초(1 이상의 정수) | 요청 한도와 429 | |
| 멱등 | 같은 요청을 다시 보내도 결과가 한 번만 반영되는 성질 | 멱등 규칙 | ||
| 재시도 키 | Idempotency-Key 요청 헤더 | 고객 등록, 미터 등록, 결제 취소를 안전하게 다시 보내려고 요청에 붙이는 값 | 멱등 규칙 | |
| 재전송 응답 표시 | Idempotency-Replayed: true 응답 헤더 | 같은 Idempotency-Key의 첫 응답을 다시 돌려줄 때 붙는 헤더. 고객 등록과 미터 등록에만 붙습니다 | 멱등 규칙 | |
| 시험 화면 | API 참조 페이지에서 실제 요청을 보내 보는 입력 화면. 요청과 키가 Mintlify 서버를 거칩니다 | API 참조 읽는 법 |
가격 설계
| 용어 | 콘솔 표기 | API 값 | 뜻 | 자세히 |
|---|---|---|---|---|
| 미터 | 미터 | 경로 /v1/billable-metrics | 어떤 type의 이벤트에서 어떤 값을 어떻게 모아 한 달 청구 수량으로 만들지 정한 규칙 | 미터 설계 |
| 미터 code | 코드 | code | 미터를 가리키는 값. 업무 환경마다 유일하고 등록한 뒤 바꿀 수 없습니다 | 미터 설계 |
| 이벤트 타입 | 이벤트 타입 | 미터의 event_type, 이벤트의 type | 미터가 집계할 이벤트를 고르는 값. 이벤트의 type과 글자까지 같아야 집계됩니다 | 미터 설계 |
| 집계 방식 | 집계 함수 | aggregation: sum, count, count_distinct, min, max, avg, first, last, median, percentile | 한 달, 한 고객, 한 조합의 이벤트 값을 모으는 방식 | 미터 설계 |
| 집계 대상 속성 | 집계 대상 속성 | target_property | 이벤트 properties에서 집계할 키. count에는 쓰지 않습니다 | 미터 설계 |
| 과금 단위 크기 | 과금 단위 크기 | unit_size | 집계량을 나누는 양수. 한 달 조합 집계 결과에 한 번 적용합니다 | 미터 설계 |
| 반올림 방식 | 반올림 방식: 추가 반올림 없음, 올림, 내림, 반올림 | rounding_mode: none, ceil, floor, round, 자릿수 rounding_precision | 단위 크기로 나눈 수량에 적용하는 반올림과 소수 자릿수 | 미터 설계 |
| 차원 키 | 차원 키 | dimension_properties | 단가를 가르는 이벤트 properties 키의 배열 | 차원과 속성 조합 |
| 조합 | 속성 조합 | dimension_values | 차원 키마다 이벤트에서 뽑은 값의 묶음. 금액은 조합마다 그 조합의 단가로 계산합니다 | 차원과 속성 조합 |
| 단가 | 단가 버전 등록, 과금 수량 1당 단가 (원) | 경로 /v1/billable-metrics/{code}/price-rates, unit_price | 과금 수량 1당 금액. 월 단위 버전으로 등록합니다 | 단가 모델과 버전 |
| 단일 단가 | 단일 단가 | per_unit | 청구 수량 전체에 한 단가를 곱하는 모델 | 단가 모델과 버전 |
| 누진 구간 | 누진 구간, 라인 ‘구간 N’ | graduated, 라인 line_type graduated_tier와 tier_index | 수량을 구간마다 잘라 구간 단가를 곱해 더하는 모델. 구간마다 라인이 생깁니다 | 단가 모델과 버전 |
| 총량 구간 | 총량 구간, 라인 ‘총량 단가’ | volume, 라인 line_type volume | 전체 수량이 속한 구간 하나의 단가를 수량 전체에 곱하는 모델 | 단가 모델과 버전 |
| 끝 수량 | 끝 수량, 상한 없음 | tiers[].up_to | 구간의 상한. 그 값을 포함하고 마지막 구간은 null입니다 | 단가 모델과 버전 |
| 적용 시작 월, 적용 종료 월 | 적용 시작 월, 적용 종료 월 | effective_from, effective_until (KST, YYYY-MM) | 단가나 요금제 버전이 적용되는 첫 달과 적용되지 않기 시작하는 달. 종료 월은 포함하지 않습니다 | 단가 모델과 버전 |
| 단가 버전 | 단가 버전 등록 | 단가 이력의 각 항목 | 월 단위로 적용 기간을 정한 단가. 그 달에 걸리는 버전 가운데 시작 월이 가장 늦은 것을 씁니다 | 단가 모델과 버전 |
| 공통 단가와 고객 단가 | 적용 대상(모든 고객 공통 또는 고객), 공통 단가 적용 | customer_id(없으면 공통) | 같은 조합에 고객 단가가 있으면 그것을, 없으면 공통 단가를 씁니다 | 단가 모델과 버전 |
| 요금제 | 기본료와 최소 사용료 | 경로 /v1/price-plans | 사용료 위에 더하는 월 기본료와 월 최소 사용료의 월 단위 버전 | 기본료와 최소 사용료 |
| 월 기본료 | 월 기본료 (원), 라인 ‘기본료’ | base_fee, 라인 line_type base_fee | 그 달 사용량이 있는 고객에게 붙는 고정 금액. 10원 미만은 버립니다 | 기본료와 최소 사용료 |
| 월 최소 사용료 | 월 최소 사용료 (원) | minimum_amount | 사용료 합이 이 금액보다 작으면 차액을 조정 라인으로 더하는 기준 금액 | 기본료와 최소 사용료 |
| 최소 사용료 조정 | 최소 사용료 조정 | 라인 line_type minimum_adjustment | 월 최소 사용료와 사용료 합의 차액으로 더하는 라인 | 기본료와 최소 사용료 |
| 공통 요금제와 고객 요금제 | 공통 요금제 적용, 모든 고객 공통, 적용 대상의 고객 선택 | customer_id가 null이면 공통, 고객 id면 그 고객 전용 | 고객 요금제가 있는 고객은 그것을, 없는 고객은 공통 요금제를 씁니다 | 기본료와 최소 사용료 |
| 정확 청구 수량 | quantity_numerator, quantity_denominator | 금액과 구간 판정에 쓴 수량의 분자와 분모. quantity는 표시용입니다 | 금액 계산 따라가기 | |
| 보관 | 보관, 고객 보관, 단가 버전 보관, 요금제 버전 보관, 보관됨 | DELETE 요청, archived_at, status=archived | 지우지 않고 사용을 멈추는 것. 고객은 바로, 미터와 단가와 요금제 버전은 다음 달부터 효력이 생깁니다 | 바꾸기, 보관, 복원 |
| 복원 | 고객 복원, 미터 복원, 단가 버전 복원, 요금제 버전 복원 | POST .../restorations | 보관을 되돌리는 것. 고객은 바로, 미터는 다음 달부터 다시 집계하고, 단가와 요금제 버전은 보관 효력이 시작되기 전에만 됩니다 | 바꾸기, 보관, 복원 |
| 보관 효력 시작 월 | ’YYYY-MM부터 중단’ | archived_from | 보관한 단가나 요금제 버전이 적용을 멈추는 달 | 바꾸기, 보관, 복원 |
| 미터 집계 중단 월, 재개 월 | inactive_from, active_from | 보관한 미터가 집계를 멈추는 달과 복원한 뒤 다시 집계하는 달 | 바꾸기, 보관, 복원 |
고객과 이벤트 연동
| 용어 | 콘솔 표기 | API 값 | 뜻 | 자세히 |
|---|---|---|---|---|
| 고객 id | 고객 상세 화면 주소의 /customers/ 뒤 값 | 고객의 id, 이벤트의 customer_id | MeterEngine이 고객 등록 때 만드는 UUID. 이벤트의 customer_id에 넣습니다 | 고객 등록과 ID 대응 |
| 외부 고객 ID | 외부 고객 ID | external_id | 도입사 시스템에서 고객을 가리키는 값. 업무 환경 안에서 유일하며 중복 등록을 막고 고객을 다시 찾는 데 씁니다 | 고객 등록과 ID 대응 |
| 청구 이메일 | 청구 이메일 | billing_email | 고객에 저장하는 이메일. MeterEngine은 이 주소로 메일을 보내지 않습니다 | 고객 등록과 ID 대응 |
| 고객 보관 | 고객 보관, 고객 복원 | archived_at, 409 customer_archived | 고객의 새 이벤트를 막는 상태. 지난 기록은 남고 복원할 수 있습니다 | 고객 등록과 ID 대응 |
| 이벤트 | POST /v1/events | 고객이 서비스를 쓴 사실 하나. transaction_id, customer_id, type, properties, timestamp로 보냅니다 | 사용량 이벤트 보내기 | |
| transaction_id | 전송 ID | transaction_id | 도입사가 이벤트마다 붙이는 고유 값. 업무 환경 안에서 유일해야 하고 같은 값으로 다시 보내면 처음 것이 남습니다 | 사용량 이벤트 보내기 |
| 중복 | 단건 duplicate: true, 묶음 result duplicate | 같은 transaction_id가 이미 저장돼 있어 저장하지 않은 결과. 성공으로 처리합니다 | 멱등 규칙 | |
| 묶어 보내기 | POST /v1/event-batches, results[].result: stored, duplicate, rejected | 한 요청에 1건부터 100건까지 이벤트를 보내고 원소마다 결과를 받는 방식 | 사용량 이벤트 보내기 | |
| 발생 시각 | 발생 시각 (KST) | 요청의 timestamp, 조회 응답의 occurred_at | 이벤트가 일어난 시각. 청구 월을 정합니다 | 시간 규칙 |
| 수신 시각 | 수신 시각 (KST) | received_at | MeterEngine이 이벤트를 받은 시각. 서버가 정하며 집계 마감 판정에 씁니다 | 시간 규칙 |
| 청구 월 | 청구 월 | month (YYYY-MM) | KST 달력 월 | 시간 규칙 |
| 집계 마감 | 집계 마감(마감 전), 집계 기준(마감 뒤) | 인보이스의 cutoff_at | 그 달 사용량을 받는 마지막 시각, 다음 달 1일 13:00 KST. 그 전에 받은 그 달 이벤트만 청구됩니다 | 시간 규칙 |
| cutoff_at | 집계 마감, 집계 기준 | cutoff_at | 인보이스에서는 금액에 든 이벤트의 받은 시각 상한, 청구 제외 사용량에서는 발생 시각 상한 | 시간 규칙 |
| 상계 이벤트 | 집계가 sum인 미터에서 잘못 보낸 양을 빼려고 같은 고객, type, 차원 값으로 보내는 음수 값 이벤트 | 사용량 이벤트 보내기 | ||
| 아웃박스 | 보낼 이벤트를 사용 기록과 같은 트랜잭션으로 도입사 데이터베이스에 먼저 저장하고 따로 보내는 방식 | 재전송 설계 |
확인과 진단
| 용어 | 콘솔 표기 | API 값 | 뜻 | 자세히 |
|---|---|---|---|---|
| 수집 로그 | 수집 로그 | GET /v1/events, GET /v1/events/lookup | 저장된 사용량 이벤트 원본을 발생 시각, 수신 시각과 함께 보는 콘솔 화면 | 보낸 데이터 확인하기 |
| 수집 확인과 정정 | 수집 확인과 정정 | GET /v1/unbilled-events | ’사용량’ 화면에서 청구에서 빠지거나 확인이 필요한 이벤트를 항목별 건수로 보여 주는 구역 | 보낸 데이터 확인하기 |
| 청구 제외 집계 항목 | 미터와 연결되지 않은 유형, 집계할 수 없는 속성, 미래 시각의 이벤트, 음수 수량의 이벤트 | unmatched_type, non_numeric_value, future_timestamp, negative_quantity | ’수집 확인과 정정’과 unbilled_usage_detected 웹훅이 세는 항목 | 보낸 데이터 확인하기 |
| 수집 거절 | 수집 거절 | GET /v1/event-rejections/search | 고객 연결이나 수집 조건 때문에 저장하지 못한 이벤트의 기록. 원문은 남지 않습니다 | 이벤트가 청구에 안 보일 때 |
| 거절 사유 | 고객을 찾을 수 없음, 보관된 고객, 수집 가능 기간 초과, 요청 항목 확인 필요 | customer_not_found, customer_archived, event_too_old, validation_error | 수집 거절 기록의 사유 | 이벤트가 청구에 안 보일 때 |
| 거절 기록 월 | 거절 기록 월 | 수집 거절 검색의 month | 이벤트가 일어난 달이 아니라 거절을 기록한 KST 달 | 이벤트가 청구에 안 보일 때 |
| 이벤트 매핑 진단 | 이벤트 매핑 진단 | GET /v1/event-issues/search | 저장된 이벤트가 미터, 집계 수량, 단가와 이어지지 않은 문제를 지금 정의로 다시 진단한 결과 | 이벤트가 청구에 안 보일 때 |
| 매핑 문제 종류 | 연결할 미터 없음, 집계할 수량 확인 필요, 적용 단가 없음 | unknown_event_type, invalid_target_property, unpriced_usage | 이벤트의 type을 세는 미터가 없거나, 세는 속성이 없거나 형식이 맞지 않거나, 그 조합에 단가가 없는 문제 | 이벤트가 청구에 안 보일 때 |
| 단가 없는 사용량 | 단가 없는 사용량, 적용 단가 없음 | unpriced_usages | 같은 조합의 단가가 없어 라인과 금액에서 빠진 사용량. 청구되지 않습니다 | 차원과 속성 조합 |
| 음수 합계 | 음수 합계 | negative_usages | 집계한 값이 음수라 0원으로 보고 라인에서 뺀 조합 | 예정액, 확정액, 수납액 |
| 조건 전체 CSV 내보내기 | 조건 전체 CSV 내보내기 | GET .../export | 화면에 건 조건의 전체 결과를 최대 10,000행 CSV로 받는 기능 | 서버 조회와 CSV 내보내기 |
| 원본 속성 포함 | 원본 속성 포함 (JSON) | include_properties=true | 이벤트 CSV에 properties JSON 열을 붙이는 선택 | 서버 조회와 CSV 내보내기 |
| total_unfiltered | total_unfiltered | 검색 조건을 적용하기 전 지금 업무 환경의 전체 건수 | 서버 조회와 CSV 내보내기 |
금액과 청구 확정
| 용어 | 콘솔 표기 | API 값 | 뜻 | 자세히 |
|---|---|---|---|---|
| 청구 예정액 | 청구 예정액 | GET /v1/invoices/draft의 total_amount, 개요의 draft_supply_amount | 아직 확정하지 않은 고객의 세전 공급가액. 조회할 때마다 다시 계산합니다 | 예정액, 확정액, 수납액 |
| 확정 청구액 | 확정 청구액 | finalized_total_amount | 확정한 인보이스 합계(세액 포함)의 합 | 예정액, 확정액, 수납액 |
| 공급가액 | 공급가액 | supply_amount | 세액을 뺀 확정 금액 | 예정액, 확정액, 수납액 |
| 세액 | 세액 | tax_amount | 공급가액의 10% | 예정액, 확정액, 수납액 |
| 합계 | ’확정 인보이스’ 고객 줄의 금액, ‘수납과 취소’의 청구액 | 인보이스 total_amount, 결제 amount | 공급가액에 세액을 더한 금액. 결제하는 금액입니다 | 예정액, 확정액, 수납액 |
| 결제 대기액 | 결제 대기액 | 개요의 outstanding_amount | 결제 전, 결과 확인 중, 결제 실패인 인보이스의 청구액 합 | 예정액, 확정액, 수납액 |
| 순수납액 | 순수납액 | collected_amount | 결제가 끝난 인보이스의 청구액에서 취소액을 뺀 합 | 예정액, 확정액, 수납액 |
| 취소액 | 취소액 | canceled_amount | 결제를 취소한 금액의 합. 인보이스 금액은 바뀌지 않습니다 | 예정액, 확정액, 수납액 |
| 라인 | 고객 조회 화면의 청구 항목 | lines[], line_type | 고객, 미터, 조합(구간)마다 한 줄인 금액과 기본료, 최소 사용료 조정 줄. 줄마다 10원 미만을 버립니다 | 예정액, 확정액, 수납액 |
| 청구 검토 | 청구 검토(화면 제목 ‘청구 예정액 - YYYY년 M월’) | 청구 예정액을 보고 확정하는 콘솔 화면 | 인보이스 수동 확정 | |
| 확정 | 월 전체 확정 | POST /v1/invoices?month=YYYY-MM | 한 달의 청구 예정액을 고객마다 인보이스로 굳히는 일. 되돌릴 수 없고 결제를 자동으로 시작하지 않습니다 | 인보이스 수동 확정 |
| 확정 상태 | 확정 전 (draft), 확정됨 (finalized) | ‘청구 검토’ 화면의 달 상태 표시 | 인보이스 수동 확정 | |
| 확정 결과 수 | finalized_count, failed_count | 이번 확정 호출로 새로 확정한 인보이스 수와 확정하지 못한 고객 수. 같은 달로 다시 부르면 실패한 고객을 다시 시도합니다 | 인보이스 수동 확정 | |
| finalized_at | finalized_at | 인보이스를 확정한 시각 | 인보이스 수동 확정 | |
| 확정 인보이스 | 확정 인보이스 | GET /v1/invoices | 확정된 인보이스와 그 목록 화면 | 인보이스 수동 확정 |
| 인보이스 번호 | 청구서 번호 | invoice_number | 고객에게 보여 주는 번호(예: ME-202610-00000012). 세금계산서나 영수증 번호가 아닙니다 | 확정 뒤 바뀌는 것과 안 바뀌는 것 |
| 자동 확정 | 다음 자동 확정, 자동 확정 진행 중 | auto_finalize_enabled | 서버 전체 설정. 켜져 있으면 매시 정각에 확정 시각이 지난 달을 고객마다 확정합니다. 도입사가 켜고 끌 수 없습니다 | 자동 확정과 보류 |
| 확정 시각 | 다음 자동 확정 | auto_finalize_at | 자동 확정이 그 달을 다루기 시작하는 시각, 다음 달 1일 14:00 KST | 자동 확정과 보류 |
| 자동 확정 진행 중 | 자동 확정 진행 중 | auto_finalize_running | 자동 확정이 돌고 있고 그 달을 아직 다 처리하지 않은 상태 | 자동 확정과 보류 |
| 보류 | 자동 확정 보류: 단가 없는 사용량, 자동 확정 보류: 수동 확정 필요 | auto_finalize_held | 금액이 0원이 아닌데 단가 없는 사용량이 있어 자동 확정이 확정하지 않은 고객. 다시 시도하지 않으므로 직접 확정합니다 | 자동 확정과 보류 |
결제
| 용어 | 콘솔 표기 | API 값 | 뜻 | 자세히 |
|---|---|---|---|---|
| 결제 모드 | 테스트 결제, 실결제 | test, live | 결제에 쓰는 토스페이먼츠 키와 카드의 구분. 테스트 환경과 실제 환경에서는 고정이고 기존 데이터에서만 바꿀 수 있습니다 | 테스트 결제와 실결제 |
| 테스트 헤더 | TossPayments-Test-Code 요청 헤더 | 테스트 결제에서 결제 실패를 재현하는 헤더. 실결제에서 보내면 400으로 거절됩니다 | 테스트 결제와 실결제 | |
| 토스페이먼츠 키 | 토스페이먼츠 연동, 토스 키 저장, 클라이언트 키, 시크릿 키, 토스 키 보관 | client_key, secret_key, secret_key_last_four | 업무 환경마다 저장하는 토스페이먼츠 API 개별 연동 키 한 쌍. 저장은 콘솔에서만 됩니다 | 토스페이먼츠 상점 준비와 키 저장 |
| API 개별 연동 키 | test_ck_, test_sk_, live_ck_, live_sk_ 접두사 | MeterEngine이 받는 토스페이먼츠 키 종류. 결제위젯 키(gck, gsk)는 거절합니다 | 토스페이먼츠 상점 준비와 키 저장 | |
| 토스페이먼츠 웹훅 | /v1/toss-payments-webhooks/{organization_id}, PAYMENT_STATUS_CHANGED | 토스페이먼츠가 결제 상태 변경을 MeterEngine에 알리는 주소. MeterEngine이 도입사에 보내는 웹훅과 다릅니다 | 토스페이먼츠 상점 준비와 키 저장 | |
| 카드 등록 링크 | 카드 등록 링크 만들기 | POST /v1/customers/{id}/payment-method-registrations의 token | 고객이 카드를 등록하는 링크. 24시간 동안 한 번 쓸 수 있습니다 | 고객 카드 등록 링크 |
| 등록 카드 | 현재 등록 카드, 카드 보관 | GET /v1/customers/{id}/payment-method | 고객이 지금 결제 모드로 등록한 카드. 빌링키 자체는 보이지 않습니다 | 고객 카드 등록 링크 |
| 결제 시도 | 결제 시도 기록 | payment_attempts, status: pending, done, failed | 인보이스 하나를 등록 카드로 결제하려고 토스페이먼츠에 보낸 요청 한 번. 첫 결제, 자동 재시도, 고객 재시도, 도입사 재요청이 각각 하나씩 남습니다 | 첫 결제 요청과 결과 확인 |
| 결과 확인 중 | 결과 확인 중 | pending | 토스페이먼츠가 승인했는지 아직 확인하지 못한 상태. 실패가 아니며 MeterEngine이 다시 조회합니다 | 첫 결제 요청과 결과 확인 |
| 수납 상태 | 결제 불필요, 결제 전, 결과 확인 중, 수납 완료, 결제 실패, 부분 취소, 전액 취소 | not_required, unpaid, pending, paid, failed, partially_canceled, canceled | 지금 결제 모드의 가장 늦은 결제 시도로 정하는 인보이스별 결제 상태 | 수납 상태와 대사 확인 |
| 시도 수 | attempt_count | 한 인보이스에 같은 결제 모드로 한 결제 시도 전부의 수. 3이 되면 자동 재시도와 고객 재시도가 멈춥니다 | 결제 실패와 재시도 | |
| 자동 재시도 | 다음 재시도 | next_retry_at | 실패하고 24시간 뒤 MeterEngine이 조건에 맞는 실패를 다시 결제하는 것 | 결제 실패와 재시도 |
| 실패 코드 | 실패 코드 | failure_code, last_failure_code | 실패한 결제 시도의 사유. 토스페이먼츠 코드이거나 MeterEngine이 정한 값(HTTP_<상태>, NOT_FOUND_PAYMENT, toss_payments_credential_missing, payment_method_missing)입니다 | 결제 실패와 재시도 |
| 카드 오류 | failure_code(예: INVALID_STOPPED_CARD) | 같은 카드로 다시 결제해도 실패할 것으로 보고 자동 재시도하지 않는 토스페이먼츠 실패 코드. 고객이 카드를 다시 등록하면 풀립니다 | 결제 실패와 재시도 | |
| 고객의 링크 재시도 | 고객의 실패 결제 재시도 허용, 결제 다시 시도 | allow_payment_retry | 재시도를 허용한 고객 조회 링크 화면에서 고객이 실패한 결제를 등록 카드로 다시 요청하는 것 | 결제 실패와 재시도 |
| 결제 취소 | 승인 결제 취소, 입력한 금액 취소 요청, 전액 취소 요청 | POST /v1/payment-attempts/{id}/cancellations, status: pending, done, failed | 승인된 결제 시도의 금액 전부나 일부를 토스페이먼츠에 돌려 달라고 요청하는 것. 인보이스 금액은 바뀌지 않습니다 | 결제 취소 |
| 잔액 | 잔액 | 결제 시도 금액에서 끝난 취소의 합을 뺀 값. 더 취소할 수 있는 상한입니다 | 결제 취소 | |
| 고객 조회 링크 | 고객 조회 링크 | POST /v1/invoices/{id}/view-links의 token | 고객이 로그인 없이 확정 인보이스 하나와 결제 상태를 보는 링크(https://meterengine.com/invoice-links#<token>) | 고객에게 인보이스 보여 주기 |
| 조회 전용 링크 | 조회 전용 | allow_payment_retry: false | 재시도를 허용하지 않은 고객 조회 링크 | 고객에게 인보이스 보여 주기 |
| 대사 | GET /v1/payment-reconciliation-mismatches | 매일 04:00 KST에 토스페이먼츠 거래 목록과 MeterEngine의 승인된 결제, 끝난 취소를 맞춰 보고 다른 것을 불일치로 기록하는 작업 | 수납 상태와 대사 확인 | |
| 불일치 종류 | missing_in_meterengine, missing_in_toss_payments, amount_mismatch, status_mismatch | 대사가 찾은 차이의 종류 | 수납 상태와 대사 확인 |
웹훅
| 용어 | 콘솔 표기 | API 값 | 뜻 | 자세히 |
|---|---|---|---|---|
| 웹훅 | 처리 결과 통보 | MeterEngine이 결제 결과처럼 나중에 정해지는 일을 도입사 서버에 HTTPS POST로 알리는 것 | 웹훅 받기 시작하기 | |
| 수신 주소 | 수신 주소, 수신 URL, 수신 주소 등록 | 경로 /v1/webhook-endpoints, url | 웹훅을 받을 도입사 서버의 HTTPS URL. 업무 환경마다 10개까지 등록합니다 | 웹훅 받기 시작하기 |
| 서명 비밀값 | 서명 비밀값 | secret(whsec_ 접두사) | 수신 주소마다 하나인 서명 키. 등록 응답에만 한 번 나옵니다 | 웹훅 서명 검증 |
| 받을 통보 | 받을 통보 | event_types | 수신 주소가 받을 웹훅 유형의 목록 | 웹훅 받기 시작하기 |
| 발송 상태 | 발송 사용, 발송 일시 중지(목록: 발송 중, 일시 중지) | enabled true, false | 수신 주소의 발송을 켜고 끄는 값. 끈 동안 생긴 웹훅은 나중에도 보내지 않습니다 | 웹훅 받기 시작하기 |
| 수신 주소 보관 | 수신 주소 보관, 보관됨, 수신 주소 복원 | DELETE, archived_at, status=archived | 수신 주소의 발송을 멈추고 기본 목록에서 뺀 상태. 기록은 남고 복원할 수 있습니다 | 웹훅 받기 시작하기 |
| 결제 성공 | 결제 성공 | payment_succeeded | 결제 시도가 승인으로 끝났을 때의 웹훅 | 웹훅 이벤트 유형과 data |
| 결제 실패 | 결제 실패 | payment_failed | 결제 시도가 실패로 끝났을 때의 웹훅. 실패 사유는 실리지 않습니다 | 웹훅 이벤트 유형과 data |
| 결제 취소 통보 | 결제 취소 | payment_canceled | 결제 취소가 끝났을 때의 웹훅. amount는 이번 취소 금액입니다 | 웹훅 이벤트 유형과 data |
| 과금 제외 사용량 | 과금 제외 사용량 | unbilled_usage_detected | 매일 09:00 KST에 청구에서 빠지는 사용량이 있는 달마다 보내는 상태 보고 웹훅 | 웹훅 이벤트 유형과 data |
| 시험 통보 | 시험 통보, 시험 통보 보내기 | webhook_test | 연결을 확인하는 웹훅. 시험 발송한 수신 주소로만 갑니다 | 웹훅 이벤트 유형과 data |
| environment(웹훅 본문) | 테스트 환경, 실제 환경, 기존 데이터 | test, live, legacy | 웹훅이 생긴 업무 환경 | 웹훅 이벤트 유형과 data |
| mode(결제 웹훅 data) | 테스트 결제, 실결제 | test, live | 그 결제를 처리한 결제 모드 | 웹훅 이벤트 유형과 data |
| webhook-id | webhook-id 요청 헤더 | 웹훅 하나의 고유 값. 재전송과 여러 수신 주소에서도 같아 중복을 거르는 데 씁니다 | 전송, 재전송, 중복 처리 | |
| 통보 발송 내역 | 발송 내역과 설정(링크), 통보 발송 내역(화면 제목) | 수신 주소별 전송 기록 화면 | 전송, 재전송, 중복 처리 | |
| 전송 상태 | 발송 대기, 재시도 대기, 발송 완료, 발송 실패 | pending, done, failed | 수신 주소별 전송 한 건의 상태 | 전송, 재전송, 중복 처리 |
| 전송 실패 사유 | 응답 시간 초과, 연결 실패, 성공이 아닌 응답, 허용되지 않는 주소, 발송을 멈춘 수신 주소, 발송 처리 시간 초과, 서명 비밀값 확인 불가 | timeout, connection_error, unexpected_status, blocked_address, endpoint_disabled, lease_expired, secret_unavailable | 전송 시도가 실패한 이유 | 전송, 재전송, 중복 처리 |
| 다시 보내기 | 다시 보내기 | POST /v1/webhook-endpoints/{id}/deliveries/{delivery_id}/retries | 발송 실패로 끝난 전송을 같은 webhook-id로 다시 대기시키는 수동 재전송 | 전송, 재전송, 중복 처리 |