@cmarket/partner-sdk

v12.4.0

Published

2 days ago

OpenAPI client for @cmarket/partner-sdk

0High
0Medium
0Low

cmarket

axios typescript openapi-client openapi-generator @cmarket/partner-sdk

CMARKET V6 Partner SDK

CMARKET V6 Partner API 의 공식 클라이언트 SDK — 외부 ERP 가 입찰 등록부터 낙찰·검수·정산까지 전 흐름을 타입 안전하게 연동합니다.

이 상단 섹션(설치·인증·통합 순서·에러·예제)은 CMARKET 가 관리하는 quickstart 입니다. 그 아래 --- 구분선 이후는 OpenAPI Generator 가 매 릴리스 생성하는 전체 엔드포인트/모델 레퍼런스입니다.

신규 파트너는 /v2 (OAuth2) 경로를 기본으로 사용하세요. /v1 (platform-auth) 은 V5 호환 대체 경로입니다. /v2 는 8개 핵심 operation 으로 축소된 표면이며, 협상점수평가·분할계산서·계약서류조회·입찰결과 배치조회는 /v1 에서만 제공됩니다(아래 "통합 순서" 표 참조).

설치 (Installation)

TypeScript / Node (npm):

npm install @cmarket/[email protected]

Java (Maven):

<dependency>
  <groupId>net.c-market</groupId>
  <artifactId>partner-sdk</artifactId>
  <version>12.4.0</version>
</dependency>

Base URL

단일 base URL 만 사용합니다 — operation 경로에 이미 /v2 또는 /v1 이 포함되므로 base 에 버전을 붙이지 마세요.

| 환경 | Base URL | | ---------- | ------------------------------------------ | | production | https://partner-api.c-market.net | | staging | https://partner-api.staging.c-market.net |

client_id / client_secret(또는 /v1 의 platform id/secret)은 온보딩 시 CMARKET 운영팀이 파트너별로 발급·안내합니다.

인증 (Authentication)

SDK 자동관리 — `createPartnerClient` (권장 경로)

/v2 통합자는 토큰 발급·캐시·만료 60초 전 선갱신·401 재발급 재시도·(선택) DPoP proof 를 직접 구현하지 말고 SDK 팩토리에 위임하세요. createPartnerClient() 가 반환하는 v2/oauth 클라이언트는 매 요청에 Authorization 헤더를 자동 부착합니다.

import { createPartnerClient } from '@cmarket/partner-sdk/partner-client';

const client = createPartnerClient({
  baseUrl: 'https://partner-api.c-market.net', // staging: https://partner-api.staging.c-market.net
  clientId: process.env.CMARKET_CLIENT_ID!,
  clientSecret: process.env.CMARKET_CLIENT_SECRET!,
  scope: 'bids:write bids:read',
  // dpop: true, // 키 바인딩 토큰(DPoP)을 쓰는 파트너만
});

// 토큰 발급/캐시/갱신은 SDK 가 처리 — write 는 Idempotency-Key 만 챙기면 됩니다.
await client.v2.registerBid(
  { buyerId: 'BUYER-001', projectName: '2026 사무용품 구매' },
  { headers: { 'Idempotency-Key': crypto.randomUUID() } },
);

Java 도 동일하게 PartnerClient.create(config) → client.v2() 로 사용합니다.

아래 ### /v2 — OAuth2 Client Credentials 이하는 토큰을 직접 발급·관리할 때의 계약 정본(수동/raw)입니다.

`/v2` — OAuth2 Client Credentials (권장)

/v2 호출은 OAuth2 client_credentials 그랜트(RFC 6749 §4.4)로 발급한 JWT access token 을 Authorization: Bearer <token> 헤더에 실어야 합니다.

토큰 발급: POST {BASE}/oauth/token (버전 prefix 없음)
- 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 은 JWT 이며 TTL 900초(15분) — iss=cmarket-partner-api, aud=cmarket-v6-partners. 만료 시 재발급하세요.
이후 모든 /v2 호출에 Authorization: Bearer <access_token> 부착.

