@portone/mcp-server 0.14.0 → 0.15.0-alpha.1

package/assets/docs/release-notes/platform/2025-08-13.md

@@ -0,0 +1,95 @@
+---
+releasedAt: 2025-08-13T00:00:00.000Z
+writtenAt: 2025-08-13T00:00:00.000Z
+---
+
+안녕하세요, 파트너 정산 자동화 팀입니다.
+
+2025년 8월 13일 업데이트 사항을 확인해 보세요.
+
+---
+
+## 정산 내역서 발송 기능 업데이트
+
+이제, 파트너 정산 콘솔에서 생성된 정산 내역을 기반으로, 파트너에게 정산 내역서를 보낼 수 있습니다.
+
+일괄지급 내역 상세 및 지급 내역 관리 페이지에서 원하는 정산 내역을 단건, 혹은 다건으로 선택하여 한 번에 정산내역서 이메일을 발송할 수 있습니다.
+
+**발신자/수신자 설정**: 발신자 이메일 설정은 필수이며, 도메인 인증을 통해 도메인을 활용한 발신이 가능합니다. 인증 완료된 도메인이 없는 경우, 기본 메일 <no-reply@portone.io>로 정산내역서를 발송할 수 있습니다.
+
+수신자 이메일은 등록해 둔 파트너의 담당자 이메일로 지정되고, 담당자 이메일을 수정하는 것으로 수신자 이메일을 수정할 수 있습니다. 모든 설정을 완료하고, '정산내역서 발송' 버튼을 클릭하면 선택된 지급 내역의 파트너 전체에게 이메일이 차례대로 발송됩니다.
+
+(관련 이미지 첨부)
+
+---
+
+## 정산 내역서 템플릿 생성 및 수정
+
+정산 내역서 템플릿을 자유롭게 생성하고, 수정할 수 있습니다.
+
+정산내역서 템플릿 관리 페이지에서 템플릿을 다양하게 만들어 관리할 수 있습니다. 지급 내역 생성 여부와 관계없이 템플릿을 생성할 수 있으며, 템플릿 목록 조회, 신규 생성 및 수정, 보관, 복원이 가능합니다. 템플릿 구성 항목의 포함 여부(on/off)를 관리할 수 있고, 구성 항목은 다음과 같습니다.
+
+(관련 이미지 첨부)
+
+**발신자 정보**
+
+- 우리 회사 상호
+
+**수신자(파트너) 정보**
+
+- 파트너 이름 및 법인명
+- 파트너 유형
+- 과세, 소득 유형
+- 예금주명
+- 은행정보 (계좌번호 및 은행명)
+
+**정산 기본 정보**
+
+- 정산 기간
+
+**정산 금액 정보**
+
+- 지급 금액 (필수값)
+- 원천징수세액 (소득세, 지방 소득세)
+- 정산 금액
+- 확정 공급가액
+- 확정 부가세액
+- 정산 면세액
+- 확정 면세액
+
+---
+
+## 지급 내역에서 정산 내역서의 상태를 확인
+
+지급 내역 페이지에서 정산 내역서 상태 컬럼이 추가되어 발송 상태를 확인할 수 있습니다.
+
+지급 내역 페이지에 `정산내역서 상태`, `정산내역서 ID`, `정산내역서 발송 일시` 컬럼이 추가됩니다. 정산 내역서의 상태는 정산내역서가 아직 생성 및 발송되지 않은 상태인 **미발송**, 이메일이 수신자에게 성공적으로 전달된 **발송 완료**, 이메일 발송을 시도했으나, 주소 오류 등의 이유로 실패한 상태인 **발송 실패** 총 3개의 상태가 존재합니다.
+
+(관련 이미지 첨부)
+
+---
+
+## API 변경 안내
+
+지급내역 `PlatformPayout` 에 정산내역서 요약 정보가 추가되었고, 지급내역 다건 조회 시 정산내역서 정보를 기준으로 필터링할 수 있습니다.
+
+**지급 내역** `PlatformPayout` **필드 추가**
+
+신규 필드: `settlementStatement`: `PlatformPayoutSettlementStatementSummary`
+
+- `id` – 정산내역서 아이디
+- `status` – 정산내역서 상태
+- `issuedAt` – 정산내역서 발송 일시
+
+**지급 내역 필터** `PlatformPayoutFilterInput` **옵션 추가**
+
+- `settlementStatementStatuses`: 정산내역서 상태
+- `criteria.settlementStatementIssuedTimestampRange`: 정산내역서 발송 일시 범위
+- `criteria.settlementStatementId`: 정산내역서 아이디
+
+---
+
+작성일자: **2025년 08월 13일**
+
+- 일반 문의: <cs@portone.io> / 채널톡
+- 기술지원 문의: <tech.support@portone.io> / 파트너스 슬랙 채널

