API 연동

API 레퍼런스 · 기본 커넥터

클립톡이 업종별로 제공하는 기본 커넥터의 스펙입니다. 기본 커넥터를 불러와 바로 연결한 다음, 작업·경로·파라미터를 우리 서비스에 맞게 자유롭게 커스터마이징할 수 있습니다.

#기본 커넥터란

업종마다 AI 상담봇이 자주 쓰는 작업(본인확인, 조회, 취소·변경)을 미리 정의해 둔 API 스펙입니다. 스펙의 기본 주소는 프로젝트에 등록한 내 도메인을 기준으로 https://www.mydomain.com/api/업종 형태로 자동으로 채워집니다.

1
내 도메인 등록
프로젝트를 만들 때 내 도메인(예: www.mydomain.com)을 입력합니다. 나중에 프로젝트 → 일반 탭에서 바꿀 수 있습니다.
2
기본 커넥터 불러오기
프로젝트 → AI 상담봇 → API 스펙 만들기 → 시작하기에서 업종에 맞는 기본 커넥터를 고릅니다. Base URL 이 내 도메인 기준으로 채워집니다.
3
API 구현 또는 연결
내 서버에 아래 스펙과 같은 경로·응답으로 API 를 만들면 그대로 동작합니다. 이미 있는 API 가 있다면 다음 단계에서 스펙을 그 API 에 맞춥니다.
4
커스터마이징
필요 없는 작업은 끄거나 지우고, 새 작업을 추가하고, 경로·파라미터 이름·설명·인증 방식을 우리 API 에 맞게 고칩니다. 설명은 AI 가 도구를 고르는 기준이 되므로 우리 서비스 용어로 다듬으면 좋습니다.
5
보안키 · 테스트 · 연결
보안키 탭에서 API 키를 저장하고, API 테스트 탭에서 호출해 본 뒤 저장 후 AI 상담봇에 연결을 누릅니다.

API 를 만들기 전에 흐름부터 보고 싶다면 AI 상담봇 설정의 샘플 커넥터로 연결해 보세요. 같은 스펙의 클립톡 데모 API 에 연결되어 채팅창에서 바로 체험할 수 있습니다.

# 쇼핑몰
https://www.mydomain.com/api/shop

# 배송대행·구매대행
https://www.mydomain.com/api/forwarding

# 여행사
https://www.mydomain.com/api/travel

# 병원·미용실 예약
https://www.mydomain.com/api/clinic

# 구독 서비스(SaaS)
https://www.mydomain.com/api/subscription

# 교육·학원
https://www.mydomain.com/api/academy

# 호텔·펜션 숙박
https://www.mydomain.com/api/stay

# 헬스장·필라테스
https://www.mydomain.com/api/fitness

#공통 규칙

항목	설명
`인증`	기본값은 `Authorization: Bearer 키`. 스튜디오의 기본 설정에서 API 키 헤더·Basic·쿼리 파라미터 방식으로 바꿀 수 있습니다.
`형식`	요청·응답 모두 JSON. 성공 응답은 ok: true 와 데이터를 함께 돌려줍니다.
`오류`	2xx 가 아닌 상태 코드와 `{ "ok": false, "error", "message" }`. message 는 AI 가 고객에게 상황을 설명하는 근거가 됩니다.
`본인확인`	`POST /verify` 가 `customer.id` 를 돌려주면, 이후 경로의 `{customer_id}` 는 클립톡이 자동으로 채웁니다. 고객이 다른 사람의 ID 를 넣을 수 없습니다.
`처리 작업`	취소·변경처럼 데이터를 바꾸는 작업은 먼저 `dry_run: true` 로 호출해 미리보기(`summary` 문자열 배열)를 받고, 고객이 동의하면 `dry_run` 없이 다시 호출합니다.
`소유권 검증`	고객 정보를 다루는 API 는 서버에서도 customer_id 의 데이터인지 꼭 확인하세요.

{
  "ok": true,
  "customer": { "id": "cus_1001", "name": "김클립" }
}

#쇼핑몰 기본 커넥터

주문번호로 본인확인 → 주문 목록·상세 → 배송 조회 → 배송 전 주문 취소, 상품 재고·가격 검색. 기본 주소는 https://www.mydomain.com/api/shop 입니다.

작업	요청	설명 · 주요 파라미터
`verify_customer`	POST `/verify`	본인확인 `order_no, phone_last4`
`list_orders`	GET `/customers/{customer_id}/orders`	주문 목록 `status`
`get_order`	GET `/customers/{customer_id}/orders/{order_no}`	주문 상세·배송 조회 `order_no*`
`cancel_order`	POST `/customers/{customer_id}/orders/{order_no}/cancel`	주문 취소 (미리보기 → 확정) `order_no*, reason`
`search_products`	GET `/products`	상품 검색 `q*`

curl -X POST https://www.mydomain.com/api/shop/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"order_no":"DM-10001","phone_last4":"1234"}'

#쇼핑몰 · 본인확인

POST/verify

