> For the complete documentation index, see [llms.txt](https://help-partner.mallpie.kr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help-partner.mallpie.kr/api/api.md).

# 몰파이 API 연동 가이드

{% hint style="info" %}
본 문서는 몰파이 커넥트 시작을 위해 제휴사 APP/WEB 내에서 **Mallpie 쇼핑몰 상품을 노출하고, 주문 완료 정보를 수신하기 위한 API 연동 가이드**입니다.\
연동이 필요한경우 안내된 가이드를 통해 진행해보세요.
{% endhint %}

## 1. 연동 개요

Mallpie 커넥트 연동은 아래 3가지로 구성됩니다.

1. **uKey 유저 식별값 처리 (**<mark style="color:purple;">**리워드유형**</mark>**&#x20;해당)**\
   &#x20;→ 회원 식별을 위한 해당 서비스의 고유한 userKey DATA로 몰파이 호출시에는 암호화하여 전달

&#x20;      (uKey 의경우 50자  이내로  전송)

&#x20;      ex) shop.mallpie.kr/?uKey=a123b456c789

1. **상품 리스트 조회 API (GET)**\
   &#x20;→ 제휴사 앱 내 상품 노출용
2. **주문 상태 Postback API (POST)**\
   → 주문 완료/취소/구매확정 시 제휴사 서버로 상태 전달

## 2. 상품 리스트 조회 API

### 📌 개요

제휴사 APP 내에 Mallpie 상품을 노출하기 위한 API입니다.<br>

* 상품 정보는 Best로 선정된 상품 200개 정보 제공
* 리워드 금액(contract\_price)은 사전 협의 비율로 계산
* 상품 상세 이동 시 `uKey` 파라미터 포함 필수
* Shop\_id 는 제휴시 요청 하신 Sub도메인 명 (ex test.mallpie.kr -> test 가 Shop\_id)
* 개발 서버 사용을 위해서는 사전 요청이 필요하며, 개발 서버를 통해서는 샘플 전문만 확인 가능&#x20;

***

### 2.1 Endpoint

#### 🔹 개발 서버

```
GET https://cps.sellerd.kr/api/v1/list/{shop_id}?service_key={연동Key}
```

#### 🔹 운영 서버

```
GET https://cps.mallpie.kr/api/v1/list/{shop_id}?service_key={연동Key}
```

***

### 2.2 Request

#### Header

```
Content-Type: application/json
charset: UTF-8
```

#### Path Parameter

| 항목       | 타입     | 설명          |
| -------- | ------ | ----------- |
| shop\_id | String | 제휴사 shop ID |

#### Query Parameter

| 항목           | 타입     | 설명         |
| ------------ | ------ | ---------- |
| service\_key | String | 발급된 연동 Key |

***

### 2.3 Response

#### ✅ 성공 (HTTP 200)

```
{
  "meta": {
    "status": 200,
    "message": "ok"
  },
  "body": {
    "contents": [
      {
        "id": 10000436,
        "url": "https://{생성된Shop_ID}.mallpie.kr/product/10000436?uKey=123qwer",
        "product_image": "https://...",
        "shop_name": "지니웍스",
        "name": "상품명",
        "price": 22000,
        "discount_price": 13900,
        "contract_price": 2400,
        "sale_flag": 1,
        "card_view_image": "https://...",
        "discount_percent": 37,
        "category_code": "1001",
        "category_nm": "생활용품",
        "curation_code": 10,
        "curation_title": "봄맞이 특가전",
        "curation_link": "https://..."
      }
    ]
  }
}
```

***

### 2.4 Response 필드 설명

<table data-search="false"><thead><tr><th>필드</th><th>타입</th><th>설명</th></tr></thead><tbody><tr><td>id</td><td>Long</td><td>상품 ID</td></tr><tr><td>url</td><td>String</td><td>상품 상세 URL (uKey 포함)</td></tr><tr><td>product_image</td><td>String</td><td>상품 이미지</td></tr><tr><td>shop_name</td><td>String</td><td>판매업체명</td></tr><tr><td>name</td><td>String</td><td>상품명</td></tr><tr><td>price</td><td>Long</td><td>정상가</td></tr><tr><td>discount_price</td><td>Long</td><td>할인가</td></tr><tr><td>contract_price</td><td>Long</td><td>리워드 금액</td></tr><tr><td>sale_flag</td><td>int</td><td>판매여부 (1: 판매중)</td></tr><tr><td>card_view_image</td><td>String</td><td>카드형 노출 이미지</td></tr><tr><td>discount_percent</td><td>Long</td><td>할인율</td></tr><tr><td>category_code</td><td>String</td><td>카테고리 코드</td></tr><tr><td>category_nm</td><td>String</td><td>카테고리명</td></tr><tr><td>curation_code</td><td>Long</td><td>기획전 코드</td></tr><tr><td>curation_title</td><td>String</td><td>기획전 타이틀</td></tr><tr><td>curation_link</td><td>String</td><td>기획전 링크</td></tr></tbody></table>

***

### 2.5 오류 응답

#### 🔸 Service Key 오류 (HTTP 401)

```
{
  "meta": {
    "status": 401,
    "message": "잘못된 요청입니다."
  }
}
```

#### 🔸 데이터 없음 (HTTP 404)

```
{
  "meta": {
    "status": 404,
    "message": "데이터가 존재하지 않습니다."
  }
}
```

***

### 2.6 ⚠️ 중요 – uKey 처리

상품 상세 URL 호출 시 반드시 아래 형식으로 user\_key를 포함해야 합니다.

```
https://{생성된Shop_ID}.mallpie.kr/product/{product_id}?uKey={user_key}
```

* user\_key는 제휴사에서 생성한 유니크 값
* 주문 발생 시 Postback으로 동일 값 전달
* 리워드 정산 기준값으로 사용

***

## 3. 주문 상태 Postback API

POSTBACK&#x20;

### 📌 개요

Mallpie에서 주문 상태 변경 시\
제휴사 서버로 자동 전송되는 POST API입니다.

* 주문
* 구매확정
* 주문취소(환불완료)

응답코드 **200만 성공 처리**됩니다.

`cps_key2` 는 연동 제휴사에서 uKey 외에 추가적인 식별값이 필요한 경우 사용할 수 있도록 추가된 항목이며, 필수값은 아닙니다.

중복 방지 Key는 아래 항목을 사용합니다. 주문상태`order_detail[order_status]`에 따라 업체에서 판단하여 처리합니다.

order\_price와 contract\_price는 단가 기준입니다. 수량을 반영한 금액이 필요한 경우, order\_qty를 곱하여 사용해주시면 됩니다.

```
order_id
order_detail[order_dtl_id]
```

⚠️ 공동구매 주문의 경우 일반상품 Postback과 동일하나 공동구매 Field가 추가됩니다.

***

### 3.1 전송 방식

```
Method: POST
Content-Type: application/json
```

***

### 3.2 기본 파라미터

| 필드            | 타입     | 설명               |
| ------------- | ------ | ---------------- |
| user\_key     | String | 상품 상세 호출 시 전달된 값 |
| order\_id     | Long   | 주문 ID            |
| cps\_key2     | String | 추가 연동 키 (선택)     |
| order\_detail | List   | 주문 상세 정보         |

***

### 3.3 order\_detail 필드

&#x20;⚠️ 공동구매 환급 금액은 환급 여부와 상관없이 예정된 환급 금액을 전달 드립니다.

&#x20;⚠️ 공동구매 환급 금액이 적용된 리워드는 환급 여부와 상관없이 예정된 환급금액을 적용하여 전달드립니다.

<table data-search="false"><thead><tr><th>필드</th><th>타입</th><th>설명</th></tr></thead><tbody><tr><td>order_dtl_id</td><td>Long</td><td>주문 상세 ID</td></tr><tr><td>product_id</td><td>Long</td><td>상품 ID</td></tr><tr><td>product_name</td><td>String</td><td>상품명</td></tr><tr><td>order_price</td><td>Long</td><td>주문 금액</td></tr><tr><td>contract_price</td><td>Long</td><td>리워드 금액</td></tr><tr><td>order_qty</td><td>Long</td><td>주문 수량</td></tr><tr><td>order_status</td><td>String</td><td>주문 상태</td></tr><tr><td>group_buying_finish</td><td>Optinal&#x3C;boolean></td><td>공동 구매 종료 여부<br>(공동구매 진행 중 false / 종료 true )</td></tr><tr><td>group_buying_refund</td><td>Optinal&#x3C;boolean></td><td>공동구매 환급 여부 <br>( 공동구매 미달성시 및 미종료시  false )</td></tr><tr><td>group_buying_refund_price</td><td>Optional&#x3C;Long></td><td>공동구매 환급 금액<br>( 환급 여부와 관계없는 예정된 환급 금액입니다. )</td></tr><tr><td>group_buying_reward_after_refund</td><td>Optinal&#x3C;Long></td><td>공동구매 환급 금액 적용 리워드<br>(환급여부와 관계없이 예정된 환급 금액으로 계산됩니다. )</td></tr></tbody></table>

***

### 3.4 주문 상태값 정의

⚠️ 공동구매 주문의 경우 공동구매가 종료되고 +1일뒤 환급이 되며 구매확정된 주문들이 PURCHASE로 발송됩니다.

⚠️ 공동구매 주문상품은 상태값 여부를 확인해보시고 리워드 지급해주시기 바랍니다.

| 상태값      | 설명                                                          |
| -------- | ----------------------------------------------------------- |
| PAYMENT  | 주문 완료                                                       |
| PURCHASE | <p>구매확정<br>(공동 구매 주문의 경우 공동구매 종료시까지 해당 상태값이 발송되지 않습니다.)</p> |
| CANCEL   | 주문취소 (환불완료)                                                 |
| SHIPPING | <p>배송중 </p><p>( 판매자가 배송중 상태 변경 시점으로 택배사 배송 시작과 별개입니다 )</p>  |

***

### 3.5 Postback 예시 ( 일반 주문 )

```
{
  "user_key": "abc123",
  "order_id": 123456,
  "cps_key2": null,
  "order_detail": [
    {
      "order_dtl_id": 9999,
      "product_id": 10000436,
      "product_name": "상품명",
      "order_price": 13900,
      "contract_price": 2400,
      "order_qty": 1,
      "order_status": "PURCHASE"
    }
  ]
} 
```

### 3.6 Postback 예시 ( 공동구매 주문 )

```
{
  "user_key": "abc123",
  "order_id": 123456,
  "cps_key2": null,
  "order_detail": [
    {
      "order_dtl_id": 9999,
      "product_id": 10000436,
      "product_name": "상품명",
      "order_price": 13900,
      "contract_price": 2400,
      "order_qty": 1,
      "order_status": "PURCHASE",
      "group_buying_finish": true,  // 공동구매 종료 여부
      "group_buying_refund": true, // 환급 여부 
      "group_buying_reward_after_refund": 2227, // 환급성공시 reward
      "group_buying_refund_price": 1000, // 환급 성공시 환급 금액
    }
  ]
}
```

### 3.7 몰파이 Postback 테스트(샌드박스)

**몰파이 Postback 전용 샌드박스를** 통해 개발·테스트 환경을 구성할 수 있어요.

* 해당 샌드박스는 DEV Postback URL 테스트만 지원합니다.

<a href="https://mallpie.co.kr/sandbox/index.html" class="button primary">Postback 연동 테스트 바로가기</a>

### 📌 개요

제휴사 APP 내에 Mallpie 한정특가 상품을 노출하기 위한 API입니다.

* 리워드 금액(contract\_price)은 사전 협의 비율로 계산
* 상품 상세 이동 시 `uKey` 파라미터 포함 필수

### 3.8 재전송 처리

재전송 처리 대상

```
HTTP Status가 정상 응답(200)이 아닌 전송 건
```

재전송 처리 횟수

```
최대 3회 재전송
재전송 간격: 1분
```

***

### 4.1 Endpoint

#### 🔹 개발 서버

```
GET https://cps.sellerd.kr/api/v1/list/timedeal/{shop_id}?service_key={연동Key}
```

#### 🔹 운영 서버

```
GET https://cps.mallpie.kr/api/v1/list/timedeal/{shop_id}?service_key={연동Key}
```

***

### 4.2 Request

#### Header

```
Content-Type: application/json
charset: UTF-8
```

#### Path Parameter

| 항목       | 타입     | 설명          |
| -------- | ------ | ----------- |
| shop\_id | String | 제휴사 shop ID |

#### Query Parameter

| 항목           | 타입     | 설명         |
| ------------ | ------ | ---------- |
| service\_key | String | 발급된 연동 Key |

***

### 4.3 Response

#### ✅ 성공 (HTTP 200)

```
{
  "meta": {
    "status": 200,
    "message": "ok"
  },
  "body": [
    {
      "promotionId": 2484,
      "productId": 10029326,
      "promotionProudctName": "프로모션 상품명",
      "productName": "상품명",
      "productImg": "https://.....",
      "cardViewImg": "https://.......",
      "price": 28900,
      "discountPrice": 21900,
      "promotionPrice": 21500,
      "discountPercent": 24,
      "promotionDiscountPercent": 26,
      "brandName": "지니웍스",
      "productUrl": "https://cps.mallpie.kr/v1/product/10029326",
      "startAt": "2026-05-14 17:00:00",
      "endAt": "2026-05-15 16:59:59"
    }
  ]
}
```

***

### 4.4 Response 필드 설명

<table data-search="false"><thead><tr><th>필드</th><th>타입</th><th>설명</th></tr></thead><tbody><tr><td>promotionId</td><td>Long</td><td>프로모션 ID</td></tr><tr><td>productId</td><td>Long</td><td>상품 ID</td></tr><tr><td>promotionProductName</td><td>String</td><td>프로모션시 상품명</td></tr><tr><td>productName</td><td>String</td><td>상품명</td></tr><tr><td>productImg</td><td>String</td><td>상품 썸네일</td></tr><tr><td>cardViewImg</td><td>String</td><td>프로모션 카드이미지</td></tr><tr><td>price</td><td>Long</td><td>정상가</td></tr><tr><td>discountPrice</td><td>Long</td><td>판매가</td></tr><tr><td>promotionPrice</td><td>Long</td><td>프로모션 판매가격</td></tr><tr><td>discountPercent</td><td>int</td><td>할인율</td></tr><tr><td>promotionDiscountPercent</td><td>int</td><td>프로모션 할인율</td></tr><tr><td>brandName</td><td>String</td><td>브랜드명</td></tr><tr><td>productUrl</td><td>String</td><td>상품상세 URL</td></tr><tr><td>startAt</td><td>DateTime</td><td>특가 시작 일시</td></tr><tr><td>endAt</td><td>DateTime</td><td>특가 종료 일시</td></tr><tr><td>contractPrice</td><td>Long</td><td>리워드 금액</td></tr><tr><td>promotionContractPrice</td><td>Long</td><td>프로모션 리워드 금액</td></tr></tbody></table>

***

### 4.5 오류 응답

#### 🔸 Service Key 오류 (HTTP 401)

```
{
  "meta": {
    "status": 401,
    "message": "잘못된 요청입니다."
  }
}
```

#### 🔸 데이터 없음 (HTTP 404)

```
{
  "meta": {
    "status": 404,
    "message": "데이터가 존재하지 않습니다."
  }
}
```

***

### 4.6 ⚠️ 중요 – uKey 처리

상품 상세 URL 호출 시 반드시 아래 형식으로 user\_key를 포함해야 합니다.

```
https://cps.mallpie.kr/product/{product_id}?uKey={user_key}
```

* user\_key는 제휴사에서 생성한 유니크 값
* 주문 발생 시 Postback으로 동일 값 전달
* 리워드 정산 기준값으로 사용

### 4.7 ⚠️ 중요 – 프로모션 시작 종료 처리

응답값에 포함된 startAt / endAt 사이에만 해당 프로모션이 적용되며 시간이 종료되면 아래와같이  필드값을 변경하셔야 합니다.

* promotionDiscountPercent -> discountPercent
* promotionProductName -> productName
* productPrice -> discountPrice
* promotionContractPrice -> contractPrice

## 5. 공동구매 상품 조회 API

### 📌 개요

제휴사 APP 내에 Mallpie 한정특가 상품을 노출하기 위한 API입니다.

* 리워드 금액(contract\_price)은 사전 협의 비율로 계산
* 상품 상세 이동 시 `uKey` 파라미터 포함 필수
* 조회시점에 진행중인 공동구매만 조회 가능&#x20;
* end\_at을 활용하여 공동구매 종료 기능은 직접 구현 필요.
* 공동구매 달성시 종료일 +1일 후 일괄 환급
* 공동구매 달성률은 연결된 매체 전체의 주문 합계이며 개별 설정은 사업 팀과 협의가 필요합니다.

***

### 5.1 Endpoint

#### 🔹 개발 서버

```
GET https://cps.sellerd.kr/api/v1/list/groupbuying/{shop_id}?service_key={연동Key}
```

#### 🔹 운영 서버

```
GET https://cps.mallpie.kr/api/v1/list/groupbuying/{shop_id}?service_key={연동Key}
```

***

### 5.2 Request

#### Header

```
Content-Type: application/json
charset: UTF-8
```

#### Path Parameter

| 항목       | 타입     | 설명          |
| -------- | ------ | ----------- |
| shop\_id | String | 제휴사 shop ID |

#### Query Parameter

| 항목           | 타입     | 설명         |
| ------------ | ------ | ---------- |
| service\_key | String | 발급된 연동 Key |

***

### 5.3 Response

#### ✅ 성공 (HTTP 200)

```
{
  "meta": {
    "status": 200,
    "message": "ok"
  },
  "body": {
    "contents":[
      "id": 10086165,
      "name": "지니웍스 반려견 츄잉껌(공구)",
      "product_image": "https://....,
      "card_view_image": "https://......",
      "price": 12900,
      "discount_price": 8900,
      "shop_name": "지니웍스",
      "brand_name": "지니웍스",
      "url": "https://cps.mallpie.kr/v1/product/10086165",
      "discount_percent": 31,
      "contract_price": 0,
      "group_buying_id": 131,
      "target_order_count": 15,
      "achievement_reward": 1000,
      "current_order_count": 0,
      "start_at": "2026-05-19 00:00:00",
      "end_at": "2026-05-26 23:59:59"
    ]
  }
}
```

***

### 5.4 Response 필드 설명

| 필드                    | 타입       | 설명                                                  |
| --------------------- | -------- | --------------------------------------------------- |
| id                    | Long     | 상품 ID                                               |
| url                   | String   | 상품 상세 URL (uKey 포함)                                 |
| product\_image        | String   | 상품 이미지                                              |
| shop\_name            | String   | 판매업체명                                               |
| name                  | String   | 상품명                                                 |
| price                 | Long     | 정상가                                                 |
| discount\_price       | Long     | 할인가                                                 |
| contract\_price       | Long     | 리워드 금액                                              |
| card\_view\_image     | String   | 카드형 노출 이미지                                          |
| discount\_percent     | Long     | 할인율                                                 |
| goup\_buying\_id      | Long     | 공동구매 관리 ID                                          |
| target\_order\_count  | Long     | 공동구매 목표 수량                                          |
| achievement\_reward   | Long     | 목표 달성시 환급 금액                                        |
| current\_order\_count | Long     | 현재 주문 수량                                            |
| start\_at             | DateTime | <p>공동구매 시작 일시, KST</p><p>(yyyy-MM-dd HH:mm:ss )</p> |
| end\_at               | DateTime | <p>공동구매 종료 일시, KST</p><p>(yyyy-MM-dd HH:mm:ss )</p> |

***

### 5.5 오류 응답

#### 🔸 Service Key 오류 (HTTP 401)

```
{
  "meta": {
    "status": 401,
    "message": "잘못된 요청입니다."
  }
}
```

#### 🔸 데이터 없음 (HTTP 404)

```
{
  "meta": {
    "status": 404,
    "message": "데이터가 존재하지 않습니다."
  }
}
```

***

### 5.6 ⚠️ 중요 – uKey 처리

상품 상세 URL 호출 시 반드시 아래 형식으로 user\_key를 포함해야 합니다.

```
https://cps.mallpie.kr/product/{product_id}?uKey={user_key}
```

* user\_key는 제휴사에서 생성한 유니크 값
* 주문 발생 시 Postback으로 동일 값 전달
* 리워드 정산 기준값으로 사용

### 5.7 ⚠️ 중요 – 공동구매 유의사항

응답값에 포함된 start\_at / end\_at 사이에만 공동구매가 적용되며 종료 이후 주문은 환급 대상에서 제외처리 됩니다.

* start\_at / end\_at 사이의 주문만 집계합니다.
* end\_at + 1일 이후 결제하신 주문수단의 부분취소로 환급이 진행됩니다.
* 부분취소로 진행됨에 따라 가상계좌, 계좌이체 및 일부 간편결제는 지원되지 않습니다.