TutuPP
69개 MCP 도구 + 완전한 REST API

TutuPP API 문서

REST API 또는 MCP 프로토콜을 통해 AI 어시스턴트가 사진 인쇄, 문서 인쇄, 주문 관리 등 모든 작업을 직접 수행하게 하세요. Claude, Gemini, Codex, Copilot 등 21개 주요 AI 클라이언트를 지원합니다.

빠른 시작

세 단계로 연동하고 바로 AI로 인쇄를 시작하세요.

1

계정 등록

TutuPP 웹사이트에 방문해 문자 인증코드로 빠르게 가입하세요.

2

API Key 생성

계정 센터의 「API 키」 페이지에서 원클릭으로 키를 만들어 바로 사용하세요.

3

요청 보내기

API Key로 REST API를 호출하거나, AI 클라이언트에 설정해 MCP를 사용하세요.

인증 방식

모든 API 요청은 HTTP 헤더에 API Key를 담아 인증합니다.

Authorization: Bearer tk_YOUR_API_KEY

Base URL

https://tutupp.com

응답 형식

Content-Type: application/json

MCP 엔드포인트

POST https://tutupp.com/api/mcp
오픈 플랫폼: 가입 후 승인 없이 API Key를 만들어 모든 API와 MCP 기능을 즉시 사용하세요.

MCP 통합

MCP (Model Context Protocol)는 Anthropic이 제안한 개방형 프로토콜로, AI 어시스턴트가 외부 도구를 직접 호출하게 합니다.

설정 후에는 자연어로 AI에게 「문서 업로드 → 주문 생성 → 잔액 결제」 전체 흐름을 실행하게 할 수 있습니다.

프로토콜 정보

엔드포인트：https://tutupp.com/api/mcp

프로토콜：JSON-RPC 2.0 over Streamable HTTP

메서드：initialize · tools/list · tools/call

파일 업로드：multipart/form-data 확장(message part + file parts, base64 불필요, 100MB+)과 표준 application/json를 지원

AI 클라이언트 선택 21개

Claude Code — 터미널 CLI

추가 (Add)

claude mcp add --transport http tutupp https://tutupp.com/api/mcp --header "Authorization: Bearer tk_YOUR_API_KEY"

--scope user는 전역, --scope project는 현재 프로젝트에만 적용

키 교체 (Replace)

claude mcp remove tutupp && claude mcp add --transport http tutupp ...(새 키)

제거 (Remove)

claude mcp remove tutupp

AI 대화 예시

나： 바탕화면의 report.pdf를 A4 흑백으로 한 부 인쇄하고 잔액으로 결제해 줘

AI가 자동으로 호출:

1. upload_document → 파일 업로드

2. get_print_prices → A4 흑백 가격 조회

3. create_order → 주문 생성

4. pay_with_balance → 잔액 결제

AI： 완료! 주문번호 PP2026040612345, A4 흑백 1부, 잔액에서 ¥0.50 차감했습니다.

REST API 레퍼런스

API Key로 아래 모든 엔드포인트에 접근할 수 있으며, UI의 모든 기능을 포함합니다.

문서 관리

POST /api/documents/upload
GET /api/documents
GET /api/documents/{id}
DELETE /api/documents/{id}

사진 관리

POST /api/photos/upload
GET /api/photos/{id}
DELETE /api/photos/{id}
GET /api/photos/{id}/quality-check?size={size}

주문

POST /api/orders
GET /api/orders
GET /api/orders/{id}
PUT /api/orders/{id}/cancel
GET /api/orders/track/{order_no}
GET /api/orders/{id}/tracking

결제

POST /api/payment/create
POST /api/payment/balance
GET /api/payment/status/{order_id}

잔액

GET /api/user/balance
POST /api/user/balance/topup
GET /api/user/balance/transactions

쿠폰

GET /api/user/coupons
GET /api/user/coupons/available
POST /api/user/coupons/redeem

배송 주소

GET /api/addresses
POST /api/addresses
PUT /api/addresses/{id}
DELETE /api/addresses/{id}
POST /api/addresses/parse

대리 주문(사전 주문)

GET /api/user/pre-orders
POST /api/user/pre-orders
GET /api/user/pre-orders/{id}
PUT /api/user/pre-orders/{id}
PUT /api/user/pre-orders/{id}/status
POST /api/user/pre-orders/{id}/submissions/{sid}/review
PUT /api/user/pre-orders/{id}/submissions/{sid}/cancel