주문번호와 휴대폰 뒷 4자리로 고객을 확인합니다. 응답의 customer.id 가 이후 작업의 {customer_id} 로 쓰입니다.

Body	타입	설명
`order_no *`	string	주문번호
`phone_last4 *`	string	휴대폰 뒷 4자리

curl -X POST https://www.mydomain.com/api/shop/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"order_no":"DM-10001","phone_last4":"1234"}'

#쇼핑몰 · 주문 목록

GET/customers/{customer_id}/orders

고객의 주문 목록입니다.

파라미터	위치	설명
`customer_id *`	path	본인확인에서 받은 고객 ID
`status`	query	paid \| preparing \| shipped \| delivered \| cancelled

curl https://www.mydomain.com/api/shop/customers/cus_1001/orders \
  -H 'Authorization: Bearer YOUR_API_KEY'

#쇼핑몰 · 주문 상세

GET/customers/{customer_id}/orders/{order_no}

주문 1건의 상품·금액·배송 정보(택배사, 운송장 번호, 배송 조회 링크)입니다.

curl https://www.mydomain.com/api/shop/customers/cus_1001/orders/DM-10001 \
  -H 'Authorization: Bearer YOUR_API_KEY'

#쇼핑몰 · 주문 취소

POST/customers/{customer_id}/orders/{order_no}/cancel

결제완료·상품준비중 주문만 취소할 수 있습니다. dry_run: true 면 환불 예정액 미리보기만 돌려줍니다.

Body	타입	설명
`dry_run`	boolean	미리보기 여부
`reason`	string	취소 사유

curl -X POST https://www.mydomain.com/api/shop/customers/cus_1001/orders/DM-10002/cancel \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"dry_run":true}'

#쇼핑몰 · 상품 검색

GET/products

파라미터	위치	설명
`q *`	query	상품명 검색어 또는 SKU

curl 'https://www.mydomain.com/api/shop/products?q=텀블러' \
  -H 'Authorization: Bearer YOUR_API_KEY'

#배송대행·구매대행 기본 커넥터

사서함번호로 본인확인 → 신청서 목록·상세(트래킹) → 신청 취소, 예상 배송비와 해외 창고 주소 안내. 기본 주소는 https://www.mydomain.com/api/forwarding 입니다.

작업	요청	설명 · 주요 파라미터
`verify_customer`	POST `/verify`	본인확인 `member_code, name`
`list_applications`	GET `/customers/{customer_id}/applications`	신청서 목록 `status`
`get_application`	GET `/customers/{customer_id}/applications/{application_no}`	신청서 상세·트래킹 `application_no*`
`cancel_application`	POST `/customers/{customer_id}/applications/{application_no}/cancel`	신청 취소 (미리보기 → 확정) `application_no*, reason`
`estimate_shipping`	GET `/rates`	예상 배송비 `country, weight_kg`
`list_warehouses`	GET `/warehouses`	해외 창고 주소

curl -X POST https://www.mydomain.com/api/forwarding/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"member_code":"CT1001","name":"박배송"}'

#여행사 기본 커넥터

예약번호로 본인확인 → 예약 목록·상세 → 예약 취소, 여행 상품 검색과 취소 규정 안내. 기본 주소는 https://www.mydomain.com/api/travel 입니다.

작업	요청	설명 · 주요 파라미터
`verify_customer`	POST `/verify`	본인확인 `booking_no, name`
`list_bookings`	GET `/customers/{customer_id}/bookings`	예약 목록
`get_booking`	GET `/customers/{customer_id}/bookings/{booking_no}`	예약 상세 `booking_no*`
`cancel_booking`	POST `/customers/{customer_id}/bookings/{booking_no}/cancel`	예약 취소 (미리보기 → 확정) `booking_no*, reason`
`search_products`	GET `/products`	여행 상품 검색 `city, q`
`get_cancellation_policy`	GET `/cancellation-policy`	취소 규정

curl -X POST https://www.mydomain.com/api/travel/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"booking_no":"TR-260001","name":"정여행"}'

#병원·미용실 예약 기본 커넥터

시술·진료 안내와 빈 시간 조회, 신규 예약, 예약번호로 본인확인 → 내 예약 조회 → 예약 변경·취소. 기본 주소는 https://www.mydomain.com/api/clinic 입니다.

작업	요청	설명 · 주요 파라미터
`verify_customer`	POST `/verify`	본인확인 `reservation_no, name`
`list_services`	GET `/services`	시술·진료 안내
`find_slots`	GET `/slots`	빈 시간 조회 `date*`
`create_reservation`	POST `/reservations`	신규 예약 (미리보기 → 확정) `service_code, datetime, name, phone`
`list_reservations`	GET `/customers/{customer_id}/reservations`	내 예약 조회
`change_reservation`	POST `/customers/{customer_id}/reservations/{reservation_no}/change`	예약 변경 (미리보기 → 확정) `reservation_no, new_datetime`
`cancel_reservation`	POST `/customers/{customer_id}/reservations/{reservation_no}/cancel`	예약 취소 (미리보기 → 확정) `reservation_no*`