`/v1` — platform-auth (V5 호환 대체)

/v1 은 V5 와 동일한 platform-auth 방식입니다. OAuth·스코프 없이 두 헤더로 인증하며, 권한은 group_code 로 결정됩니다.

X-Platform-Id: cate_set.api_id
X-Platform-Secret: cate_set.api_secret (MD5-hex)
자격증명이 유효하지 않으면 503 으로 응답합니다(V5 충실 동작).

스코프 (Scopes) — `/v2` 8개 operation

토큰은 파트너에 부여된 스코프 범위 내에서만 발급됩니다. 각 /v2 operation 이 요구하는 스코프는 다음과 같습니다(미보유 시 403 insufficient-scope, WWW-Authenticate 헤더에 필요한 scope 명시).

| operation | 메서드 / 경로 | scope | 용도 | | -------------------- | ---------------- | ----------------- | ----------------------------- | | registerBid | POST /v2/bids | bids:write | 입찰 등록 | | getBidResults | GET /v2/... | bids:read | 응찰 결과 조회 | | getBidSettlement | GET /v2/... | bids:read | 정산(사업자·계좌·공급가) 조회 | | getBidStatement | GET /v2/... | contracts:read | 거래명세서 조회 | | completeAcceptance | POST /v2/... | contracts:write | 검수완료 통지 | | registerAward | POST /v2/... | awards:write | 낙찰 결과 전송 | | markBidFailed | POST /v2/... | awards:write | 유찰 처리 | | uploadFile | POST /v2/files | files:write | 첨부파일 업로드 |

정확한 경로·요청/응답 스키마는 --- 아래 자동 생성 레퍼런스를 정본(canonical)으로 삼으세요.

멱등성 (Idempotency)

모든 write(POST) 엔드포인트는 Idempotency-Key 헤더가 필수입니다.

대상(/v2): registerBid, completeAcceptance, registerAward, markBidFailed, uploadFile.
키 포맷: 1~255자, [A-Za-z0-9_-] (예: UUID). 호출 단위로 클라이언트가 고유 값을 생성.
같은 키 + 같은 body 로 재전송하면 핸들러를 재실행하지 않고 최초 응답을 그대로 replay(24시간) — 네트워크 재시도가 안전합니다.
같은 키에 다른 body 를 보내면 409 idempotency-key-conflict.

에러 (Errors)

비즈니스 엔드포인트는 RFC 9457 application/problem+json 을 반환합니다.

{
  "type": "https://problems.cmarket.io/partner/validation-failed",
  "title": "사람이 읽는 요약",
  "status": 400,
  "detail": "구체적 원인",
  "instance": "/v2/bids"
}

OAuth 토큰 엔드포인트(/oauth/token)만 예외로, RFC 6749 §5.2 형식 { error, error_description } 을 반환합니다.

분기 기준은 HTTP status (4xx 는 추가로 type)로 하세요. type 단독 분기는 위험합니다 — 예를 들어 upstream-rejected 는 400/403/404/409/502 에 모두 걸칩니다.

에러 카탈로그 (비즈니스 엔드포인트, problem+json)

| type slug | status | 의미 / 대처 | | -------------------------- | ------------------- | ----------------------------------------------------------------------------------------------- | | validation-failed | 400 | 입력 검증 실패 | | idempotency-key-required | 400 | write 인데 Idempotency-Key 누락 | | idempotency-key-invalid | 400 | 키 포맷 위반 | | idempotency-key-conflict | 409 | 같은 키에 다른 body | | buyer-id-required | 400 | /v1 입찰 등록에 buyerId 누락 | | missing-bearer-token | 401 | (/v2) Bearer 토큰 누락 | | invalid-token | 401 | (/v2) 토큰 만료/무효 — 재발급 | | unbound-partner-key | 403 | 키 설정 오류(미바인딩) — 운영팀 문의 | | ip-not-allowed | 403 | 호출 IP 가 allowlist 에 없음 | | insufficient-scope | 403 | 토큰 스코프 부족 (WWW-Authenticate 헤더 참조) | | buyer-scope-mismatch | 403 | 키에 바인딩되지 않은 buyer 사용 | | upstream-rejected | 400/403/404/409/502 | 백엔드 도메인 거절 — status 로 분기, detail 은 불투명하므로 correlation id 를 지원팀에 전달 | | payload-too-large | 413 | 본문 50MB 초과 | | too-many-requests | 429 | rate limit — Retry-After 준수 | | service-unavailable | 503 | 백엔드 다운 또는 /v1 platform-auth 실패 — Retry-After 준수 | | internal-server-error | 500 | 서버 오류 — 재시도 + correlation id 보고 |

