TL;DR

  • Mercemur가 하나의 스토어에 REST API, MCP 서버, CLI라는 세 가지 접근 경로를 제공하며 동일한 비밀 키와 권한 범위를 공유하는 구조임
  • REST API가 카탈로그·주문·고객·가격·금액 전반에 걸쳐 571개 작업을 제공함
  • MCP 서버를 통해 Claude Desktop·통합 개발 환경(IDE)·다른 에이전트가 라이브 스토어프론트를 직접 읽고 쓰는 방식임
  • 권한이 66개 그룹의 136개 범위로 나뉘며 읽기·쓰기·삭제 권한을 별도로 부여하는 보안 모델임
  • 모든 쓰기 요청에 Idempotency-Key가 필요하고 커서 기반 순방향 페이징과 오류 코드 중심의 계약을 적용함

하나의 스토어를 위한 세 가지 접근 경로

  • Mercemur가 모든 상점 운영자에게 동일한 스토어로 연결되는 세 가지 경로를 제공함.
  • 코드에서 호출하는 REST API
  • 인공지능 에이전트가 직접 작업하는 MCP 서버
  • 로컬 컴퓨터의 파일처럼 스토어프론트를 편집하는 명령줄 인터페이스(CLI)
  • 세 경로 모두 동일한 비밀 키와 동일한 권한 범위로 관리되며, 사용하는 경로와 관계없이 하나의 권한 부여가 적용됨.

시작하기

  • API: 카탈로그·주문·고객·가격·금액 전반에 걸쳐 571개 작업을 제공하며, HTTP 요청을 보낼 수 있는 모든 플랫폼에서 호출 가능함.
  • MCP: Claude Desktop, 통합 개발 환경(IDE), 다른 에이전트 등의 인공지능 클라이언트를 하나의 엔드포인트에 연결하면 라이브 스토어프론트를 읽고 쓸 수 있음.
  • CLI: 스토어프론트를 디스크로 가져와 원하는 편집기에서 수정하고, 라이브 미리보기로 확인한 뒤 준비가 되면 게시하는 방식임.
  • 모든 요청의 REST API 기본 URL은 https://api.mercemur.com/api/v1임.
  • MCP 엔드포인트는 https://mcp.mercemur.com/mcp임.

REST API 세부 사항

  • 빠른 시작: 키를 생성하고 5분 이내에 첫 요청을 실행하는 절차임.
  • API 레퍼런스: 모든 엔드포인트와 자체 스토어를 대상으로 실행할 수 있는 플레이그라운드를 제공함.
  • 요청 한도: 스로틀링과 올바른 백오프 처리 방식을 설명함.

인증과 보안

  • API 키: 비밀 키의 생성 방법과 안전한 교체 방법을 다룸.
  • 권한 범위: 읽기·쓰기·삭제가 별도 권한으로 분리되며, 66개 그룹에 걸친 136개 범위로 구성됨.
  • 오류 처리: 모든 상태 코드의 모든 거부 응답에 하나의 오류 봉투 형식을 적용함.

요청 만들기

  • 멱등성: 모든 쓰기 요청에 Idempotency-Key가 필요하며 안전한 재시도를 지원함.
  • 페이지 매김: 순방향 전용 커서 기반 방식이며, 커서는 발급한 경로에 서명되고 연결됨.
  • 금액: 모든 금액을 통화의 최소 단위로 나타내는 정수로 처리함.

단일 엔드포인트만으로는 추측할 수 없는 네 가지 사항

  • 단일 예시 요청만으로는 알 수 없으며 통합 과정에서 문제를 일으킬 수 있는 규칙 네 가지임.

금액은 항상 최소 단위의 정수임

  • usd 필드의 1999는 19.99 미국 달러를 의미함.
  • 이 API 어디에도 소수 금액은 존재하지 않으며, 소수를 허용하는 필드도 없음.
  • 일본 엔(JPY)처럼 최소 단위가 없는 통화는 전체 금액을 그대로 입력함.

읽기와 쓰기는 별도 권한임

  • write_products 권한만으로는 해당 키가 카탈로그를 읽을 수 없음.
  • 삭제는 다시 별도의 권한인 write_products:delete를 요구함.
  • 기록을 최신 상태로 유지하는 키도 삭제 권한을 별도로 부여하지 않으면 기록을 삭제할 수 없음.

모든 쓰기 요청에 Idempotency-Key가 필요함

  • 재시도하는 경우에만 선택적으로 필요한 항목이 아니라 모든 쓰기 요청에 필수임.
  • 헤더가 없는 요청은 idempotency_key_required 오류로 거부됨.
  • 동일한 키로 요청을 다시 보내면 작업을 두 번 실행하지 않고 저장된 응답을 반환함.

페이지 매김은 순방향 전용 커서 방식임

  • 페이지 번호나 오프셋 파라미터는 존재하지 않음.
  • 이전 응답의 page.next_cursor를 같은 엔드포인트의 ?after= 값으로 보내는 방식임.
  • 다른 컬렉션에서 발급된 커서는 거부됨.

메시지가 아닌 코드에 따라 분기함

  • 모든 상태 코드의 모든 API 거부 응답은 동일한 본문 구조를 사용함.
  • 오류에는 계약상 안전하게 분기할 수 있는 code와 사람이 로그를 읽기 위한 영어 문장인 message가 포함됨.
  • code가 계약의 일부이며, message의 표현은 계약에 포함되지 않음.