🔌 API 제작 가이드

분야별 Tool API 명세서

아래 명세는 AGENIX 기본 프리셋 기준으로 제공되는 엔드포인트 구조입니다. 실제 도입 시에는 고객사 시스템에 맞게 API URL, 파라미터, 응답 구조를 조정하여 사용하세요. 등록된 URL로의 호출은 AGENIX가 자동으로 처리하며, 비즈니스 로직은 고객사 서버에서 직접 구현합니다.

📋

엔드포인트 명세

10개 분야 60여 개 API

🔑

X-User-Token

로그인 연동 지원

💻

코드 예시

Python / Node.js / Java

📋 공통 규칙

🔐 인증 헤더

X-Tool-API-Key: your-secret-key

모든 요청에 포함. 관리자 패널에서 설정한 값과 동일해야 합니다.

🔑 사용자 토큰

X-User-Token: user@example.com

로그인 연동 시 자동 전달. API에서 이 값으로 사용자를 식별합니다.

📦 응답 형식

Content-Type: application/json
{ "found": true, ... }
{ "success": true, ... }
{ "error": true, "message": "..." }

⚠️ X-User-Token 처리 방법

Python (FastAPI)

from fastapi import Header

@app.post("/tools/list_my_tickets")
async def list_my_tickets(
  user_token: str = Header(None, alias="X-User-Token")
):
  email = user_token  # 이 값으로 DB 조회

Node.js (Express)

app.post('/tools/list_my_tickets',
  (req, res) => {
    const userToken =
      req.headers['x-user-token'];
    // userToken으로 DB 조회
  }
);

Spring Boot (Java)

@PostMapping("/tools/list_my_tickets")
public Result listTickets(
  @RequestHeader("X-User-Token")
  String userToken
) {
  // userToken으로 DB 조회
}

⚠️ 사용자 식별 필드는 '선택(optional)'으로 구현하세요

AGENIX는 로그인 사용자를 X-User-Token 헤더로 식별하고, 요청 body는 비워서(예: {}) 호출할 수 있습니다. 따라서 customer_email·employee_email·account_number 같은 본인 식별 필드를 요청 body에서필수(required)로 두면, 서버 프레임워크(FastAPI·Spring 등)가 검증 단계에서 요청을 거부(HTTP 422)하여 도구가 동작하지 않습니다.

✅ 올바른 구현

  • ① body의 식별 필드는 optional로 선언합니다.
  • ② X-User-Token 헤더가 있으면 그 값을 우선 사용합니다.
  • ③ 헤더가 없고 body에 값이 있으면 그 값으로 조회합니다(다른 사용자 조회가 필요한 관리형 도구 등).

💡 AGENIX 호출 형태 → 헤더 X-User-Token: user@example.com + body {}(빈 값).

📥 요청 본문(body)은 어떻게 구성되나

API가 받는 요청 body 필드는 두 곳에서 옵니다 — 그래서 body에 들어오는 값 = 관리자 패널에서 정의한 파라미터입니다:

  • ① 파라미터 정의(관리자 패널 Tool 등록 화면) — 챗봇이 대화에서 수집하는 값. 예: 환불 사유, 예약 날짜·인원.
  • ② 자동추출 식별자 — 트리거 정규식으로 메시지에서 뽑는 단일 식별자. 예: 주문번호·티켓번호·운송장번호.
  • ③ 본인 식별값(이메일·전화·사번·계좌)은 body가 아니라 위의 X-User-Token 헤더로 전달됩니다.

💡 각 Tool을 등록할 때 관리자 패널의 "내 API가 받는 요청(명세)"에서 그 도구가 실제로 받는 헤더·본문 필드와 복사용 예시 요청을 바로 확인할 수 있습니다.

🧩 프리셋 동작 방식

각 도구는 관리자 패널에서 분야별 기본 도구로 등록할 때 아래 3가지가 프리셋으로 자동 세팅됩니다. (등록 후 수정 가능)

🎯 트리거 패턴

고객 메시지에 등록된 키워드·정규식이 포함되면 해당 도구가 자동 호출됩니다. 주문번호·송장번호 등 회사 양식은 우리 형식에 맞게 수정하세요.각 도구 카드의 "트리거 패턴" 참고

📝 파라미터 (멀티턴 수집)

도구에 정의된 파라미터가 대화에서 부족하면, 챗봇이 필요한 값을 되물어 자동 수집한 뒤 request body로 담아 API를 호출합니다.예: "환불해주세요" → 챗봇이 주문번호·사유를 물어본 뒤 request_refund 호출

📈 전환 도구 (쓰기)

주문·예약·환불·접수처럼 실제 처리(쓰기) 도구는 '전환 도구'로 표시됩니다. 사용자가 명시적으로 요청할 때만 실행되고(예: "예약할게요"), 방법·정책을 묻는 안내 질문에는 실행되지 않아 오작동을 막습니다.

💡 조회 도구(잔액·재고·상태 등)는 자유롭게 호출되고, 처리(쓰기) 도구만 명시적 요청 시 발동합니다. X-User-Token으로 "본인"이 식별되므로, 로그인 연동 시 "내 주문 어디쯤?" 같은 질문에 별도 번호 없이 바로 답합니다.

🛍️ 쇼핑몰

쇼핑몰 CS 자동화 — 주문 조회, 상품 검색, 환불 접수 등

Base URL 예시

https://your-shop.com/api/chatbot

🔑

이 분야의 X-User-Token

고객 이메일 또는 회원 ID — 예: customer@example.com

📡 API 엔드포인트 (8개)

📋 AGENIX에 등록하는 방법

1. 관리자 패널 → Tool API 관리
2. 분야별 기본 도구에서 해당 분야 선택 → 도구 등록 클릭
3. API URL을 실제 서버 주소로 변경
4. 인증 헤더에 X-Tool-API-Key 값 입력
5. 파라미터 정의에서 각 Tool의 파라미터 확인/수정

API 연동이 어렵거나 도움이 필요하신가요?

고객사 시스템에 맞는 API 구조 설계, 연동 방법 등 기술 문의는 이메일로 연락주세요.

✉️ support@agenix.kr