본문으로 건너뛰기

APP 설치 연동 가이드

📘 개발 가이드

APP 설치 연동 가이드

스토어에서 상점이 APP을 설치할 때, 파트너사에서 처리해야 하는 연동 절차를 설명합니다.

개요​

1
APP URL로 랜딩

설치 완료 시 APP URL로 랜딩되며, shop_uid, timestamp, action_type, hmac 파라미터가 GET 방식으로 전달됩니다.

2
무결성 검증 (HMAC)

전달받은 파라미터와 파트너사의 Client Secret을 사용하여 요청의 유효성을 검증합니다.

3
설치 정보 조회 및 온보딩

검증이 완료되면 shop_uid를 이용해 상점 설치 앱 정보 조회 API를 호출하여 설치 정보를 조회하고 온보딩을 진행합니다.

1. APP 설치 완료 후 동작​

설치하기와 신청하기 두 가지 액션 모두 동일하게 동작합니다. 설치가 완료되면, 등록된 APP URL로 자동으로 랜딩되며, 이때 무결성 검증을 위한 hmac을 포함한 여러 파라미터가 GET 방식으로 함께 전달됩니다.

https://your-app-url.com?shop_uid={shop_uid}&timestamp={timestamp}&action_type={action_type}&hmac={hmac}
💡
APP URL 확인 경로

개발자센터 > APP 가이드 > APP 등록 > 개발 정보 관리 > APP URL 항목

2. HMAC 검증 가이드​

파트너 앱스토어에서 앱 URL 호출 시, 요청의 무결성 검증 및 위·변조 방지를 위해 HMAC-SHA256 서명을 쿼리 파라미터로 전달합니다. 파트너는 자신의 Client Secret을 사용하여 요청의 유효성을 검증할 수 있습니다.

응답 필드 설명​

앱 URL이 호출될 때 다음 쿼리 파라미터가 추가됩니다.

파라미터설명예시
shop_uid앱을 설치한(또는 설치하려는) 상점의 IDtestshop
timestamp요청 생성 시각 (Unix timestamp, milliseconds)1715050800000
action_type요청 유형install
hmacHMAC-SHA256 서명 값 (hex)a1b2c3d4...

호출 예시​

https://your-app-url.com?shop_uid=testshop&timestamp=1715050800000&action_type=install&hmac=a1b2c3d4e5f6...

검증 방법​

1
서명 메시지 생성

수신한 쿼리 파라미터에서 shop_uid, timestamp, action_type 값을 : 구분자로 결합합니다.

{shop_uid}:{timestamp}:{action_type}

예시: testshop:1715050800000:install

2
HMAC-SHA256 서명 생성

파트너 패널에서 확인할 수 있는 Client Secret을 키로 사용하여, 위 메시지를 HMAC-SHA256으로 서명(Hex Digest)합니다.

3
서명 비교 및 검증

생성한 서명 값과 쿼리 파라미터의 hmac 값을 비교합니다. 두 값이 일치하면 유효한 요청으로 판단할 수 있습니다.

보안 권장 사항​

💡
timestamp 유효성 검증 (강력 권장)
  • timestamp 검증은 오래된 요청의 재전송(replay attack)을 방지하기 위한 중요한 보안 요소입니다.

  • 현재 시각과 timestamp의 차이가 5분(300,000ms)을 초과하면 만료된 요청으로 처리하는 것을 권장합니다.

  • 서버 간 시간 차이를 고려하여 미래 시각의 timestamp에 대해서도 허용 범위를 두는 것이 안전합니다.
⚠️
보안 주의사항

  • Client Secret 보호: 절대로 클라이언트 측 코드(JS 등)에 노출하지 마세요. 반드시 서버 측에서 검증을 수행해야 합니다.

  • 타이밍 공격 방지: 서명 비교 시 timing-safe 비교 함수를 사용하세요.

  • 에러 정보 최소화: 검증 실패 시 구체적인 사유(예: 비밀키 불일치 등)를 외부에 노출하지 마세요.

3. 상점 설치 앱 정보 조회 API​

설치된 APP의 상세 정보를 조회할 수 있는 API를 제공합니다. 온보딩 처리에 필요한 설치 정보 및 만료일 등을 확인할 수 있습니다.

요청​

항목내용
MethodGET
URLhttps://connect.makeshop.co.kr/api/application/:shopId/apps

Path Parameters​

ParameterRequiredDescription
shopId필수요청한 상점 ID

Query Parameters​

ParameterRequiredDescription
client_id필수조회하고자 하는 APP의 Client ID
⚠️
주의

Access Token 발급 시 사용한 client_id와 shopId를 동일하게 입력해야 합니다. 다른 값을 입력할 경우 올바른 설치 정보를 조회할 수 없습니다.

Curl 예시​

curl -X GET 'https://connect.makeshop.co.kr/api/application/{shopId}/apps?client_id={client_id}' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>'

응답 예시​

HTTP/1.1 200 OK
{
  "success": true,
  "operation": "store_application_apps.get_installed_app",
  "code": "OK",
  "message": "",
  "data": {
    "shop_uid": "makeshop",
    "client_id": "abcedfg-hijklmn-opqrstu-vwxyz",
    "app_name": "APP 테스트2",
    "app_url": "https://store.makeshop.co.kr",
    "installed_at": "2026-04-16",
    "expired_at": "2026-05-01"
  }
}

응답 필드 설명​

Field NameDescription비고
shop_uid상점 ID해당 APP을 설치한 상점의 메이크샵 고유 UID
client_id클라이언트 IDAPP 등록 시 발급된 클라이언트 ID
app_nameAPP 이름APP의 관리용 상품명
app_urlAPP URLAPP 설치 시 랜딩할 URL
installed_at설치일

APP 설치 일자 YYYY-MM-DD

expired_at만료일

APP 설치 만료일 YYYY-MM-DD