package/assets/docs/release-notes/platform/2025-08-21.md

@@ -0,0 +1,53 @@
+---
+releasedAt: 2025-08-21T00:00:00.000Z
+writtenAt: 2025-08-21T00:00:00.000Z
+---
+
+안녕하세요, 파트너 정산 자동화 팀입니다.
+
+2025년 8월 21일 업데이트 사항을 확인해 보세요.
+
+---
+
+## 세금계산서 정발행 기능 출시
+
+고객에게 발행하는 정발행 세금계산서를 발행하고 관리할 수 있습니다.
+
+이제, 역발행 뿐 아니라 정발행 기능을 콘솔에서 사용할 수 있습니다. 단건 발행 및 일괄 발행으로 정발행 세금계산서를 발행할 수 있게 되어 정산뿐만 아니라 모든 거래에 대한 세금계산서 커버가 가능해집니다.
+
+기존 역발행과 다르게 정발행은 파트너 등록 및 <strong>국세청 연동 없이</strong> 이용할 수 있으며, 파트너 등록을 하지 않더라도 정발행시 입력한 공급받는 자(거래처) 정보를 다시 불러와 사용할 수 있습니다.
+
+(관련 이미지 첨부)
+
+---
+
+## 엑셀, CSV 일괄 정/역발행
+
+기존 일괄 세금계산서 발행은 CSV 파일만 지원되었지만, 이번 업데이트를 통해 엑셀 파일 업로드도 가능해집니다. 제공되는 엑셀 및 CSV 파일 양식을 다운로드 받아 일괄적으로 세금계산서를 작성하여 업로드할 수 있습니다. 기존 역발행과 동일하게 미리보기 후 임시 저장하거나 즉시 발행할 수 있습니다.
+
+(관련 이미지 첨부)
+
+---
+
+## 세금계산서 내역 관리
+
+기존 역발행 건과 정발행 건의 자연스러운 통합을 위해 세금계산서 내역 관리 페이지에 발행 유형 필터가 추가됩니다. 세금계산서 내역 테이블 내 사업자 정보 컬럼이 기존 공급자 정보에서 거래처(공급자/공급받는자) 정보로 변경되어 역발행의 경우 공급자, 정발행의 경우 공급받는자 정보가 표기됩니다.
+
+일괄 세금계산서 내역 관리 페이지에서 발행 대기 상태와 발행 실패 상태가 추가됩니다. 발행 대기 상태는 일괄 세금계산서 발행 처리 중 상태를 의미하며 발행 실패 상태는 시스템 처리 실패를 의미합니다. 또한 정발행과 역발행을 구분하는 발행 유형 정보 및 필터가 추가됩니다.
+
+(관련 이미지 첨부)
+
+---
+
+## 세금계산서 안내 메일 발송
+
+공급받는 자에게 이메일이 발송됩니다.
+
+세금계산서를 발행하는 시점에 공급받는자 (고객) 에게 팝빌 (포트원과 연동된 세금계산서 서비스) 로부터 이메일이 발송됩니다. 공급자는 발행 주체이므로, 별도의 알림 이메일은 발송되지 않습니다.
+
+---
+
+작성일자: **2025년 08월 21일**
+
+- 일반 문의: <cs@portone.io> / 채널톡
+- 기술지원 문의: <tech.support@portone.io> / 파트너스 슬랙 채널

