@portone/mcp-server 0.13.0

package/assets/docs/platform/ko/guides/webhook.md

@@ -0,0 +1,171 @@
+---
+title: 세금계산서 웹훅 가이드
+description: 세금계산서 상태 변화 웹훅의 사용 방법과 설정 가이드입니다.
+---
+
+## ✔️ 웹훅이란?
+
+<div class="hint" data-style="info">
+
+🔔 **웹훅(Webhook)** 은 서버에서 특정 이벤트가 발생했을 때 설정된 URL로 이벤트와 관련된 데이터를 전송하는 방식을 의미합니다.
+
+</div>
+
+포트원 파트너 정산 내 세금계산서 제품은 세금계산서의 상태가 변경되었을 때 고객사가 사전에 설정한 URL로 즉각적으로 이벤트와 관련된 정보를 전달하여 효율적인 시스템 연동을 지원합니다.
+
+### 웹훅이 필요한 이유
+
+웹훅은 다음과 같은 이유로 시스템 간 효율적인 통합에 필수적입니다.
+
+- **리소스 절약**: 주기적으로 데이터를 폴링(polling)하지 않고 이벤트 발생 시에만 정보를 받아볼 수 있어 리소스와 네트워크 대역폭을 크게 절약합니다.
+- **실시간성**: 이벤트 발생 직후 즉시 알림을 받을 수 있어 지연 없이 후속 처리가 가능합니다.
+- **확장성**: 여러 시스템이나 서비스를 쉽게 연동할 수 있어 비즈니스 프로세스 자동화와 확장에 용이합니다.
+
+## ✔️ 세금계산서 웹훅 사용 예시
+
+### 사용 시나리오
+
+- 세금계산서가 국세청에 성공적으로 전송 완료된 경우에만 정산금 지급 처리를 수행해야 하는 정책이 존재할 수 있습니다.
+  이 때 세금계산서 상태를 확인하기 위해 반복하여 콘솔에 접속하지 않고도 웹훅을 통해 실시간으로 상태 알림을 전달받을 수 있습니다.
+
+- 고객사의 내부 데이터베이스에 세금계산서의 상태를 직접 관리하고자 하는 경우, 상태 변화를 내부 시스템에 실시간으로 반영합니다.
+
+### 동작 흐름
+
+1. 포트원에서 특정 이벤트(예: 세금계산서 국세청 전송 완료)가 발생합니다.
+2. 고객사가 사전에 설정한 웹훅 URL로 JSON 데이터를 포함한 HTTP POST 요청이 발송됩니다.
+3. 고객사 서버는 웹훅 데이터를 받아 필요한 내부 로직을 처리합니다.
+
+### 예시 코드 (Node.js)
+
+```javascript
+const express = require("express");
+const app = express();
+
+app.use(express.json());
+
+// 포트원에 사전 설정된 웹훅 URL 예시: https://<고객사 서버 URL>/webhook/taxinvoice
+app.post("/webhook/taxinvoice", (req, res) => {
+  const event = req.body;
+
+  switch (event.type) {
+    case "TaxInvoice.SendingCompleted":
+      // 세금계산서 국세청 전송 완료 로직 처리
+      handleSendingCompleted(event.data);
+      break;
+    // 다른 이벤트 처리 로직 추가 가능
+  }
+
+  res.status(200).send("Webhook received successfully");
+});
+```
+
+## ✔️ 웹훅 스키마
+
+웹훅 데이터는 다음 JSON 구조로 전달됩니다.
+
+|필드명   |타입                  |필수|설명                       |예시                         |
+|---------|----------------------|----|---------------------------|-----------------------------|
+|type     |String                |O   |웹훅 이벤트 유형           |`TaxInvoice.SendingCompleted`|
+|timestamp|String (RFC 3339 형식)|O   |이벤트 발생 시각           |`2025-03-20T14:25:10Z`       |
+|data     |Object                |O   |세금계산서 관련 상세 데이터|`{...}`                      |
+
+### 실제 웹훅 데이터 예시
+
+```json
+{
+  "type": "TaxInvoice.SendingCompleted",
+  "timestamp": "2025-03-20T14:25:10Z",
+  "data": {
+    "taxInvoiceId": "txi-test",
+    "supplierDocumentKey": "sdk-test",
+    "recipientDocumentKey": "rdk-test",
+    "status": "SENDING_COMPLETED",
+    "supplierBrn": "1234567890",
+    "totalAmount": 110000,
+    "totalSupplyAmount": 100000,
+    "totalTaxAmount": 10000
+  }
+}
+```
+
+### `type` 상세 정보
+
+웹훅을 트리거한 이벤트의 타입으로, 아래와 같은 종류로 구성됩니다.
+
+- `TaxInvoice.Requested`: 역발행 요청이 완료된 경우
+- `TaxInvoice.Issued`: 공급자가 발행을 승인한 경우
+- `TaxInvoice.RequestCancelled`: 공급받는자가 역발행 요청을 취소한 경우
+- `TaxInvoice.IssuanceCancelled`: 공급자가 역발행 승인 이후 취소한 경우
+- `TaxInvoice.Refused`: 공급자가 역발행 요청을 발행 거부한 경우
+- `TaxInvoice.SendingCompleted`: 발행 완료된 세금계산서가 국세청에 전송 완료된 경우
+- `TaxInvoice.Manual`: 특정 이벤트가 발생하지 않고 수동 웹훅 재발송 기능을 이용한 경우 (**수동 웹훅 발송 API는 추후 지원 예정**)
+
+### `data` 객체 상세
+
+|필드명              |타입  |필수|설명                  |예시               |
+|--------------------|------|----|----------------------|-------------------|
+|taxInvoiceId        |String|O   |세금계산서 고유 아이디|`txi-test`         |
+|supplierDocumentKey |String|O   |공급자 문서 번호      |`sdk-test`         |
+|recipientDocumentKey|String|O   |공급받는자 문서 번호  |`rdk-test`         |
+|status              |String|O   |세금계산서 상태       |`SENDING_COMPLETED`|
+|supplierBrn         |String|O   |공급자 사업자 등록번호|`1234567890`       |
+|totalAmount         |Number|O   |합계금액              |`110000`           |
+|totalSupplyAmount   |Number|O   |공급가액              |`100000`           |
+|totalTaxAmount      |Number|O   |세액                  |`10000`            |
+
+### `status` 상세 정보
+
+세금계산서의 현재 상태를 나타내는 값으로, 다음과 같은 종류로 구성됩니다. 웹훅의 경우 아래 상태들 중 주요 상태로 변경되는 이벤트에 대해서만 발송됩니다.
+
+- `DRAFTED`: 임시 저장 완료
+- `DRAFT_PENDING`: 임시 저장 대기 (일괄 발행 시 시스템의 처리 대기 상태)
+- `DRAFT_FAILED`: 임시 저장 실패
+- `REQUESTED`: 발행 요청 완료 (공급자에게 이메일이 발송된 상태)
+- `REQUEST_PENDING`: 발행 요청 대기 (일괄 발행 시 시스템의 처리 대기 상태)
+- `REQUEST_FAILED`: 발행 요청 실패
+- `REQUEST_CANCELLED`: 공급받는 자에 의한 발행 취소 (공급자가 역발행 승인하기 이전에 공급받는자가 미리 취소한 상태)
+- `REQUEST_REFUSED`: 발행 요청 거부
+- `ISSUED`: 발행 완료
+- `ISSUANCE_CANCELLED`: 공급자에 의한 발행 취소 (공급자가 역발행 승인 이후 취소된 상태)
+- `BEFORE_SENDING`: 국세청 전송 전
+- `WAITING_SENDING`: 국세청 전송 대기
+- `SENDING`: 국세청 전송 중
+- `SENDING_COMPLETED`: 국세청 전송 완료 (세금계산서가 발행 승인되어 최종적으로 국세청까지 전달된 상태)
+- `SENDING_FAILED`: 국세청 전송 실패
+
+## ✔️ 웹훅 설정 방법
+
+포트원 세금계산서 웹훅은 기술팀에서 직접 설정합니다. 아래 절차를 따라 웹훅 설정을 요청해주세요.
+
+### 설정 요청 절차
+
+1. 웹훅 수신 URL을 준비해주세요.
+2. 기술지원 이메일(<support.b2b@portone.io>)로 웹훅 URL(운영 환경, 테스트 환경 별도 적용 가능)을 전달해주세요.
+3. 테스트 모드 설정이 완료되었다는 회신을 받으면 테스트 모드에서 웹훅 정상 작동 여부를 확인해주세요
+4. 운영 환경에도 적용을 요청하신 뒤 운영 환경에서 웹훅 정상 작동 여부를 확인해주세요.
+
+### 테스트 모드 웹훅 정상 작동 확인 방법
+
+- 포트원 콘솔에서 웹훅 테스트 토글을 활성화해주세요.
+- 테스트용 세금계산서를 발행 요청하면 설정된 테스트용 URL로 웹훅이 전송됩니다.
+
+### IP 필터링 안내
+
+포트원은 아래 고정 IP를 사용하여 웹훅을 전송합니다.
+
+안전한 웹훅 수신을 위해 IP 필터링이 필요하신 경우, 아래 IP를 허용 목록에 추가해 주세요.
+
+- **포트원 V2 웹훅 IP**: `52.78.5.241`
+
+추후 웹훅 발송 IP가 추가/변경될 경우 사전에 메일로 안내드릴 예정이며, 이 때 IP 필터를 업데이트해 주셔야 정상적으로 웹훅 수신이 가능합니다.
+
+### 웹훅 실패 시 재시도 정책
+
+웹훅 요청 시 실패 응답을 받은 경우, 포트원에서는 총 5회(최초 요청 + 4회 재시도)까지 웹훅 전송을 시도합니다.
+또한 고객사의 시스템 장애 상황에서 웹훅 과부하로 인한 영향을 최소화하기 위해 다음과 같은 재시도 정책을 적용하고 있습니다:
+
+- 지수함수 형태로 지연 시간을 점진적으로 늘리는 **Exponential Backoff** 방식
+- 지연 시간에 무작위성을 추가하는 **Equal Jitter** 정책
+
+이러한 정책에 따라 각 재시도는 5분, 10분, 20분, 40분의 기본 지연시간을 기반으로 하지만, 실제 지연시간은 기본값의 절반 정도의 무작위성을 추가하여 결정됩니다. 위에서 언급된 재시도 정책의 자세한 기술적 내용이 궁금하시면 [포트원 기술 블로그 - 웹훅 재시도](https://developers.portone.io/blog/posts/2024-02/v2-webhook)에서 확인하실 수 있습니다.

package/assets/docs/platform/ko/readme.md

@@ -0,0 +1,64 @@
+---
+title: 파트너 정산 자동화 서비스 가이드
+description: ''
+---
+
+## ✔️ 파트너 정산 자동화 서비스란?
+
+<div class="hint" data-style="etc">
+
+👍 **매달 반복되는 모든 파트너(하위셀러) 정산을 한 번에 처리하는 원스톱 정산 솔루션입니다.**
+
+</div>
+
+포트원의 파트너 정산 자동화 서비스를 이용하여 **마켓플레이스**, **플랫폼 사업자**들이 간단한 API연동과
+포트원 관리자 콘솔을 통해서 간편하게 하위정산을 처리할 수 있습니다.
+
+플랫폼 사업을 운영하는 포트원의 고객사분들의 다양한 요청을 통해 기획된 본 서비스는,
+모든 정산 케이스들을 매우 편리하게 처리할 수 있습니다.
+
+**하위셀러 정산 시스템 구축**을 위해 고객사 자체 개발에 드는 많은 비용과 시간을,
+포트원 파트너 정산 자동화 서비스로 재무, 개발 공수를 획기적으로 줄여보세요.
+
+## ✔️ 어떤 비지니스에 파트너 정산 자동화 서비스가 필요할까요?
+
+파트너정산 서비스를 통해 정산 금액을 계산 및 관리하고 정산주기에 맞춰서 이체하실 수 있습니다.
+
+각 주문건별로 중개수수료, 부가세, 할인 분담금 등을 파트너정산 서비스에서는 자동으로 정산금액을 계산합니다.
+
+### 🛒 커머스 마켓플레이스
+
+- 셀러가 마켓플레이스에 입점하여 상품을 판매하는 경우, 셀러에게 중개수수료 및 할인분담금 등을 정산하는 경우
+- 마케팅 채널 비용, 풀필먼트와 같이 추가로 발생하는 비용을 정산하는 경우
+
+### 🖥 온라인 강의 플랫폼
+
+- 크리에이터와 Revenue Share를 통해 주문건 마다 수익을 나누는 경우 (크리에이터, 파트너와 각 주문건별로 Revenue Share를 처리하는 경우)
+
+### 🛵 배달 플랫폼
+
+- 앱에서 이루어진 주문건별로 배달업체 및 식당과 수수료를 정산하는 경우
+
+### 🤝 중고거래 플랫폼
+
+- 앱에서 이루어진 거래건당 중개수수료를 정산하는 경우
+- 매입상품 플랫폼 커머스, 주기적으로 매입하는 상품에 대한 정산을 처리하는 경우
+
+## ✔️ 왜 파트너 정산 자동화 서비스를 꼭 써야할까요?
+
+포트원 결제 연동 서비스에서 확장하여 복잡한 정산도 손쉽게 처리가 가능합니다!
+
+### 간단한 정산 API를 통해 실시간 정산 데이터 등록 및 관리
+
+- 주문정보를 통한 손쉬운 정산 관리
+- 주문건 외 추가 처리 필요한 정산건별
+
+### 단순 중개수수료 처리부터 다양한 파트너 과금 모델 지원
+
+- 쿠폰 및 포인트에 적용되는 할인 분담율
+- 마케팅 비용 분담, 풀필먼트 수수료와 같은 주문별 추가수수료
+- 정산 시 수식 편집 가능
+
+### 뱅킹앱 엑셀 다운로드 및 지급대행을 통한 이체 자동화
+
+[파트너 정산 자동화 서비스 가이드](https://www.youtube.com/watch?v=tLeo78Ko4h4)

package/assets/docs/platform/ko/usages/client.md

@@ -0,0 +1,17 @@
+---
+title: 고객사 예시
+description: ''
+---
+
+## 사전 조건
+
+- 가맹점 : 커머스 마켓플레이스
+
+- 파트너 : 셀러 A, 셀러 B
+
+- 계약 조건
+
+  |파트너|중개수수료|           정산주기           |
+  |:----:|:--------:|:----------------------------:|
+  |   A  |    10%   |D+2, 매월 31일, 전 영업일 기준|
+  |   B  |    20%   |D+2, 매월 31일, 전 영업일 기준|

package/assets/docs/platform/ko/usages/contract.md

@@ -0,0 +1,126 @@
+---
+title: 계약 예시
+description: ''
+---
+
+## 사전 조건
+
+| 계약|중개수수료|           정산주기           |
+|:---:|:--------:|:----------------------------:|
+|계약1|    10%   |D+2, 매월 31일, 전 영업일 기준|
+
+## 샘플 코드
+
+### Request
+
+<div class="tabs-container">
+
+<div class="tabs-content" data-title="Python">
+
+```py
+contract_payload = {
+"platformFee": {
+  "fixedRate": 10000
+  }, # 10% 수수료. 료율 표시 기준은 1/100000 입니다. 따라서 소수점 5자리까지 표시 가능합니다.
+"platformFeeVatPayer": "PARTNER", # 부가세 부담 여부. 파트너 부담("PARTNER"), 파트너 미부담("MERCHANT") 가 있습니다.
+"id": "contractA",
+"memo": "contract A",
+"settlementCycle": { #정산주기
+  "lagDays": 2, #정산 지연일 (d+n)일
+  "datePolicy": "HOLIDAY_BEFORE", # 전 영업일 기준
+  "method": { #'daily','weekly','monthly' 'manualDates' 중 하나를 선택하셔야 합니다.
+    'monthly':{
+      "daysOfMonth":[31] # 매월 31일. 31일은 월말 기준으로 합니다.
+      }
+    }
+  }
+}
+
+headers = {
+'Authorization': f'PortOne ${PORTONE_API_SECRET}',
+'Content-Type': 'application/json'
+}
+
+contract_A = requests.post('https://api.portone.io/platform/contracts/', headers=headers, json=contract_payload)
+```
+
+</div>
+
+<div class="tabs-content" data-title="Node">
+
+```js
+const axios = require("axios");
+// 10% 수수료. 료율 표시 기준은 1/100000 입니다. 따라서 소수점 5자리까지 표시 가능합니다.
+const contract_payload = {
+  platformFee: { fixedRate: 10000 },
+  // 부가세 부담 여부. 파트너 부담("PARTNER"), 파트너 미부담("MERCHANT") 가 있습니다.
+  platformFeeVatPayer: "PARTNER",
+  id: "contractA",
+  memo: "contract A",
+  //정산주기
+  settlementCycle: {
+    //정산 지연일 (d+n)일
+    lagDays: 2,
+    // 전 영업일 기준
+    datePolicy: "HOLIDAY_BEFORE",
+    // 'daily','weekly','monthly' 'manualDates' 중 하나를 선택하셔야 합니다.
+    method: {
+      // 매월 31일. 31일은 월말 기준으로 합니다.
+      monthly: { daysOfMonth: [31] },
+    },
+  },
+};
+
+axios
+  .post("https://api.portone.io/platform/contracts", contract_payload, {
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `PortOne ${PORTONE_API_SECRET}`,
+    },
+  })
+  .then((response) => {
+    console.log(response.data);
+  })
+  .catch((error) => {
+    console.error("Error:", error.response.data);
+  });
+```
+
+</div>
+
+</div>
+
+### Response (snippet)
+
+<div class="tabs-container">
+
+<div class="tabs-content" data-title="snippet">
+
+```json
+{
+  "contract": {
+    "id": "contractA",
+    "graphqlId": "NTpjb250cmFjdEE=",
+    "memo": "contract A",
+    "platformFee": {
+      "type": "FIXED_RATE",
+      "rate": 10000
+    },
+    "settlementCycle": {
+      "lagDays": 2,
+      "datePolicy": "HOLIDAY_BEFORE",
+      "method": {
+        "type": "MONTHLY",
+        "daysOfMonth": [31]
+      }
+    },
+    "platformFeeVatPayer": "PARTNER",
+    "isHidden": false,
+    "appliedAt": "2023-08-11T11:18:52.944447Z" // 업데이트 된 순간을 뜻합니다. 추후 해당 계약에대한 업데이트가 있을 때 해당 시점을 보여줍니다.
+  }
+}
+```
+
+</div>
+
+</div>

package/assets/docs/platform/ko/usages/discount.md

@@ -0,0 +1,89 @@
+---
+title: 할인 예시
+description: ''
+---
+
+## 사전 조건
+
+- 할인 정책 1 : 할인 금액 50% 파트너 분담
+
+## 샘플 코드
+
+### Request
+
+<div class="tabs-container">
+
+<div class="tabs-content" data-title="Python">
+
+```py
+discount_payload = {
+"id": "discount_2", #할인 아이디
+"partnerShareRate": 50000, # 10^5기준, 50% 분담
+"memo": "테스트 할인"
+}
+
+headers = {
+'Authorization': f'PortOne ${PORTONE_API_SECRET}',
+'Content-Type': 'application/json'
+}
+
+discount_A = requests.post('https://api.portone.io/platform/discount-share-policies', headers=headers, json=discount_payload)
+```
+
+</div>
+
+<div class="tabs-content" data-title="Node">
+
+```js
+const axios = require("axios");
+const discount_payload = {
+  id: "discount_2", //할인 아이디
+  partnerShareRate: 50000, // 10^5기준, 50% 분담
+  memo: "테스트 할인",
+};
+
+axios
+  .post(
+    "https://api.portone.io/platform/discount-share-policies",
+    discount_payload,
+    {
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `PortOne ${PORTONE_API_SECRET}`,
+      },
+    },
+  )
+  .then((response) => {
+    console.log(response.data);
+  })
+  .catch((error) => {
+    console.error("Error:", error.response.data);
+  });
+```
+
+</div>
+
+</div>
+
+### Response (snippet)
+
+<div class="tabs-container">
+
+<div class="tabs-content" data-title="snippet">
+
+```json
+{
+  "discountSharePolicy": {
+    "id": "discount_2",
+    "graphqlId": "MjpkaXNjb3VudF8y",
+    "partnerShareRate": 50000,
+    "memo": "테스트 할인",
+    "isHidden": false,
+    "appliedAt": "2023-08-13T10:41:02.385833Z"
+  }
+}
+```
+
+</div>
+
+</div>

package/assets/docs/platform/ko/usages/fee.md

@@ -0,0 +1,97 @@
+---
+title: 추가수수료 예시
+description: ''
+---
+
+## 사전 조건
+
+- 추가수수료 정책 1 : 추가수수료 5% 파트너 분담
+
+## 샘플 코드
+
+### Request
+
+<div class="tabs-container">
+
+<div class="tabs-content" data-title="Python">
+
+```py
+additionalfees_payload = {
+  "id": "addtional_fee_3",
+  "fee": {
+    "fixedRate": 5,
+  },
+  "memo": "테스트 추가수수료",
+  "vatPayer": "PARTNER"
+}
+
+headers = {
+'Authorization': f'PortOne ${PORTONE_API_SECRET}',
+'Content-Type': 'application/json'
+}
+
+fee_A = requests.post('https://api.portone.io/platform/additional-fee-policies', headers=headers, json=additionalfees_payload)
+```
+
+</div>
+
+<div class="tabs-content" data-title="Node">
+
+```js
+const axios = require("axios");
+const additionalfees_payload = {
+  id: "addtional_fee_3", //추가수수료 아이디
+  fee: {
+    fixedRate: 5, // 5%분담
+  },
+  memo: "테스트 추가수수료",
+  vatPayer: "PARTNER",
+};
+
+axios
+  .post(
+    "https://api.portone.io/platform/additional-fee-policies",
+    additionalfees_payload,
+    {
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `PortOne ${PORTONE_API_SECRET}`,
+      },
+    },
+  )
+  .then((response) => {
+    console.log(response.data);
+  })
+  .catch((error) => {
+    console.error("Error:", error.response.data);
+  });
+```
+
+</div>
+
+</div>
+
+### Response (snippet)
+
+<div class="tabs-container">
+
+<div class="tabs-content" data-title="snippet">
+
+```json
+{
+  "additionalFeePolicy": {
+    "id": "addtional_fee_3",
+    "graphqlId": "MzphZGR0aW9uYWxfZmVlXzM=",
+    "fee.type": "FIXED_RATE",
+    "fee.rate": 5,
+    "memo": "테스트 추가수수료",
+    "vatPayer": "PARTNER",
+    "isHidden": false,
+    "appliedAt": "2023-08-13T12:31:50.822913Z"
+  }
+}
+```
+
+</div>
+
+</div>