몰파이 API 연동 가이드

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

1. 연동 개요

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

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

2. 상품 리스트 조회 API (GET) → 제휴사 앱 내 상품 노출용

3. 주문 상태 Postback API (POST) → 주문 완료/취소/구매확정 시 제휴사 서버로 상태 전달

2. 상품 리스트 조회 API

📌 개요

제휴사 APP 내에 Mallpie 상품을 노출하기 위한 API입니다. 협의된 조건에 따라 정렬된 상품 리스트를 반환합니다.

• 최대 노출 개수 요청 가능

• 리워드 금액(contract_price)은 사전 협의 비율로 계산

• 상품 상세 이동 시 uKey 파라미터 포함 필수

---

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://cps.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 필드 설명

필드	타입	설명
id	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://cps.mallpie.kr/product/{product_id}?uKey={user_key}

• user_key는 제휴사에서 생성한 유니크 값

• 주문 발생 시 Postback으로 동일 값 전달

• 리워드 정산 기준값으로 사용

---

3. 주문 상태 Postback API

📌 개요

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

• 주문

• 구매확정

• 주문취소(환불완료)

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

---

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	주문 상태

---

3.4 주문 상태값 정의

상태값	설명
PAYMENT	주문 완료
PURCHASE	구매확정
CANCEL	주문취소 (환불완료)

---

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"
    }
  ]
}