@cmarket/partner-sdk 0.1.0 → 0.3.0

package/README.md

@@ -1,4 +1,194 @@
-## @cmarket/partner-sdk@0.1.0
+<!-- cmarket-quickstart-preamble -->
+
+# CMARKET V6 Partner SDK
+
+CMARKET V6 Partner API 의 공식 클라이언트 SDK — 외부 ERP 가 입찰 등록부터 낙찰·계약서류·검수·정산까지 전 흐름을 연동하기 위한 7개 API 를 타입 안전하게 호출합니다.
+
+> 이 상단 섹션(설치·인증·통합 순서·에러·예제)은 CMARKET 가 관리하는 quickstart 입니다. 그 아래 `---` 구분선 이후는 OpenAPI Generator 가 매 릴리스 생성하는 **전체 엔드포인트/모델 레퍼런스**입니다.
+
+## 설치 (Installation)
+
+TypeScript / Node (npm):
+
+```bash
+npm install @cmarket/partner-sdk@0.3.0
+```
+
+Java (Maven):
+
+```xml
+<dependency>
+  <groupId>net.c-market</groupId>
+  <artifactId>partner-sdk</artifactId>
+  <version>0.3.0</version>
+</dependency>
+```
+
+## Base URL
+
+```
+https://partner-api.c-market.net   # 예시 — 확정 도메인 아님
+```
+
+환경별(staging/production) baseURL 과 client_id / client_secret 은 파트너 온보딩 시 개별 발급·안내됩니다. 아래 예제의 baseURL 은 발급받은 값으로 교체하세요.
+
+## 인증 (Authentication) — OAuth 2.0 Client Credentials
+
+모든 호출은 OAuth 2.0 client_credentials 그랜트(RFC 6749 §4.4)로 발급한 JWT access token 을 `Authorization: Bearer <token>` 헤더로 실어야 합니다.
+
+1. 토큰 발급: `POST {BASE}/v1/oauth/token`
+   - body(form 또는 JSON): `grant_type=client_credentials`, `client_id`, `client_secret`, (선택) `scope` (space-separated)
+   - 응답(RFC 6749 §5.1, snake_case): `{ access_token, token_type: "Bearer", expires_in, scope }`
+   - access_token TTL 은 짧습니다(현재 900초/15분) — 만료 시 재발급하세요.
+2. 이후 모든 비즈니스 호출에 `Authorization: Bearer <access_token>` 부착.
+
+### 스코프 (Scopes)
+
+토큰은 파트너에 부여된 스코프 범위 내에서 발급되며, 각 엔드포인트는 아래 스코프를 요구합니다(미보유 시 403).
+
+| Scope             | 용도                                                                       |
+| ----------------- | -------------------------------------------------------------------------- |
+| `bids:read`       | 입찰 결과/정산 조회 (getBidResults, getBidSettlement)                      |
+| `bids:write`      | 입찰 등록 (registerBid)                                                    |
+| `awards:write`    | 낙찰·유찰·협상점수 (registerAward, markBidFailed, submitNegotiationScores) |
+| `contracts:read`  | 계약서류·거래명세서 조회 (getBidContractDocuments, getBidStatement)        |
+| `contracts:write` | 검수완료 (completeAcceptance)                                              |
+| `invoices:write`  | 분할 계산서 요청 (requestSplitInvoice)                                     |
+| `files:write`     | 첨부파일 업로드 (uploadFile)                                               |
+
+## 멱등성 (Idempotency)
+
+모든 write(POST) 엔드포인트는 `Idempotency-Key` 헤더가 **필수**입니다.
+
+- 키 포맷: 1~255자, `[A-Za-z0-9_-]`. 호출 단위로 클라이언트가 고유 값(예: UUID) 생성.
+- 같은 키 + 같은 body 로 재전송하면 핸들러를 다시 실행하지 않고 **최초 응답을 그대로 replay**(기본 24시간) — 네트워크 재시도가 안전합니다.
+- 대상: registerBid, registerAward, markBidFailed, submitNegotiationScores, completeAcceptance, requestSplitInvoice, uploadFile.
+
+## 에러 (Errors) — RFC 9457 problem+json
+
+오류 응답은 `application/problem+json` 입니다.
+
+```json
+{
+  "type": "https://.../errors/...",
+  "title": "사람이 읽는 요약",
+  "status": 400,
+  "detail": "구체적 원인"
+}
+```
+
+`status` 로 분기하고 `detail` 을 로깅하세요. 401 = 토큰 누락/만료, 403 = 스코프 부족, 409 = idempotency 충돌(동일 키 다른 body) 등.
+
+## 통합 순서 (7개 API — V5 → V6 매핑)
+
+V5 push/pull 7개 API 의 V6 후속입니다. 표준 흐름:
+
+| 단계 | V6 operation                              | scope                           | 비고                                                             |
+| ---- | ----------------------------------------- | ------------------------------- | ---------------------------------------------------------------- |
+| 1    | `registerBid`                             | bids:write                      | 입찰 정보 등록 (필요 시 `uploadFile` 선행)                       |
+| 2    | `getBidResults` / `getBidSettlement`      | bids:read                       | 응찰 결과 / 정산(사업자·계좌·공급가) 조회                        |
+| 3a   | (협상 H/K) `submitNegotiationScores`      | awards:write                    | 낙찰 전 기술/가격 점수 평가 — `complete=true` 로 평가완료 게이트 |
+| 3b   | `registerAward`                           | awards:write                    | 낙찰 결과 전송                                                   |
+| 3c   | (유찰 시) `markBidFailed`                 | awards:write                    | 유찰 사유 코드와 함께 처리 (3b 와 택일)                          |
+| 4    | `getBidContractDocuments`                 | contracts:read                  | 계약서류 조회                                                    |
+| 5    | `completeAcceptance`                      | contracts:write                 | 검수완료 통지                                                    |
+| 6    | `getBidStatement` / `requestSplitInvoice` | contracts:read / invoices:write | 거래명세서 조회 / 분할 계산서 요청                               |
+
+> 협상에 의한 계약(H/K)일 때만 3a(submitNegotiationScores)가 3b(registerAward) 보다 선행합니다. 그 외 낙찰방법은 2 → 3b 로 진행합니다.
+
+## SDK 호출 예제
+
+### TypeScript
+
+```ts
+import {
+  Configuration,
+  OauthApi,
+  PartnerV1Api,
+  type CreateBidRequestDto,
+} from '@cmarket/partner-sdk';
+
+const BASE = 'https://partner-api.c-market.net'; // 발급받은 baseURL 로 교체
+
+async function main() {
+  // 1) 토큰 발급 (/v1/oauth/token)
+  const oauth = new OauthApi(new Configuration({ basePath: BASE }));
+  const { data: token } = await oauth.token({
+    grant_type: 'client_credentials',
+    client_id: process.env.CMARKET_CLIENT_ID!,
+    client_secret: process.env.CMARKET_CLIENT_SECRET!,
+    scope: 'bids:write',
+  });
+
+  // 2) access_token 으로 인증된 클라이언트 구성
+  const v1 = new PartnerV1Api(
+    new Configuration({ basePath: BASE, accessToken: token.access_token }),
+  );
+
+  // 3) 입찰 등록 — write 는 Idempotency-Key 헤더 필수
+  const body: CreateBidRequestDto = {
+    buyerId: 'BUYER-001',
+    projectName: '2026 사무용품 구매',
+    // ...나머지 필드는 CreateBidRequestDto 타입 참조
+  } as CreateBidRequestDto;
+
+  const { data } = await v1.registerBid(body, {
+    headers: { 'Idempotency-Key': crypto.randomUUID() },
+  });
+  console.log('created bid:', data);
+}
+
+main().catch(console.error);
+```
+
+### Java
+
+```java
+import net.cmarket.partner.client.ApiClient;
+import net.cmarket.partner.client.api.OauthApi;
+import net.cmarket.partner.client.api.PartnerV1Api;
+import net.cmarket.partner.client.model.*;
+import java.util.Map;
+import java.util.UUID;
+
+public class Quickstart {
+  public static void main(String[] args) throws Exception {
+    String base = "https://partner-api.c-market.net"; // 발급받은 baseURL 로 교체
+
+    // 1) 토큰 발급 (/v1/oauth/token)
+    ApiClient authClient = new ApiClient().setBasePath(base);
+    OauthApi oauth = new OauthApi(authClient);
+    TokenResponseDto token = oauth.token(new TokenRequestDto()
+        .grantType(TokenRequestDto.GrantTypeEnum.CLIENT_CREDENTIALS)
+        .clientId(System.getenv("CMARKET_CLIENT_ID"))
+        .clientSecret(System.getenv("CMARKET_CLIENT_SECRET"))
+        .scope("bids:write"));
+
+    // 2) access_token 을 Authorization 헤더로 부착
+    ApiClient apiClient = new ApiClient()
+        .setBasePath(base)
+        .setRequestInterceptor(req ->
+            req.header("Authorization", "Bearer " + token.getAccessToken()));
+    PartnerV1Api v1 = new PartnerV1Api(apiClient);
+
+    // 3) 입찰 등록 — write 는 Idempotency-Key 헤더 필수
+    CreateBidRequestDto body = new CreateBidRequestDto()
+        .buyerId("BUYER-001")
+        .projectName("2026 사무용품 구매");
+        // ...나머지 필드는 CreateBidRequestDto 참조
+
+    BidCreatedResponseDto created = v1.registerBid(
+        body, Map.of("Idempotency-Key", UUID.randomUUID().toString()));
+    System.out.println("created bid: " + created);
+  }
+}
+```
+
+각 operation 의 정확한 요청/응답 타입과 전체 엔드포인트 목록은 아래 자동 생성 레퍼런스를 참고하세요.
+
+---
+
+## @cmarket/partner-sdk@0.3.0
 
 This generator creates TypeScript/JavaScript client that utilizes [axios](https://github.com/axios/axios). The generated Node module can be used in the following environments:
 
@@ -36,7 +226,7 @@ navigate to the folder of your consuming project and run one of the following co
 _published:_
 
 ```
-npm install @cmarket/partner-sdk@0.1.0 --save
+npm install @cmarket/partner-sdk@0.3.0 --save
 ```
 
 _unPublished (not recommended):_
@@ -53,31 +243,62 @@ Class | Method | HTTP request | Description
 ------------ | ------------- | ------------- | -------------
 *OauthApi* | [**token**](docs/OauthApi.md#token) | **POST** /v1/oauth/token | OAuth 2.0 access token 발급 (client_credentials)
 *PartnerV1Api* | [**bidsControllerFindOne**](docs/PartnerV1Api.md#bidscontrollerfindone) | **GET** /v1/bids/{bidId} | 공고 단건 조회
-*PartnerV1Api* | [**healthControllerCheck**](docs/PartnerV1Api.md#healthcontrollercheck) | **GET** /v1/health | Partner API 헬스체크 (V5 /check 후속)
-*PartnerV1LegacyApi* | [**legacyControllerCheckGet**](docs/PartnerV1LegacyApi.md#legacycontrollercheckget) | **GET** /v1-legacy/check | V5 /check 호환 헬스체크 (deprecated)
-*PartnerV1LegacyApi* | [**legacyControllerCheckPost**](docs/PartnerV1LegacyApi.md#legacycontrollercheckpost) | **POST** /v1-legacy/check | V5 /check 호환 헬스체크 — POST (deprecated)
-*PartnerV2Api* | [**registerAward**](docs/PartnerV2Api.md#registeraward) | **POST** /v2/awards | 낙찰 결과 전송
-*PartnerV2Api* | [**registerBid**](docs/PartnerV2Api.md#registerbid) | **POST** /v2/bids | 입찰 정보 전송(등록)
-*PartnerV2Api* | [**uploadFile**](docs/PartnerV2Api.md#uploadfile) | **POST** /v2/files | 입찰 첨부파일 업로드(base64 또는 url) → fileKey
+*PartnerV1Api* | [**completeAcceptance**](docs/PartnerV1Api.md#completeacceptance) | **POST** /v1/bids/{bidId}/acceptance | 검수완료 전송
+*PartnerV1Api* | [**getBidContractDocuments**](docs/PartnerV1Api.md#getbidcontractdocuments) | **GET** /v1/bids/{bidId}/contract-documents | 계약서류 수신 조회
+*PartnerV1Api* | [**getBidContractDocumentsBatch**](docs/PartnerV1Api.md#getbidcontractdocumentsbatch) | **POST** /v1/bids/contract-documents/batch | 계약서류 수신 배치 조회
+*PartnerV1Api* | [**getBidResults**](docs/PartnerV1Api.md#getbidresults) | **GET** /v1/bids/{bidId}/results | 입찰 결과 조회
+*PartnerV1Api* | [**getBidResultsBatch**](docs/PartnerV1Api.md#getbidresultsbatch) | **POST** /v1/bids/results/batch | 입찰결과 배치 조회
+*PartnerV1Api* | [**getBidSettlement**](docs/PartnerV1Api.md#getbidsettlement) | **GET** /v1/bids/{bidId}/settlement | 입찰결과 정산정보 조회
+*PartnerV1Api* | [**getBidStatement**](docs/PartnerV1Api.md#getbidstatement) | **GET** /v1/bids/{bidId}/statement | 거래명세서 조회
+*PartnerV1Api* | [**healthControllerCheck**](docs/PartnerV1Api.md#healthcontrollercheck) | **GET** /v1/health | Partner API 헬스체크
+*PartnerV1Api* | [**markBidFailed**](docs/PartnerV1Api.md#markbidfailed) | **POST** /v1/awards/fail | 유찰 처리
+*PartnerV1Api* | [**registerAward**](docs/PartnerV1Api.md#registeraward) | **POST** /v1/awards | 낙찰 결과 전송
+*PartnerV1Api* | [**registerBid**](docs/PartnerV1Api.md#registerbid) | **POST** /v1/bids | 입찰 정보 전송(등록)
+*PartnerV1Api* | [**requestSplitInvoice**](docs/PartnerV1Api.md#requestsplitinvoice) | **POST** /v1/invoices/split-requests | 계산서 분할 발급 청구
+*PartnerV1Api* | [**submitNegotiationScores**](docs/PartnerV1Api.md#submitnegotiationscores) | **POST** /v1/awards/nego-eval | 협상(H/K) 점수평가
+*PartnerV1Api* | [**uploadFile**](docs/PartnerV1Api.md#uploadfile) | **POST** /v1/files | 입찰 첨부파일 업로드(base64 또는 url) → fileKey
 
 
 ### Documentation For Models
 
+ - [AcceptanceResultResponseDto](docs/AcceptanceResultResponseDto.md)
  - [AwardRegisteredResponseDto](docs/AwardRegisteredResponseDto.md)
  - [BidBondDto](docs/BidBondDto.md)
+ - [BidContractDocumentsBatchRequestDto](docs/BidContractDocumentsBatchRequestDto.md)
+ - [BidContractDocumentsResponseDto](docs/BidContractDocumentsResponseDto.md)
  - [BidCreatedResponseDto](docs/BidCreatedResponseDto.md)
  - [BidDocumentDto](docs/BidDocumentDto.md)
+ - [BidFailedResponseDto](docs/BidFailedResponseDto.md)
+ - [BidFailureReason](docs/BidFailureReason.md)
  - [BidItemDto](docs/BidItemDto.md)
  - [BidManagerDto](docs/BidManagerDto.md)
+ - [BidResultParticipantDto](docs/BidResultParticipantDto.md)
+ - [BidResultProductDto](docs/BidResultProductDto.md)
+ - [BidResultWinnerDto](docs/BidResultWinnerDto.md)
+ - [BidResultsBatchRequestDto](docs/BidResultsBatchRequestDto.md)
+ - [BidResultsResponseDto](docs/BidResultsResponseDto.md)
+ - [BidSettlementLineItemDto](docs/BidSettlementLineItemDto.md)
+ - [BidSettlementParticipantDto](docs/BidSettlementParticipantDto.md)
+ - [BidSettlementResponseDto](docs/BidSettlementResponseDto.md)
+ - [BidStatementResponseDto](docs/BidStatementResponseDto.md)
  - [BidStatus](docs/BidStatus.md)
  - [BidSummaryResponseDto](docs/BidSummaryResponseDto.md)
+ - [CompleteAcceptanceRequestDto](docs/CompleteAcceptanceRequestDto.md)
+ - [ContractDocumentItemDto](docs/ContractDocumentItemDto.md)
  - [CreateBidRequestDto](docs/CreateBidRequestDto.md)
  - [FileUploadedResponseDto](docs/FileUploadedResponseDto.md)
  - [HealthResponseDto](docs/HealthResponseDto.md)
  - [HierarchicalRegionDto](docs/HierarchicalRegionDto.md)
- - [LegacyEnvelopeDto](docs/LegacyEnvelopeDto.md)
+ - [MarkBidFailedRequestDto](docs/MarkBidFailedRequestDto.md)
+ - [NegotiationScoreDto](docs/NegotiationScoreDto.md)
+ - [NegotiationScoredResponseDto](docs/NegotiationScoredResponseDto.md)
  - [PreconditionsDto](docs/PreconditionsDto.md)
  - [RegisterAwardRequestDto](docs/RegisterAwardRequestDto.md)
+ - [RequestSplitInvoiceRequestDto](docs/RequestSplitInvoiceRequestDto.md)
+ - [SplitInvoiceResponseDto](docs/SplitInvoiceResponseDto.md)
+ - [StatementDocumentDto](docs/StatementDocumentDto.md)
+ - [StatementProductDto](docs/StatementProductDto.md)
+ - [SubmitNegotiationScoresRequestDto](docs/SubmitNegotiationScoresRequestDto.md)
  - [TokenRequestDto](docs/TokenRequestDto.md)
  - [TokenResponseDto](docs/TokenResponseDto.md)
  - [UploadFileRequestDto](docs/UploadFileRequestDto.md)

package/api/oauth-api.ts

@@ -2,7 +2,7 @@
 /* eslint-disable */
 /**
  * CMARKET V6 Partner API
- * 외부 ERP 연동용 RESTful API. V5 17개 엔드포인트의 V6 후속.
+ * 외부 ERP 연동용 RESTful API.
  *
  * The version of the OpenAPI document: 1.0
  *