개발자·AI 연동 문서
마켓파일럿은 AI 에이전트가 직접 쓸 수 있는 마케팅 실행 API를 공개해요. ChatGPT·Claude·Cursor 같은 AI나 직접 만든 에이전트가 마케팅 서비스·상품을 조회하고, 견적을 뽑고, 사용자 확인을 받아 주문하고, 진행 상황 확인·포인트 충전·문의 접수·회원가입까지 처리할 수 있어요.
빠른 시작
연결 방식은 두 가지예요. 하나만 골라도 되고 둘 다 써도 돼요.
① MCP (Claude Code·Cursor 등)
claude mcp add --transport http marketpilot https://api.marketpilot.it/mcp \
--header "Authorization: Bearer mk_..."② REST (그 외 전부 — GPTs·자체 에이전트·스크립트)
curl https://api.marketpilot.it/v1/ai/products \
-H "Authorization: Bearer mk_..."AI에게 문서 URL만 던져줘도 돼요: https://api.marketpilot.it/v1/ai/docs 를 읽고 알아서 호출해요.
문서·스펙 (전부 인증 불필요)
- API 인덱스 — 뭐가 있는지 한눈에 (JSON)
- 주문 API 문서 — 인증·가입·주문 2단계·포인트·문의 전환 (마크다운, LLM이 읽기 좋음)
- OpenAPI 스펙 — GPTs Actions에 그대로 등록 가능
- MCP 서버 명세 · API llms.txt
- 서비스·상품 카탈로그 — 적합 고객·기대 효과·단가 (JSON)
- 사이트 전체 llms.txt
엔드포인트
| 메서드 | 경로 | 설명 | 인증 |
|---|---|---|---|
| GET | /v1/public/ai-catalog | 서비스·상품 전체 카탈로그 | 공개 |
| 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회만 사용 가능 |
아직 지원하지 않는 것
연동 전에 알아두시면 시간을 아낄 수 있어요.
- OAuth — 인증은 API 키(
mk_)만 지원해요. 그래서 Claude 웹·데스크탑이나 ChatGPT 커넥터처럼 헤더를 직접 넣을 수 없는 클라이언트에서는 MCP 연결이 안 돼요. Claude Code·Cursor·자체 에이전트처럼 헤더를 지정할 수 있는 환경에서 사용하세요. - 웹훅·콜백 — 주문 상태 변경 푸시는 없어요.
GET /v1/ai/orders/{id}를 폴링하세요(진행 로그가 최신순). - 샌드박스·테스트 환경 — 별도 테스트 서버가 없어요. 주문은 실제로 집행되고 포인트가 차감되니, 시험할 땐 단가가 낮은 상품에 최소 수량으로 해주세요.
- 주문 취소 API — AI로는 취소할 수 없어요. 고객센터나 문의 접수를 이용하세요. (충전 신청은
cancel_charge_request로 취소 가능)
자주 묻는 질문
- 마켓파일럿 API로 무엇을 할 수 있나요?
- AI 에이전트가 마케팅 서비스·상품 카탈로그를 조회하고, 견적을 뽑고, 사용자 확인을 받아 주문하고, 주문 진행 상황을 확인하고, 포인트 잔액 조회·충전 신청, 상담 문의 접수, 심지어 회원가입까지 처리할 수 있어요.
- 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 등 MCP 클라이언트에서 Authorization 헤더에 mk_ 키를 넣어 연결하면 상품 조회·견적·주문·포인트·문의 툴을 바로 쓸 수 있어요.
- AI가 마음대로 주문할 수도 있나요?
- 아니요. 주문은 견적(quote) → 사용자 확인 → 확정(confirm) 2단계를 서버에서 강제해요. 견적 토큰은 15분 유효하고 1회만 쓸 수 있으며, AI 경유 주문에는 1회 금액 상한이 걸려 있어요.
- 결제는 어떻게 하나요?
- AI 주문은 선불 포인트(1P=1원)로 결제돼요. 포인트가 부족하면 충전 신청 API가 무통장 입금 계좌를 안내하고, 입금자명과 금액이 일치하면 보통 몇 분 안에 자동 충전돼요. 카드·간편결제는 웹사이트 주문에서 쓸 수 있어요.
문의
연동 중 막히면 info@marketpilot.it 또는 고객센터 1551-6151로 알려주세요. AI가 직접 문의를 넣을 수도 있어요 — POST /v1/public/ai-inquiry
일반 이용 방법은 이용 가이드를 참고하세요.