사전 주문 공유

GET /api/share/{code}
POST /api/share/{code}/submit
GET /api/share/{code}/submissions/{sid}
GET /api/share/{code}/my-submissions

사후 지원

GET /api/user/after-sales
POST /api/after-sales

지역 및 배송

GET /api/regions
GET /api/regions/{id}
GET /api/regions/tree
GET /api/regions/coverage
GET /api/regions/{city_id}/city-coverage
GET /api/regions/{id}/express-delivery
GET /api/regions/{id}/pickup-points
GET /api/agents/referral/{code}
GET /api/shipping/config
GET /api/shipping/carriers

설정 조회

GET /api/prices
GET /api/print-options/sizes
GET /api/print-options/paper-types

AI 사진 복원

POST /api/photos/{id}/restore
GET /api/restorations/{id}

사용자 정보

GET /api/auth/me
PUT /api/auth/me

인쇄 상태

GET /api/printer/status
GET /api/print-queue/status
GET /api/orders/auto-print-schedule

API 키 자가 관리

GET /api/user/api-keys
POST /api/user/api-keys
DELETE /api/user/api-keys/{id}

시스템 상태

GET /api/health

MCP 도구 목록69개

아래 모든 도구는 MCP 프로토콜로 호출할 수 있으며, AI 클라이언트는 설정 후 자동으로 발견합니다.

문서 관리

upload_document 문서 업로드 (PDF/DOC/DOCX/XLS/XLSX/PPT/PPTX) — one of: file_url / content (base64) / file_path (curl)
list_documents 현재 사용자가 업로드한 모든 문서 목록
get_document_info 문서 상세 조회 (페이지 수, 파일 크기 등)
delete_document 문서 삭제 (유효 주문에 미연결인 경우만)

사진 관리

upload_photo 사진 업로드 (JPG/PNG/WebP/HEIC) — one of: file_url / content (base64) / file_path (curl)
get_photo 사진 상세 정보 조회
delete_photo 사진 삭제 (유효 주문에 미연결인 경우만)
check_photo_quality 지정 크기에서 사진 인쇄 품질 확인 (DPI)

주문

create_order 인쇄 주문 생성
list_orders 현재 사용자의 모든 주문 목록
get_order_status 주문 상태 및 상세 조회
cancel_order 주문 취소 (결제 대기 상태만)
track_order 주문 번호로 주문 정보 조회 (공개)
get_order_tracking 주문 배송 추적 정보 조회

결제 및 잔액

create_payment 제3자 결제 생성 (payment_url 반환, 브라우저에서 열어 결제)
pay_with_balance 계정 잔액으로 주문 결제
get_payment_status 주문 결제 상태 조회
create_topup 잔액 충전 주문 생성 (payment_url 반환)
get_balance 계정 잔액 조회 (총액/동결/사용가능)
get_balance_transactions 잔액 거래 내역 조회

쿠폰

list_coupons 현재 사용자의 쿠폰 목록
get_available_coupons 사용 가능 쿠폰 조회 (금액으로 필터)
redeem_coupon 교환 코드로 쿠폰 받기

배송 주소

list_addresses 배송 주소 목록
create_address 배송 주소 추가
update_address 배송 주소 수정
delete_address 배송 주소 삭제
parse_address 주소 텍스트 스마트 파싱

대리 주문(사전 주문)

list_pre_orders 모든 사전 주문 목록
create_pre_order 사전 주문 생성 (링크 공유로 타인이 제출)
get_pre_order 사전 주문 상세 조회 (모든 제출 포함)
update_pre_order 사전 주문 설정 수정
update_pre_order_status 사전 주문 상태 변경
review_submission 사전 주문 제출 검토
cancel_submission 특정 제출 취소

사전 주문 공유

get_share_info 공유 링크 정보 조회
submit_share_photos 공유 링크에 사진 제출
get_submission_status 제출 상태 및 사진 상세 조회
list_my_submissions 특정 공유 링크의 모든 제출 목록

사후 지원

list_after_sales 현재 사용자의 사후 지원 기록 목록
create_after_sales 사후 지원 신청 생성 (환불/재인쇄/재발송)

지역 및 배송