package/assets/docs/release-notes/platform/2025-08-28.md

@@ -0,0 +1,53 @@
+---
+releasedAt: 2025-08-28T00:00:00.000Z
+writtenAt: 2025-08-28T00:00:00.000Z
+---
+
+안녕하세요, 파트너 정산 자동화 팀입니다.
+
+2025년 8월 28일 업데이트 사항을 확인해 보세요.
+
+---
+
+## 2단계 인증수단
+
+### 2단계 인증수단이란?
+
+관리자 계정 접근 및 이체 실행 시, 공동 인증서 외에 다른 방식의 인증 절차를 요구하여 보안을 유지하는 방식입니다. 포트원은 2단계 인증 수단으로 Google Authenticator (Google OTP) 를 사용합니다. 파트너 정산을 이용하시는 고객님의 빠르고 편리한 이체를 돕기 위해 관리자 콘솔에서 2단계 인증 수단을 이용할 수 있습니다.
+
+---
+
+## 이체 시 2단계 인증수단 업데이트
+
+### 공동인증서 없이 2단계 인증수단 (OTP) 을 이용하여 쉽게 이체하세요.
+
+이제, 공동인증서 없이 콘솔에서 2단계 인증수단을 이용하여 손쉽게 이체를 진행할 수 있습니다. 설정의 내 정보 관리탭에서 2차인증을 눌러 Google Authenticator 를 등록하여 2단계 인증 수단으로 설정할 수 있습니다. 등록이 완료되면 송금대행 일괄이체 실행 페이지의 최종 단계에서 전자서명 대신 2단계 인증번호를 입력할 수 있는 다이얼로그가 노출됩니다.
+
+(이미지 첨부: 2단계 인증번호 입력 화면)
+
+---
+
+## 보안 관련 사항
+
+### 2단계 인증수단 신청 방식
+
+공동인증서 대신 2단계 인증수단 등록을 위해서는 포트원 세일즈/CS 팀으로 요청하셔야하며, <bd@portone.io> 를 통해 요청하실 수 있습니다. 요청이 완료되었더라도, 2단계 인증 설정이 완료된 Admin 계정의 유저만 사용이 가능합니다.
+
+또한, 강력한 보안 조치를 위해 포트원 관리자 콘솔 세션 접근 시 인증을 진행하였더라도, 이체 시에 2단계 인증 수단을 통한 재인증이 요구됩니다.
+
+---
+
+## 가상계좌 과출금 방지 기능 업데이트
+
+### 권장 출금 금액보다 많은 금액을 인출할 때 과출금 방지 경고를 받습니다.
+
+실시간으로 안전한 출금을 지원하고, 과출금 리스크를 방지하기 위해 과출금 방지 기능이 업데이트 되었습니다. 권장 출금 금액 (계좌 잔액 - 예상 지급 금액) 을 자동 계산하여, 권장 출금 금액보다 많은 금액을 출금하려고 할 때 과출금 방지 경고를 받을 수 있습니다. 예상 지급 금액은 정산내역과 지급내역을 통해 계산되며, 가상계좌 출금 페이지에서 예상 지급 금액 정보를 바로 확인할 수 있습니다.
+
+(이미지 첨부: 과출금 방지 화면)
+
+---
+
+작성일자: **2025년 08월 28일**
+
+- 일반 문의: <cs@portone.io> / 채널톡
+- 기술지원 문의: <tech.support@portone.io> / 파트너스 슬랙 채널

package/assets/docs/release-notes/platform/2025-10-02.md