curl -X POST https://www.mydomain.com/api/clinic/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"reservation_no":"RV-7001","name":"정예약"}'

#구독 서비스(SaaS) 기본 커넥터

요금제 안내, 이메일·계정번호로 본인확인 → 구독 상태·청구서 → 영수증 재발송, 요금제 변경, 해지 예약. 기본 주소는 https://www.mydomain.com/api/subscription 입니다.

작업	요청	설명 · 주요 파라미터
`verify_customer`	POST `/verify`	본인확인 `email, account_no`
`list_plans`	GET `/plans`	요금제 안내
`get_subscription`	GET `/customers/{customer_id}/subscription`	구독 상태
`list_invoices`	GET `/customers/{customer_id}/invoices`	청구서 목록
`resend_invoice`	POST `/customers/{customer_id}/invoices/{invoice_no}/resend`	영수증 재발송 (미리보기 → 확정) `invoice_no*`
`change_plan`	POST `/customers/{customer_id}/subscription/change-plan`	요금제 변경 (미리보기 → 확정) `plan*`
`cancel_subscription`	POST `/customers/{customer_id}/subscription/cancel`	구독 해지 예약 (미리보기 → 확정) `reason`

curl -X POST https://www.mydomain.com/api/subscription/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"email":"sub.kim@example.com","account_no":"AC-5001"}'

#교육·학원 기본 커넥터

과정 안내, 수강생 번호로 본인확인 → 수강 내역·상세(환불 예상액) → 환불 신청, 수강 연기. 기본 주소는 https://www.mydomain.com/api/academy 입니다.

작업	요청	설명 · 주요 파라미터
`verify_customer`	POST `/verify`	본인확인 `student_no, name`
`search_courses`	GET `/courses`	과정 안내 `q`
`list_enrollments`	GET `/customers/{customer_id}/enrollments`	수강 내역
`get_enrollment`	GET `/customers/{customer_id}/enrollments/{enrollment_no}`	수강 상세·환불 예상액 `enrollment_no*`
`request_refund`	POST `/customers/{customer_id}/enrollments/{enrollment_no}/refund`	환불 신청 (미리보기 → 확정) `enrollment_no*, reason`
`postpone_enrollment`	POST `/customers/{customer_id}/enrollments/{enrollment_no}/postpone`	수강 연기 (미리보기 → 확정) `enrollment_no, weeks`

curl -X POST https://www.mydomain.com/api/academy/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"student_no":"ST-8001","name":"한수강"}'

#호텔·펜션 숙박 기본 커넥터

빈 객실·요금과 시설 안내, 예약번호로 본인확인 → 예약 목록·상세 → 부가 서비스 요청, 예약 취소. 기본 주소는 https://www.mydomain.com/api/stay 입니다.

작업	요청	설명 · 주요 파라미터
`verify_customer`	POST `/verify`	본인확인 `reservation_no, name`
`find_rooms`	GET `/rooms`	빈 객실·요금 `check_in*, nights, guests`
`get_info`	GET `/info`	시설 안내
`list_reservations`	GET `/customers/{customer_id}/reservations`	내 예약 목록
`get_reservation`	GET `/customers/{customer_id}/reservations/{reservation_no}`	예약 상세 `reservation_no*`
`add_request`	POST `/customers/{customer_id}/reservations/{reservation_no}/requests`	부가 서비스 요청 (미리보기 → 확정) `reservation_no, type`
`cancel_reservation`	POST `/customers/{customer_id}/reservations/{reservation_no}/cancel`	예약 취소 (미리보기 → 확정) `reservation_no*`

curl -X POST https://www.mydomain.com/api/stay/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"reservation_no":"HT-9001","name":"최숙박"}'

#헬스장·필라테스 기본 커넥터

수업 시간표·잔여석, 회원번호로 본인확인 → 이용권·남은 횟수 → 수업 예약·취소, 회원권 정지. 기본 주소는 https://www.mydomain.com/api/fitness 입니다.

작업	요청	설명 · 주요 파라미터
`verify_customer`	POST `/verify`	본인확인 `member_no, phone_last4`
`list_classes`	GET `/classes`	수업 시간표 `date, type`
`get_membership`	GET `/customers/{customer_id}/membership`	이용권 조회
`list_bookings`	GET `/customers/{customer_id}/bookings`	내 수업 예약
`book_class`	POST `/customers/{customer_id}/bookings`	수업 예약 (미리보기 → 확정) `class_id*`
`cancel_booking`	POST `/customers/{customer_id}/bookings/{booking_id}/cancel`	수업 예약 취소 (미리보기 → 확정) `booking_id*`
`hold_membership`	POST `/customers/{customer_id}/membership/hold`	회원권 정지 (미리보기 → 확정) `start_date, days`

curl -X POST https://www.mydomain.com/api/fitness/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"member_no":"FT-1001","phone_last4":"1234"}'