list_regions 지역 목록 조회
get_region 지역 상세 및 하위 지역 조회
get_region_tree 전체 지역 트리 조회 (성→시→구/현)
get_region_coverage 대리점 커버리지 통계 조회
get_city_coverage 도시 내 구/현별 커버리지 조회
get_agent_by_referral 추천 코드로 대리점 찾기
check_express_delivery 당일 배송 지원 여부 확인
get_shipping_config 배송 설정 조회 (전역)
get_shipping_carriers 택배사 목록 조회 (외곽 추가 요금 포함)
list_pickup_points 픽업 지점 목록 조회

설정 및 상태

get_print_prices 인쇄 가격 + 수량 할인 단계 조회
get_print_options 사용 가능 크기와 용지 종류 조회
get_printer_status 프린터 상태 조회
get_queue_status 인쇄 대기열 상태 조회

사용자 정보

get_profile 현재 사용자의 프로필 조회
update_profile 사용자 닉네임 수정

AI 사진 복원

restoration_preview 사진에 AI 복원 미리보기 실행
get_restoration AI 복원 작업 결과 조회

API 키 자가 관리

list_api_keys 현재 사용자의 모든 API Key 목록
create_api_key 새 API Key 생성 (전체 키는 한 번만 표시)
revoke_api_key 특정 API Key 취소

시스템

health_check 서비스 상태 확인 (데이터베이스/결제 게이트웨이/버전)
get_auto_print_schedule 자동 인쇄 시간대 설정 조회

주문 리뷰

submit_order_review 단건 주문 리뷰 제출 (3차원 평점 + 코멘트); ON CONFLICT 멱등; 제한 5/h
batch_submit_order_reviews 일괄 리뷰 (최대 20 · 단일 트랜잭션 · 원자적); 원탭 5성
list_my_order_reviews 내 리뷰 목록 (페이지네이션 엔벨로프)
get_order_review 단건 리뷰 상세 조회 (공식 답변 포함)
mark_order_review_read 공식 답변 읽음 표시 (CTE로 재생 방지, nav 배지 수 감소)

코드 예시

「가격 조회 → 파일 업로드 → 주문 생성 → 잔액 결제」 전체 흐름의 완전한 예시.

# 查询打印价格
curl https://tutupp.com/api/prices \
  -H "Authorization: Bearer tk_YOUR_API_KEY"

# 上传文档
curl -X POST https://tutupp.com/api/documents/upload \
  -H "Authorization: Bearer tk_YOUR_API_KEY" \
  -F "file=@report.pdf"

# 创建订单
curl -X POST https://tutupp.com/api/orders \
  -H "Authorization: Bearer tk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{
      "document_id": "uuid-here",
      "size": "A4",
      "paper_type": "matte",
      "quantity": 1
    }],
    "delivery_method": "pickup"
  }'

# 余额支付
curl -X POST https://tutupp.com/api/payment/balance \
  -H "Authorization: Bearer tk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order_id": "uuid-here"}'

일반적인 워크플로

파일 업로드 가격 조회 주문 생성 잔액 결제 완료

오류 처리

API는 표준 HTTP 상태 코드를 사용하며, 오류 응답에는 JSON 형식의 오류 정보가 포함됩니다.

// 오류 응답 형식
{
  "error": "오류 설명"
}
400
요청 매개변수 오류 필수 항목 누락, 형식 오류
401
인증되지 않음 API 키 누락 또는 무효
403
권한 없음 작업 금지, 권한 부족
404
리소스 없음 주문/문서/사진 ID 없음
409
충돌 사진이 주문에 연결되어 삭제 불가
413
파일이 너무 큼 문서 50MB 초과 / 사진 120MB 초과
422
비즈니스 규칙 미충족 잔액 부족, 주문 취소 불가
429
요청이 너무 많음 API 속도 제한 초과
500
서버 내부 오류 잠시 후 다시 시도하거나 지원팀에 문의하세요
속도 제한: 로그인 / 가입 / 인증코드 같은 민감한 쓰기 작업만 공격 방어 대상이며 일반 사용으로는 절대 발동하지 않고, 임계값은 관리자 콘솔에서 설정할 수 있습니다. 응답에는 retry_after_seconds 필드 + Retry-After 헤더가 포함됩니다.

시작할 준비가 되셨나요?

계정을 만들고 API Key를 생성해 AI에게 인쇄를 맡기세요.

지금 가입 API 키 관리