몰파이 API 연동 가이드

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

1. 연동 개요

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

uKey 유저 식별값 처리 (리워드유형 해당) → 회원 식별을 위한 해당 서비스의 고유한 userKey DATA로 몰파이 호출시에는 암호화하여 전달

(uKey 의경우 50자 이내로 전송)

ex) shop.mallpie.kr/?uKey=a123b456c789

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

2. 상품 리스트 조회 API

📌 개요

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

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

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 필드 설명

필드

타입

설명

Long

상품 ID

url

String

상품 상세 URL (uKey 포함)

product_image

String

상품 이미지

shop_name

String

판매업체명

name

String

상품명

price

Long

정상가

discount_price

Long

할인가

contract_price

Long

리워드 금액

sale_flag

int

판매여부 (1: 판매중)

card_view_image

String

카드형 노출 이미지

discount_percent

Long

할인율

category_code

String

카테고리 코드

category_nm

String

카테고리명

curation_code

Long

기획전 코드

curation_title

String

기획전 타이틀

curation_link

String

기획전 링크

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

📌 개요

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

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

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

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

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

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 필드

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

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

필드

타입

설명

order_dtl_id

Long

주문 상세 ID

product_id

Long

상품 ID

product_name

String

상품명

order_price

Long

주문 금액

contract_price

Long

리워드 금액

order_qty

Long

주문 수량

order_status

String

주문 상태

group_buying_finish

Optinal<boolean>

공동 구매 종료 여부 (공동구매 진행 중 false / 종료 true )

group_buying_refund

Optinal<boolean>

공동구매 환급 여부 ( 공동구매 미달성시 및 미종료시 false )

group_buying_refund_price

Optional<Long>

공동구매 환급 금액 ( 환급 여부와 관계없는 예정된 환급 금액입니다. )

group_buying_reward_after_refund

Optinal<Long>

공동구매 환급 금액 적용 리워드 (환급여부와 관계없이 예정된 환급 금액으로 계산됩니다. )

3.4 주문 상태값 정의

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

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

상태값

설명

PAYMENT

주문 완료

PURCHASE

구매확정 (공동 구매 주문의 경우 공동구매 종료시까지 해당 상태값이 발송되지 않습니다.)

CANCEL

주문취소 (환불완료)

SHIPPING

배송중

( 판매자가 배송중 상태 변경 시점으로 택배사 배송 시작과 별개입니다 )

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 테스트만 지원합니다.

Postback 연동 테스트 바로가기

📌 개요

제휴사 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 필드 설명

필드

타입

설명

promotionId

Long

프로모션 ID

productId

Long

상품 ID

promotionProductName

String

프로모션시 상품명

productName

String

상품명

productImg

String

상품 썸네일

cardViewImg

String

프로모션 카드이미지

price

Long

정상가

discountPrice

Long

판매가

promotionPrice

Long

프로모션 판매가격

discountPercent

int

할인율

promotionDiscountPercent

int

프로모션 할인율

brandName

String

브랜드명

productUrl

String

상품상세 URL

startAt

DateTime

특가 시작 일시

endAt

DateTime

특가 종료 일시

contractPrice

Long

리워드 금액

promotionContractPrice

Long

프로모션 리워드 금액

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 파라미터 포함 필수
조회시점에 진행중인 공동구매만 조회 가능
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 필드 설명

필드

타입

설명

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

공동구매 시작 일시, KST

(yyyy-MM-dd HH:mm:ss )

end_at

DateTime

공동구매 종료 일시, KST

(yyyy-MM-dd HH:mm:ss )

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일 이후 결제하신 주문수단의 부분취소로 환급이 진행됩니다.
부분취소로 진행됨에 따라 가상계좌, 계좌이체 및 일부 간편결제는 지원되지 않습니다.

Last updated 23 days ago