개발자·AI 연동 문서
마켓파일럿은 AI 에이전트가 직접 쓸 수 있는 마케팅 실행 API를 공개해요. ChatGPT·Claude·Cursor 같은 AI나 직접 만든 에이전트가 마케팅 서비스·상품을 조회하고, 카드 결제 링크를 만들어 사용자가 바로 결제하게 하고, 진행 상황 확인·문의 접수·회원가입까지 처리할 수 있어요. 로그인이나 API 키 없이 연결돼요.
빠른 시작
서버 주소는 하나예요: https://api.marketpilot.it/mcp. 인증 없이 추가하면 상품 조회·매장 검색·카드 결제 링크·상담 문의·회원가입을 바로 쓸 수 있어요.
| 쓰는 AI | 연결 방법 |
|---|---|
| Claude 웹·데스크톱·모바일 (무료 플랜 포함) | 설정(Customize) → 커넥터(Connectors) → 커스텀 커넥터 추가 → 위 주소 입력. 인증 칸은 비워 두세요. |
| ChatGPT 웹·데스크톱 (Plus 이상) | Settings → Apps → Advanced settings → Developer mode 켜기 → 앱 만들기 → 위 주소, Authentication 은 No authentication. |
| Claude Code | claude mcp add --transport http marketpilot https://api.marketpilot.it/mcp |
| Cursor · VS Code | mcp.json 에 { "mcpServers": { "marketpilot": { "url": "https://api.marketpilot.it/mcp" } } } |
메뉴 이름은 앱 버전에 따라 조금 다를 수 있어요. ChatGPT 무료 플랜은 직접 추가하는 커넥터를 지원하지 않아요. 내 주문 내역·포인트처럼 계정이 필요한 기능은 처음 쓸 때 앱이 계정 연결(로그인) 버튼을 띄워요. ChatGPT에서 이 기능까지 쓰려면 Authentication 을 OAuth 또는 Mixed 로 고르세요.
연결한 뒤에는 이렇게 말해 보세요: “마켓파일럿에서 우리 가게에 맞는 상품을 찾아서 결제 링크를 만들어 줘.” AI가 상품과 금액을 확인받은 뒤 결제 링크를 보여주고, 그 링크에서 카드로 결제하면 주문이 접수돼요(회원가입 불필요).
본인 계정까지 쓰려면 (선택): 헤더에 API 키
주문 내역·포인트·포인트 결제 주문은 계정의 API 키가 있어야 열려요. 헤더를 지정할 수 있는 클라이언트에서 아래처럼 등록하세요.
claude mcp add --transport http marketpilot https://api.marketpilot.it/mcp \
--header "Authorization: Bearer mk_..."REST (자체 에이전트·스크립트·자동화 도구)
# 키 없이: 카드 결제 링크 만들기
curl -X POST https://api.marketpilot.it/v1/public/ai-checkout \
-H "Content-Type: application/json" \
-d '{"items":[{"productId":12,"quantity":100}],"customerName":"홍길동"}'
# 키로: 본인 계정 기능
curl https://api.marketpilot.it/v1/ai/orders \
-H "Authorization: Bearer mk_..."AI에게 문서 URL만 던져줘도 돼요: https://api.marketpilot.it/v1/ai/docs 를 읽고 알아서 호출해요.
문서·스펙 (전부 인증 불필요)
- API 인덱스 — 뭐가 있는지 한눈에 (JSON)
- 주문 API 문서 — 인증·가입·주문 2단계·포인트·문의 전환 (마크다운, LLM이 읽기 좋음)
- OpenAPI 스펙 — 자체 에이전트·자동화 도구 연결용
- MCP 서버 명세 · API llms.txt
- 서비스·상품 카탈로그 — 적합 고객·기대 효과·단가 (JSON)
- 사이트 전체 llms.txt
엔드포인트
| 메서드 | 경로 | 설명 | 인증 |
|---|---|---|---|
| GET | /v1/public/ai-catalog | 서비스·상품 전체 카탈로그 | 공개 |
| POST | /v1/public/ai-checkout | 카드 결제 링크 만들기 (상품 id·수량 → 서버가 금액 계산) | 공개 |
| GET | /v1/public/ai-checkout/{checkoutToken} | 결제·주문 진행 상태 | 공개 |
| POST | /v1/public/ai-signup/send-code | 가입용 휴대폰 인증번호 발송 | 공개 |
| POST | /v1/public/ai-signup | 인증 확인 + 계정 생성 + API 키 발급 | 공개 |
| POST | /v1/public/ai-inquiry | 상담·견적 문의 접수 | 공개 |
| GET | /v1/public/ai-forms | 공개 문의 폼 명세 목록 | 공개 |
| GET | /v1/ai/products | 주문 가능 상품 (내 단가 반영) | 키 필요 |
| GET | /v1/ai/products/{id} | 상품 상세 + 주문 폼 필드 | 키 필요 |
| POST | /v1/ai/orders/quote | 견적 — 총액·잔액·견적 토큰 | 키 필요 |
| POST | /v1/ai/orders | 주문 확정 (토큰 + confirm) | 키 필요 |
| GET | /v1/ai/orders | 내 주문 목록 | 키 필요 |
| GET | /v1/ai/orders/{id} | 주문 진행 상황·결과·로그 | 키 필요 |
| GET | /v1/ai/point/balance | 포인트 잔액 | 키 필요 |
| POST | /v1/ai/point/charge-requests | 충전 신청 (계좌 안내) | 키 필요 |
| GET | /v1/ai/point/charge-requests/{id} | 충전 상태 확인 | 키 필요 |
주문 흐름 — 반드시 2단계
주문은 견적 → 사용자 확인 → 확정 순서를 서버에서 강제해요. 견적 없이 주문할 수 없고, 견적 토큰은 15분 유효하며 한 번만 쓸 수 있어요. AI가 사람 확인 없이 결제하는 일을 구조적으로 막기 위한 장치예요.
# 1) 견적 — 돈이 나가지 않아요
POST /v1/ai/orders/quote
{ "productId": 12, "quantity": 100, "formData": { ... } }
→ { totalAmount, pointBalance, shortfall, quoteToken }
# 2) 사용자에게 상품명·수량·총액을 보여주고 동의를 받으세요
# 3) 확정 — 포인트가 즉시 차감돼요
POST /v1/ai/orders
{ "quoteToken": "...", "productId": 12, "quantity": 100, "confirm": true }계정이 없는 사용자도 AI가 가입시킬 수 있어요
# 1) 인증번호 발송 (3분 유효)
POST /v1/public/ai-signup/send-code { "phone": "010..." }
# 2) 사용자에게 문자로 받은 번호를 물어보세요
# 3) 가입 + API 키 즉시 발급
POST /v1/public/ai-signup
{ "phone": "010...", "code": "123456", "loginId": "...", "password": "...",
"name": "...", "agreedToTerms": true, "agreedToPrivacy": true }약관 동의는 사람의 의사표시예요. AI가 임의로 true로 채우면 안 되고, 사용자에게 직접 확인받아야 해요. 이용약관 · 개인정보처리방침
제한·정책
| 가입 인증번호 발송 | IP당 시간당 5회 (인증번호 3분 유효, 1회용) |
| 회원가입 | IP당 시간당 10회 |
| 문의 접수 | IP당 시간당 20회 |
| API 키 | 계정당 최대 5개 (발급 화면에서 폐기·재발급) |
| AI 주문 1회 금액 | 최대 2,000,000원 — 초과분은 웹 주문으로 안내 |
| 견적 토큰 | 15분 유효, 1회만 사용 가능 |
아직 지원하지 않는 것
연동 전에 알아두시면 시간을 아낄 수 있어요.
- 웹훅·콜백 — 주문 상태 변경 푸시는 없어요.
GET /v1/ai/orders/{id}를 폴링하세요(진행 로그가 최신순). - 샌드박스·테스트 환경 — 별도 테스트 서버가 없어요. 주문은 실제로 집행되고 포인트가 차감되니, 시험할 땐 단가가 낮은 상품에 최소 수량으로 해주세요.
- 주문 취소 API — AI로는 취소할 수 없어요. 고객센터나 문의 접수를 이용하세요. (충전 신청은
cancel_charge_request로 취소 가능)
자주 묻는 질문
- 마켓파일럿 API로 무엇을 할 수 있나요?
- AI 에이전트가 마케팅 서비스·상품 카탈로그를 조회하고, 카드 결제 링크를 만들어 사용자가 바로 결제하게 하고, 결제·주문 진행 상황을 확인하고, 상담 문의 접수와 회원가입까지 처리할 수 있어요. 본인 계정의 API 키로 접속하면 포인트 결제 주문·주문 내역·포인트 충전도 다뤄요.
- Claude나 ChatGPT 앱에서도 연결되나요?
- 네. https://api.marketpilot.it/mcp 를 인증 없이 추가하면 돼요. Claude 웹·데스크톱·모바일은 설정의 커넥터에서 커스텀 커넥터로 주소만 넣으면 되고(무료 플랜 포함), ChatGPT는 Plus 이상에서 개발자 모드를 켠 뒤 인증 없음으로 추가해요. 로그인·API 키가 필요 없어요.
- Claude나 ChatGPT 앱에서 내 주문 내역도 볼 수 있나요?
- 네. 앱에서 "내 주문 어떻게 됐어?"처럼 물으면 계정 연결(Connect) 버튼이 떠요. 마켓파일럿에 로그인해 연결을 허용하면 주문 내역·진행 상황·포인트를 그 앱에서 바로 볼 수 있어요. API 키를 복사해 넣을 필요가 없고, 연결은 내 정보의 API 키 화면에서 언제든 끊을 수 있어요. ChatGPT는 커넥터를 만들 때 인증을 OAuth 또는 Mixed로 고르면 돼요.
- API 키는 어떻게 발급받나요?
- 상품 조회·카드 결제 링크·문의·가입은 키 없이 돼요. 본인 계정의 주문 내역·포인트까지 쓰려면 마켓파일럿에 로그인한 뒤 www.marketpilot.it/developer/api-keys 에서 발급해요(계정당 최대 5개). 계정이 없다면 AI가 공개 가입 API(POST /v1/public/ai-signup)로 가입까지 진행하고 키를 바로 받을 수도 있어요.
- MCP를 지원하나요?
- 네. https://api.marketpilot.it/mcp 가 Streamable HTTP MCP 서버예요. 인증 없이 연결되고, 그 상태로 상품 조회·매장 검색·카드 결제 링크·상담 문의·회원가입 툴을 쓸 수 있어요. Claude Code·Cursor처럼 헤더를 지정할 수 있는 클라이언트에서 Authorization 헤더에 mk_ 키를 넣으면 본인 계정 툴(포인트 결제 주문·주문 내역·포인트)까지 열려요.
- AI가 마음대로 결제하거나 주문할 수도 있나요?
- 아니요. 카드 결제 링크는 만드는 것만으로는 돈이 움직이지 않고, 사용자가 링크를 열어 품목·금액을 확인한 뒤 직접 결제해야 해요. 금액은 AI가 아니라 서버가 계산해요. 포인트 결제 주문은 견적(quote) → 사용자 확인 → 확정(confirm) 2단계를 서버에서 강제하고, AI 경유 주문에는 1회 금액 상한이 걸려 있어요.
- 결제는 어떻게 하나요?
- AI가 카드 결제 링크를 만들어 주면 사용자가 그 링크에서 카드·간편결제로 바로 결제해요. 회원가입이나 포인트 충전이 필요 없어요. 본인 계정의 선불 포인트(1P=1원)로 결제할 수도 있고, 포인트 충전은 무통장 입금으로 해요.
문의
연동 중 막히면 info@marketpilot.it로 알려주세요. AI가 직접 문의를 넣을 수도 있어요: POST /v1/public/ai-inquiry
일반 이용 방법은 이용 가이드를 참고하세요.