OAuth 토큰 엔드포인트 (RFC 6749)

| error | status | 의미 | | ------------------------ | ------ | ----------------------------- | | invalid_request | 400 | 필수 파라미터 누락/형식 오류 | | unsupported_grant_type | 400 | client_credentials 외 grant | | invalid_client | 401 | client_id/secret 불일치 | | invalid_scope | 400 | 허용되지 않은 scope 요청 |

Rate limit

| 대상 | 한도 | | --------------------- | ------------- | | POST /oauth/token | 5 req/min/IP | | 그 외 모든 엔드포인트 | 60 req/min/IP |

초과 시 HTTP 429 too-many-requests (problem+json) + Retry-After 헤더(초). throttle 될 때는 Retry-After 를 신뢰해 backoff 하세요.
X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset 헤더는 성공 응답에만 포함되며, 429 응답 자체에는 없습니다.

통합 순서 (표준 흐름 — `/v2`)

V5 push/pull 흐름의 V6 후속입니다. /v2 기준 표준 단계:

| 단계 | operation | scope | 비고 | | ---- | -------------------- | ----------------- | -------------------------------------------- | | 1 | uploadFile | files:write | (선택) 첨부파일 선행 업로드 | | 2 | registerBid | bids:write | 입찰 정보 등록 | | 3 | getBidResults | bids:read | 응찰 결과 조회 | | 4 | getBidSettlement | bids:read | 정산(사업자·계좌·공급가) 조회 | | 5 | registerAward | awards:write | 낙찰 전송 (유찰이면 markBidFailed 로 택일) | | 6 | getBidStatement | contracts:read | 거래명세서 조회 | | 7 | completeAcceptance | contracts:write | 검수완료 통지 |

`/v1` 전용 operation (`/v2` 미제공)

다음 작업은 /v2 에 없습니다. 필요한 파트너는 /v1 (platform-auth) 을 사용하세요. 거래명세서(getBidStatement / v1GetBidStatement)는 양쪽 모두 제공됩니다.

| 작업 | /v1 SDK 메서드 | 비고 | | ----------------- | -------------------------------- | --------------------------- | | 협상점수평가 | v1SubmitNegotiationScores | 협상 계약(H/K) 낙찰 전 평가 | | 분할계산서 요청 | v1RequestSplitInvoice | — | | 계약서류 조회 | v1GetBidContractDocumentsBatch | — | | 입찰결과 배치조회 | v1GetBidResultsBatch | 다건 결과 일괄 조회 |

SDK 호출 예제

TypeScript (`/v2`)

import { Configuration, OauthApi, PartnerV2Api } from '@cmarket/partner-sdk';

const BASE = 'https://partner-api.c-market.net'; // staging: https://partner-api.staging.c-market.net

async function main() {
  // 1) 토큰 발급 (/oauth/token — 버전 prefix 없음)
  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 bids:read',
  });

  // 2) access_token 으로 인증된 /v2 클라이언트 구성
  const v2 = new PartnerV2Api(
    new Configuration({ basePath: BASE, accessToken: token.access_token }),
  );

  // 3) 입찰 등록 — write 는 Idempotency-Key 헤더 필수
  const { data } = await v2.registerBid(
    {
      buyerId: 'BUYER-001',
      projectName: '2026 사무용품 구매',
      // ...나머지 필드는 아래 레퍼런스의 registerBid 요청 스키마 참조
    },
    { headers: { 'Idempotency-Key': crypto.randomUUID() } },
  );
  console.log('created bid:', data);
}

