API 공통

API 호출하기

Bearer 토큰으로 쇼핑몰 데이터를 읽고 씁니다. 주소 · 응답 · 오류 형식을 정리했습니다.

기본 규칙

기본 주소 https://api.mallstory.kr/v1 — 버전이 주소에 고정됩니다.
모든 요청에 Authorization: Bearer {access_token} 를 붙입니다.
쇼핑몰은 경로로 가리킵니다: /v1/shop/{shop_unique}/{resource}. 토큰이 묶인 쇼핑몰과 다르면 403 입니다.
요청 · 응답 본문은 JSON(UTF-8)입니다.

bash

curl 'https://api.mallstory.kr/v1/shop/66f1c0a2b3d4e5f601234567/orders?limit=10' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'

401 과 WWW-Authenticate

토큰이 없거나 만료 · 폐기되면 401 과 함께 아래 헤더가 옵니다. 클라이언트는 이 헤더로 어디서 인가를 받을지 찾습니다(RFC 9728).

http

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.mallstory.kr/.well-known/oauth-protected-resource/v1"

MCP 서버(/mcp/{shop_id})는 같은 자리에 /.well-known/oauth-protected-resource/mcp/{shop_id} 를 싣습니다. → 인가 서버 찾기

오류 형식

OAuth 엔드포인트 (/oauth · /api/oauth)

OAuth 표준 형식입니다.

json

{"error": "invalid_grant", "error_description": "code 가 만료되었거나 이미 사용되었습니다."}

error	언제
`invalid_request`	필수 파라미터가 없거나 형식이 틀림(state 누락 포함)
`invalid_client`	Client ID · 비밀 키가 틀렸거나 앱이 중지됨
`invalid_grant`	code · refresh token 이 만료 · 재사용 · 폐기됨, redirect_uri · code_verifier 불일치
`invalid_scope`	앱의 권한 상한을 넘는 스코프를 요청함
`access_denied`	판매자가 동의 화면에서 거절함
`unsupported_grant_type`	authorization_code · refresh_token 이 아닌 grant_type

REST 리소스 (/v1)

json

{"code": "ShopNotExist", "message": "쇼핑몰이 없습니다.", "request_id": "req_5f2c9e0b8a4d4c1e9f3a7b6d2e1c0a98"}

HTTP	뜻	할 일
400	파라미터가 틀림	message 를 보고 값을 고칩니다
401	토큰 없음 · 만료 · 폐기	갱신하거나 다시 인가를 받습니다
403	권한(스코프) 부족 · 다른 쇼핑몰	필요한 스코프로 다시 인가를 받습니다
404	대상이 없음	식별자를 확인합니다
429	호출 한도를 넘음	`Retry-After` 초 뒤 다시 보냅니다 — 호출 제한
5xx	서버 오류	잠시 뒤 다시 시도합니다

요청 ID

/v1 · /mcp · /api/oauth 의 모든 응답에 X-Request-Id 헤더가 붙습니다. /v1 의 오류 본문에는 같은 값이 request_id 로도 실립니다.

http

HTTP/1.1 403 Forbidden
X-Request-Id: req_993be1dd8ec041a4b91dd6ec7f6b9c2a
WWW-Authenticate: Bearer error="insufficient_scope", scope="customers:read"

{"code":"InsufficientScope","message":"customers:read 권한이 없습니다.","request_id":"req_993be1dd8ec041a4b91dd6ec7f6b9c2a"}

문의할 때 이 값을 함께 보내 주세요. 그 한 건의 경로 · 상태 · 오류를 바로 찾습니다. 실패한 호출은 로그에 요청 ID 를 꼭 남기세요.
직접 정한 ID 를 보내도 됩니다 — 요청 헤더 X-Request-Id 에 영문 · 숫자 · . _ : - 8 ~ 128자를 넣으면 그 값을 그대로 씁니다(자기 서비스의 추적 ID 와 맞출 때). 모양이 다르면 새로 만듭니다.
판매자는 쇼핑몰 관리자 > 설정 > 외부연동 설정의 호출 기록에서 요청 ID · 앱 · 결과 · 오류 code · 기간으로 그 쇼핑몰의 호출을 찾고, 앱 관리 > 앱 열람의 최근 호출에서 앱별 7일 요약을 봅니다. 기록에는 경로 · 상태 · 오류와 요청의 모양만 남습니다 — 쿼리는 페이지 · 정렬 같은 값만, 본문은 키와 형식(string · number · array(개수) …)만이고 보낸 값 · 토큰은 남지 않습니다. 30일 뒤 지워집니다.

기본 규칙#

401 과 WWW-Authenticate#