@@ -0,0 +1,152 @@
+---
+releasedAt: 2025-10-02T00:00:00.000Z
+writtenAt: 2025-10-02T00:00:00.000Z
+---
+
+안녕하세요, 파트너 정산 자동화 팀입니다.
+
+파트너 정산 자동화 제품의 테스트 환경 확장에 따른 API 변경 사항을 안내드립니다.
+
+---
+
+## \[파트너 정산 자동화] 테스트 환경 분리 및 API 변경 사전 안내
+
+이번 업데이트로 운영 환경과 테스트 환경이 완전히 분리되어, 설정·정산 정책·내역서 템플릿 등을 독립적으로 관리하실 수 있습니다.
+
+## 주요 변경 사항
+
+- 신규 쿼리 파라미터: test: Boolean (선택값)
+
+- 적용 대상: 모든 파트너 정산 REST API
+
+- 적용 예정 일자: 2025년 11월 중 (정확한 일자는 추후 별도 안내 예정)
+
+- 기본값: false
+
+- 연동 환경 별 설정
+  - 라이브: 하위호환성이 보장되어 영향이 없습니다.
+  - 테스트: test=true 쿼리 파라미터 추가 설정이 필요합니다.
+
+(이미지 첨부: as is - to be)
+
+이번 변경으로 라이브/테스트 환경이 완전히 분리되어 더욱 자유로운 테스트가 가능해집니다.\
+_기존 데이터는 테스트 및 라이브 환경에 복제되어 기존 그대로 활용하실 수 있습니다._
+
+---
+
+## 개선 사항
+
+### 1. 정산 정책 및 수식 테스트 환경 분리
+
+기존에는 정산 정책 및 정산 수식을 변경할 때 별도의 테스트 환경이 없어 운영에 영향을 줄 우려가 있었습니다.\
+이번 개선으로 라이브 환경과 완전히 분리된 테스트 환경을 제공하여, 정산 정책 및 수식을 실제 운영에 영향 없이 안전하게 테스트할 수 있습니다.
+
+### 2. 파트너 데이터 환경 분리
+
+테스트를 위해 등록한 파트너가 라이브 데이터에 그대로 남아 실제 파트너와 함께 조회되는 불편함이 있었습니다.\
+테스트용 파트너는 테스트 환경에 별도로 등록하여, 실제 파트너 데이터와 분리하여 관리할 수 있습니다.
+
+### 3. 국세청 연동 환경 분리
+
+국세청 연동 시 라이브와 테스트 환경에 동시에 연동되어 불필요한 연동 안내 메일을 중복으로 받는 문제가 있었습니다.\
+환경별로 독립적인 국세청 연동이 가능해져 필요한 환경에서만 선택적으로 연동할 수 있습니다.
+
+---
+
+## 세부 변경 사항
+
+### 1. 기존 요청 본문에서 테스트 환경 구분이 가능한 API
+
+요청 본문(body)의 `isForTest` 파라미터로 환경을 지정하던 방식은 deprecated 되었습니다.\
+쿼리 파라미터 `test`로 대체 해 주시기 바랍니다. deprecated 필드는 2026년 이후 별도 공지와 함께 지원이 중단될 예정입니다.
+
+```http
+#Query Parameter가 우선 적용
+POST /platform/transfers/order?test=true
+{
+  "isForTest": false,  // 무시됨, Query Parameter의 true가 적용
+  ...
+}
+
+#Query Parameter 가 없으면 Request Body 값 사용
+POST /platform/transfers/order
+{
+  "isForTest": true,  // 이 값이 적용
+  ...
+}
+```
+
+우선순위는 아래와 같습니다.
+
+1. Query Parameter 의미 `test` (최우선)
+2. Request Body 의 `isForTest` (Query Parameter 없을 때)
+3. 기본값 `false` (둘 다 없을 때)
+
+영향 받는 API는 다음과 같습니다.
+
+- 정산 상세 내역 다운로드 `GET /platform/transfer-summaries/sheet-file`
+- 정산건 다건 조회 `GET /platform/transfer-summaries`
+- 수기 정산건 생성 `POST /platform/transfers/manual`
+- 주문 정산건 생성 `POST /platform/transfers/order`
+- 주문 취소 정산건 생성 `POST /platform/transfers/order-cancel`
+- 정산 내역 다건 조회 `GET /platform/partner-settlements`
+- 지급 내역 다건 조회 `GET /platform/payouts`
+- 일괄 지급 내역 다건 조회 `GET /platform/bulk-payouts`
+- 이체 내역 다건 조회 `GET /platform/account-transfers`
+- 일괄 이체 내역 다건 조회 `GET /platform/bulk-account-transfers`
+
+### 2. 테스트 환경 지정이 필요한 API
+
+테스트 환경 지정을 위해 쿼리 파라미터 `test`가 추가되었습니다.\
+해당 파라미터는 선택 값이며 기본값은 `false`입니다.
+
+```http
+#라이브 환경 데이터만 조회 (기본값)
+GET /platform/transfers/{id}
+
+#테스트 환경 데이터만 조회
+GET /platform/transfers/{id}?test=true
+```
+
+영향 받는 API는 다음과 같습니다.
+
+- 정산건 조회 `GET /platform/transfers/{id}`
+- 정산건 삭제 `DELETE /platform/transfers/{id}`
+- 추가 수수료 정책 다건 조회 `GET /platform/additional-fee-policies`
+- 추가 수수료 정책 생성 `POST /platform/additional-fee-policies`
+- 추가 수수료 정책 조회 `GET /platform/additional-fee-policies/{id}`
+- 추가 수수료 정책 수정 `PATCH /platform/additional-fee-policies/{id}`
+- 추가 수수료 정책 보관 `POST /platform/additional-fee-policies/{id}/archive`
+- 추가 수수료 정책 복원 `POST /platform/additional-fee-policies/{id}/recover`
+- 계약 다건 조회 `GET /platform/contracts`
+- 계약 생성 `POST /platform/contracts`
+- 계약 조회 `GET /platform/contracts/{id}`
+- 계약 수정 `PATCH /platform/contracts/{id}`
+- 계약 보관 `POST /platform/contracts/{id}/archive`
+- 계약 복원 `POST /platform/contracts/{id}/recover`
+- 할인 분담 정책 다건 조회 `GET /platform/discount-share-policies`
+- 할인 분담 정책 생성 `POST /platform/discount-share-policies`
+- 할인 분담 정책 조회 `GET /platform/discount-share-policies/{id}`
+- 할인 분담 정책 수정 `PATCH /platform/discount-share-policies/{id}`
+- 할인 분담 정책 보관 `POST /platform/discount-share-policies/{id}/archive`
+- 할인 분담 정책 복원 `POST /platform/discount-share-policies/{id}/recover`
+- 파트너 다건 조회 `GET /platform/partners`
+- 파트너 생성 `POST /platform/partners`
+- 파트너 다건 생성 `POST /platform/partners/batch`
+- 파트너 일괄 국세청 연동 `POST /platform/partners/member-company-connect`
+- 파트너 국세청 연동 `POST /platform/partners/member-company-connect/{id}`
+- 파트너 일괄 국세청 연동 해제 `POST /platform/partners/member-company-disconnect`
+- 파트너 국세청 연동 해제 `POST /platform/partners/member-company-disconnect/{id}`
+- 파트너 조회 `GET /platform/partners/{id}`
+- 파트너 수정 `PATCH /platform/partners/{id}`
+- 파트너 보관 `POST /platform/partners/{id}/archive`
+- 파트너 복원 `POST /platform/partners/{id}/recover`
+- 예금주 조회 `GET /platform/bank-accounts/{bank}/{accountNumber}/holder`
+- 사업자 조회 `GET /platform/companies/{businessRegistrationNumber}/state`
+
+---
+
+작성일자: **2025년 10월 02일**
+
+- 일반 문의: <cs@portone.io> / 채널톡
+- 기술지원 문의: <support.b2b@portone.io> / 파트너스 슬랙 채널