main().catch(console.error);

Java (`/v2`)

import net.cmarket.partner.client.ApiClient;
import net.cmarket.partner.client.api.OauthApi;
import net.cmarket.partner.client.api.PartnerV2Api;
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"; // staging: https://partner-api.staging.c-market.net

    // 1) 토큰 발급 (/oauth/token)
    OauthApi oauth = new OauthApi(new ApiClient().setBasePath(base));
    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 bids:read"));

    // 2) access_token 을 Authorization 헤더로 부착한 /v2 클라이언트
    ApiClient apiClient = new ApiClient()
        .setBasePath(base)
        .setRequestInterceptor(req ->
            req.header("Authorization", "Bearer " + token.getAccessToken()));
    PartnerV2Api v2 = new PartnerV2Api(apiClient);

    // 3) 입찰 등록 — write 는 Idempotency-Key 헤더 필수
    CreateBidRequestDto body = new CreateBidRequestDto()
        .buyerId("BUYER-001")
        .projectName("2026 사무용품 구매");
        // ...나머지 필드는 레퍼런스의 registerBid 요청 스키마 참조

    BidCreatedResponseDto created = v2.registerBid(
        body, Map.of("Idempotency-Key", UUID.randomUUID().toString()));
    System.out.println("created bid: " + created);
  }
}

Raw HTTP (계약 정본 baseline)

SDK 없이 직접 호출할 때의 contract-truthful 형태입니다.

# 1) 토큰 발급 — RFC 6749 (성공 시 snake_case 응답)
curl -X POST "$BASE/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "'"$CMARKET_CLIENT_ID"'",
    "client_secret": "'"$CMARKET_CLIENT_SECRET"'",
    "scope": "bids:write bids:read"
  }'
# => { "access_token": "...", "token_type": "Bearer", "expires_in": 900, "scope": "bids:write bids:read" }

# 2) 입찰 등록 — Bearer + Idempotency-Key 필수
curl -X POST "$BASE/v2/bids" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "buyerId": "BUYER-001", "projectName": "2026 사무용품 구매" }'

DPoP (키 바인딩 토큰) — proof 직접 서명

DPoP 를 요구하는 파트너는 요청마다 짧은 수명의 proof JWT(RFC 9449)를 서명해 DPoP 헤더에, 토큰은 Authorization: DPoP <token> 로 실어야 합니다. SDK 를 쓰면 dpop: true 한 줄로 자동 처리되지만, raw 로 직접 서명하려면 다음과 같습니다(Node jose).

클라이언트 수명 동안 ES256 키쌍 1개를 재사용하고, 공개키(JWK)를 proof 헤더에 넣습니다.
proof payload: htm(HTTP 메서드), htu(쿼리 제외 요청 URL), iat, jti(고유). 리소스 호출에는 access token 해시 ath 도 포함(토큰 엔드포인트 proof 에는 ath 없음).
proof 헤더: alg=ES256, typ=dpop+jwt, jwk(공개키).

import { SignJWT, exportJWK, generateKeyPair, type JWK } from 'jose';

const { privateKey, publicKey } = await generateKeyPair('ES256', { extractable: true });
const jwk = (await exportJWK(publicKey)) as JWK;

async function dpopProof(htm: string, htu: string, accessToken?: string) {
  const payload: Record<string, unknown> = { htm, htu, jti: crypto.randomUUID() };
  if (accessToken) {
    const digest = new Uint8Array(
      await crypto.subtle.digest('SHA-256', new TextEncoder().encode(accessToken)),
    );
    payload.ath = Buffer.from(digest).toString('base64url'); // access token 해시 바인딩
  }
  return new SignJWT(payload)
    .setProtectedHeader({ alg: 'ES256', typ: 'dpop+jwt', jwk })
    .setIssuedAt()
    .sign(privateKey);
}

// 1) 토큰 발급 — 토큰 엔드포인트 proof 에는 ath 없음
const tokenProof = await dpopProof('POST', `${BASE}/oauth/token`);
// fetch(`${BASE}/oauth/token`, { method: 'POST', headers: { DPoP: tokenProof, ... }, body });

// 2) /v2 호출 — Authorization: DPoP + access token 해시(ath) 포함 proof
const callProof = await dpopProof('POST', `${BASE}/v2/bids`, accessToken);
// fetch(`${BASE}/v2/bids`, {
//   method: 'POST',
//   headers: { Authorization: `DPoP ${accessToken}`, DPoP: callProof, 'Idempotency-Key': crypto.randomUUID() },
//   body,
// });

첫 성공 확인 (First success)

/oauth/token 호출이 200 + access_token 을 반환하면 자격증명·스코프가 유효합니다(401 invalid_client 면 client_id/secret 확인).
발급한 토큰으로 getBidResults(읽기, bids:read) 를 1회 호출해 2xx 가 오면 토큰·네트워크·스코프가 정상입니다 — write 보다 안전한 첫 검증입니다.
registerBid 가 2xx 를 반환하면 입찰이 등록된 것입니다. 같은 Idempotency-Key + 같은 body 로 재호출하면 동일 응답이 replay 됩니다.
403 insufficient-scope 면 토큰 발급 시 scope 에 해당 권한을 포함했는지(그리고 키에 그 스코프가 부여됐는지) 확인하세요.

임베드 UI (발주기관 ERP iframe)

발주기관 담당자가 ERP 화면 안에서 재로그인 없이 cmarket 공고 등록 화면을 쓰게 하려면 Partner API 의 POST /v2/embed/launch(scope embed:launch)로 일회성 launch code(60초)를 발급하고, 프론트에서는 임베드 SDK 로 iframe 을 마운트하세요:

<script src="https://cdn.jsdelivr.net/npm/@cmarket/[email protected]/dist/embed.umd.js"></script>
<script>
  CMarketEmbed.mount('#slot', { launchCode: code, screen: 'bid-register' });
</script>

npm(npm install @cmarket/embed)으로도 동일 API 를 제공합니다. 상세 통합 가이드·보안 설계·버전 핀 규율은 @cmarket/embed README 를 참고하세요. CDN URL 은 반드시 버전을 핀하고(latest 금지), 임베드 origin 은 온보딩 시 CMARKET 운영팀에 등록해야 합니다(미등록 origin 은 iframe 로드가 차단됩니다).

버전 정책

URI versioning. /v1, /v2 모두 운영 중이며 어느 쪽도 deprecated 아닙니다.
SDK 버전은 API 계약을 따릅니다(SemVer; breaking 변경 = major).
변경 이력은 CHANGELOG.md 참조.

각 operation 의 정확한 경로·요청/응답 타입과 전체 엔드포인트 목록은 아래 자동 생성 레퍼런스를 정본으로 참고하세요.

@cmarket/[email protected]

This generator creates TypeScript/JavaScript client that utilizes axios. The generated Node module can be used in the following environments:

Environment

Node.js
Webpack
Browserify

Language level

ES5 - you must have a Promises/A+ library installed
ES6

Module system

CommonJS
ES6 module system

It can be used in both TypeScript and JavaScript. In TypeScript, the definition will be automatically resolved via package.json. (Reference)

Building

To build and compile the typescript sources to javascript use:

npm install
npm run build

Publishing

First build the package then run npm publish

Consuming

navigate to the folder of your consuming project and run one of the following commands.

published:

npm install @cmarket/[email protected] --save

unPublished (not recommended):

npm install PATH_TO_GENERATED_PACKAGE --save

Documentation for API Endpoints

All URIs are relative to https://partner-api.c-market.net

Class | Method | HTTP request | Description ------------ | ------------- | ------------- | ------------- OauthApi | token | POST /oauth/token | OAuth 2.0 access token 발급 (client_credentials) PartnerV1Api | v1AcknowledgeProductReceipt | POST /v1/products/receipts | 물품 수신확인 — V5 충실 PartnerV1Api | v1CompleteAcceptance | POST /v1/bids/{bidId}/acceptance | 검수완료 전송 — V5 충실 PartnerV1Api | v1GetBidContractDocumentsBatch | POST /v1/bids/contract-documents/batch | 계약서류 수신 배치 조회 — V5 충실 PartnerV1Api | v1GetBidResultsBatch | POST /v1/bids/results/batch | 입찰결과 배치 조회 — V5 충실 PartnerV1Api | v1GetBidStatement | GET /v1/bids/{bidId}/statement | 거래명세서 조회 — V5 충실 PartnerV1Api | v1GetProductFeed | GET /v1/products | 물품 카탈로그 피드 조회 — V5 충실 PartnerV1Api | v1MarkBidFailed | POST /v1/awards/fail | 유찰 처리 — V5 충실 PartnerV1Api | v1RegisterAward | POST /v1/awards | 낙찰 결과 전송 — V5 충실 PartnerV1Api | v1RegisterBid | POST /v1/bids | 입찰 정보 전송(등록) — V5 충실 PartnerV1Api | v1RequestSplitInvoice | POST /v1/invoices/split-requests | 계산서 분할 발급 청구 — V5 충실 PartnerV1Api | v1SubmitNegotiationScores | POST /v1/awards/nego-eval | 협상(H/K) 점수평가 — V5 충실 PartnerV2Api | closeSandboxBid | POST /v2/sandbox/bids/{bidId}/close | 샌드박스 공고 마감 (영업 데모 전용) PartnerV2Api | completeAcceptance | POST /v2/bids/{bidId}/acceptance | 검수완료 전송 PartnerV2Api | completeInvoice | POST /v2/bids/{bidId}/settlement/complete | 정산 마감(송장 강제완료) PartnerV2Api | createEmbedLaunch | POST /v2/embed/launch | 임베드 launch code 발급 (iframe SSO) PartnerV2Api | getBid | GET /v2/bids/{bidId} | 공고 단건(라이프사이클) 조회 PartnerV2Api | getBidResults | GET /v2/bids/{bidId}/results | 입찰 결과 조회 PartnerV2Api | getBidSettlement | GET /v2/bids/{bidId}/settlement | 입찰결과 정산정보 조회 PartnerV2Api | getBidStatement | GET /v2/bids/{bidId}/statement | 거래명세서 조회 PartnerV2Api | healthControllerCheck | GET /health | Partner API 헬스체크 PartnerV2Api | issueTaxInvoice | POST /v2/bids/{bidId}/tax-invoice | 세금계산서 발행 PartnerV2Api | listBids | GET /v2/bids | 공고 목록 조회 PartnerV2Api | markBidFailed | POST /v2/bids/{bidId}/award/fail | 유찰 처리 PartnerV2Api | publishBid | POST /v2/bids/{bidId}/publish | 공고 게시(초안 → 진행중) PartnerV2Api | regenerateContractDocuments | POST /v2/bids/{bidId}/contract-documents | 계약서류 생성(재생성) PartnerV2Api | registerAward | POST /v2/bids/{bidId}/award | 낙찰 결과 전송 PartnerV2Api | registerBid | POST /v2/bids | 입찰 정보 전송(등록) PartnerV2Api | submitNegotiationScores | POST /v2/bids/{bidId}/negotiation-scores | 협상 점수평가 PartnerV2Api | updateBid | PATCH /v2/bids/{bidId} | 입찰 공고 수정 PartnerV2Api | uploadFile | POST /v2/files | 입찰 첨부파일 업로드(base64 또는 url) → fileKey

Documentation For Models

Documentation For Authorization

Authentication schemes defined for the API:

partner-oauth2

Type: Bearer authentication (JWT)

platform-auth-id

Type: API key
API key parameter name: X-Platform-Id
Location: HTTP header

platform-auth-secret

Type: API key
API key parameter name: X-Platform-Secret
Location: HTTP header