Docs

Docs

화면 사용법과 연동 규격을 정리한 매뉴얼입니다.

API 연동

포털 연동

고객이 직접 문의를 쓰는 팝업을 띄우고 접수 결과를 돌려받는 방법입니다.

동작 방식#

파트너는 화면을 만들 필요 없이, 우리가 제공하는 문의 작성 화면을 팝업으로 띄웁니다.

토큰 발급
파트너 서버 → POST /launch-tokens
팝업 열기
받은 URL을 새 창으로
고객 작성
우리 화면에서 제출
결과 수신
팝업이 부모 창에 접수 내용 전달

토큰 발급#

POST/api/v1/launch-tokens

고객 정보를 넘기면 그 고객 전용 접속 주소가 나옵니다. 프로젝트는 키에 묶인 프로젝트로 고정됩니다. 반드시 파트너 서버에서 호출하세요. 브라우저에서 부르면 API 키가 노출됩니다.

요청 본문 (JSON)

context.customerIdstring필수
고객 식별자. 같은 고객에게는 항상 같은 값(로그인 ID 등). 접수 내역 조회의 기준
context.namestring필수
고객 이름. 작성 폼 초기값
context.emailstring필수
고객 이메일. 작성 폼 초기값
context.phonestring
연락처. 작성 폼 초기값. 이 밖의 필드도 자유롭게 추가 가능
요청 예시
{
  "context": {
    "customerId": "user_1234",
    "name": "홍길동",
    "email": "hong@example.com",
    "phone": "010-1234-5678"
  }
}

응답 201

item.urlstring
팝업으로 열 주소
item.expiresAtstring
토큰 만료 시각 (발급 후 2분)
item.tokenstring
원본 토큰. url 에 이미 들어 있어 따로 쓸 일은 없음
응답 예시 201
{
  "success": true,
  "item": {
    "token": "a1b2c3d4e5f6...",
    "url": "https://<도메인>/portal/exchange?token=a1b2c3d4e5f6...",
    "expiresAt": "2026-09-28T00:02:00.000Z"
  }
}
HTTPcode발생 조건
401UNAUTHORIZED키 누락·오류·폐기
403FORBIDDEN프로젝트에 연결되지 않은 키
422VALIDATION_FAILEDJSON 오류, customerId·name·email 누락 또는 이메일 형식 오류

토큰과 세션 수명#

구분수명설명
접속 토큰2분창을 여는 데 한 번 쓰면 사라짐. 버튼을 누른 순간 발급해 바로 쓸 것
작성 세션30분고객이 입력할 때마다 다시 30분으로 늘어남
세션 최대2시간진입 시점부터. 입력 중이어도 이 이후엔 만료

고객 화면에 남은 시간이 표시되고, 작성 중인 내용은 브라우저에 자동 저장돼 다시 들어와도 이어 쓸 수 있습니다.

구현 예시#

복붙으로 5분 안에 끝내려면

아래는 전체 규격까지 담은 상세판입니다. 코드만 빠르게 복붙하고 싶으면 포털 빠른 시작을 보세요.

API 키는 어디에 저장하나

CS_API_KEY는 파트너 서버의 환경변수에만 둡니다. 로컬 개발 중이면 프로젝트 최상위 폴더의 .env(Next.js면 .env.local)에 추가하고, 이 파일은 절대 git에 커밋하지 않습니다(.gitignore에 .env* 포함 여부 확인). 실제 운영 서버에 올릴 때는 파일에 적는 게 아니라 배포 방식에 맞는 환경변수/시크릿 설정 화면에 등록합니다.

배포 방식넣는 곳
Vercel프로젝트 Settings → Environment Variables
Docker(직접 서버 운영)docker-compose.yml의 environment: 항목, 또는 서버의 .env 파일을 컨테이너가 읽게 마운트
GitHub Actions로 CI/CD 배포리포지토리 Settings → Secrets and variables → Actions에 등록 후, 배포 워크플로우에서 컨테이너로 주입
그 외 일반 호스팅(PM2 등)서버에 직접 .env 파일 생성, 또는 PM2 ecosystem 설정의 env 항목
서버 프록시 + 브라우저 코드 보기

파트너 서버 (API 키를 숨기는 프록시)

// app/api/cs/launch/route.ts (파트너 서버)
const CS_BASE_URL = process.env.CS_BASE_URL!; // https://<도메인>/api/v1
const CS_API_KEY = process.env.CS_API_KEY!;   // sk_live_... (서버 전용)

export async function POST(request: Request) {
  const user = await getCurrentUser(request); // 파트너의 로그인 사용자
  if (!user) return Response.json({ message: "로그인이 필요합니다" }, { status: 401 });

  const res = await fetch(`${CS_BASE_URL}/launch-tokens`, {
    method: "POST",
    headers: {
      "X-API-Key": CS_API_KEY,
      "Content-Type": "application/json; charset=utf-8",
    },
    body: JSON.stringify({
      context: { customerId: user.id, name: user.name, email: user.email },
    }),
    cache: "no-store",
  });
  const result = await res.json();
  if (!result.success) return Response.json({ message: result.error.message }, { status: 502 });

  return Response.json({ url: result.item.url });
}

파트너 브라우저

두 파일로 나뉜다. 훅(useCsInquiry)이 팝업 열기·결과 수신·창 닫힘 감지·팝업 차단 감지를 전부 처리하므로 이건 그대로 복붙해서 쓴다(로직이라 서비스마다 달라질 이유가 없음). 버튼 쪽은 실제 디자인이 서비스마다 다르므로 동작 방식만 보여주는 최소 예시다 -open/isOpening/isBlocked 세 가지를 쓰는 버튼 컴포넌트에 맞게 연결하면 된다.

hooks/use-cs-inquiry.ts
"use client";

import { useCallback, useEffect, useRef, useState } from "react";

const CS_ORIGIN = "https://<도메인>";                  // 연동 대상 origin으로 교체
const POPUP_NAME = "cs-inquiry-myservice";    // 쓰는 서비스 이름으로 교체(고정값)
const SUBMITTED_TYPE = "cs-portal:submitted";
const LAUNCH_ENDPOINT = "/api/cs/launch";

export type CsSubmittedIssue = {
    id: string;
    issueNum: number;
    title: string;
    body: string;
    category: string;
    priority: string;
    status: string;
    channel: string;
    requesterName: string;
    requesterEmail: string;
    requesterPhone: string | null;
    replyChannel: "이메일" | "문자" | null;
    customerId: string | null;
    createdAt: string;
};

type UseCsInquiryOptions = {
    onSubmitted?: (issue: CsSubmittedIssue) => void;
    onClosed?: () => void;                  // 접수 없이 창이 닫힌 경우
    onError?: (message: string) => void;
};

export function useCsInquiry({ onSubmitted, onClosed, onError }: UseCsInquiryOptions = {}) {
    const [isOpening, setIsOpening] = useState(false);
    const [isBlocked, setIsBlocked] = useState(false); // 팝업 차단 감지 여부
    const submittedRef = useRef(false);
    const pollRef = useRef<ReturnType<typeof setInterval> | null>(null);

    const stopPolling = useCallback(() => {
        if (pollRef.current) {
            clearInterval(pollRef.current);
            pollRef.current = null;
        }
    }, []);

    // 결과 수신 - 마운트 시점에 등록해 타이밍 문제를 없앤다
    useEffect(() => {
        function handleMessage(event: MessageEvent) {
            if (event.origin !== CS_ORIGIN) return;
            if (event.data?.type !== SUBMITTED_TYPE) return;

            submittedRef.current = true;
            stopPolling();
            onSubmitted?.(event.data.issue);
        }

        window.addEventListener("message", handleMessage);
        return () => window.removeEventListener("message", handleMessage);
    }, [onSubmitted, stopPolling]);

    useEffect(() => stopPolling, [stopPolling]);

    const open = useCallback(async () => {
        submittedRef.current = false;
        setIsBlocked(false);

        // 클릭 직후 빈 창부터 연다
        const popup = window.open("about:blank", POPUP_NAME, "width=480,height=860");

        // 차단됐으면 여기서 중단한다 - 토큰을 요청하지 않는다(2분 만료라 낭비)
        if (!popup) {
            setIsBlocked(true);
            return;
        }

        setIsOpening(true);
        try {
            const res = await fetch(LAUNCH_ENDPOINT, { method: "POST" });
            const data = await res.json();
            if (!res.ok) throw new Error(data.message ?? "문의 창을 열지 못했습니다");

            popup.location.href = data.url;
        } catch (e) {
            popup.close();
            onError?.(e instanceof Error ? e.message : "문의 창을 열지 못했습니다");
            return;
        } finally {
            setIsOpening(false);
        }

        // 접수 없이 닫히는 경우 감지 (닫힘 이벤트가 없어 폴링)
        stopPolling();
        pollRef.current = setInterval(() => {
            if (popup.closed) {
                stopPolling();
                if (!submittedRef.current) onClosed?.();
            }
        }, 500);
    }, [onClosed, onError, stopPolling]);

    return { open, isOpening, isBlocked };
}
components/inquiry-button.tsx
"use client";

import { useCsInquiry } from "@/hooks/use-cs-inquiry";

export function InquiryButton() {
    const { open, isOpening, isBlocked } = useCsInquiry({
        onSubmitted: async (issue) => {
            // 접수 내용 전체가 넘어온다 - 그대로 DB에 저장하면 된다 (아래 경로는 내 서버에 직접 만드는 저장용 엔드포인트, 경로는 임의)
            await fetch("/api/cs/link", {
                method: "POST",
                headers: { "Content-Type": "application/json" },
                body: JSON.stringify(issue),
            });
        },
        onClosed: () => console.log("접수하지 않고 창을 닫음"),
        onError: (message) => alert(message),
    });

    return (
        <>
            <button type="button" onClick={open} disabled={isOpening}>
                {isOpening ? "여는 중..." : "문의하기"}
            </button>

            {isBlocked && (
                <div role="alert">
                    <p>팝업이 차단되어 문의 창을 열지 못했습니다.</p>
                    <p>주소창의 차단 아이콘을 눌러 허용한 뒤, 아래 버튼을 눌러주세요.</p>
                    <button type="button" onClick={open}>다시 시도</button>
                </div>
            )}
        </>
    );
}

팝업 차단을 피하는 순서

  • 클릭 직후 빈 창부터 열고, 토큰을 받은 뒤 주소를 바꿉니다. 토큰을 기다렸다가 창을 열면 브라우저가 차단합니다.
  • 창 이름은 고정값을 씁니다. _blank를 쓰면 창이 계속 쌓이고 부모 창 연결이 끊겨 결과를 못 받습니다.
  • 빈 창조차 차단되면 진행을 멈추고 고객에게 팝업 허용을 안내한 뒤 다시 시도 버튼을 보여줍니다.

접수 결과 메시지#

고객이 제출하면 팝업이 window.opener로 접수 내용 전체(이름·이메일·전화번호 포함)를 보냅니다. 이 값만으로 파트너 DB에 기록할 수 있습니다. 받을 때는 반드시 event.origin이 https://<도메인>인지 확인하세요.

event.data
{
  "type": "cs-portal:submitted",
  "issue": {
    "id": "01920000-0000-7000-8000-00000000000a",
    "issueNum": 42,
    "title": "결제가 자꾸 실패합니다",
    "body": "<p>카드를 바꿔도 같은 오류가 납니다.</p>",
    "category": "문의",
    "priority": "보통",
    "status": "접수",
    "channel": "외부 서비스",
    "requesterName": "홍길동",
    "requesterEmail": "hong@example.com",
    "requesterPhone": "010-1234-5678",
    "replyChannel": "이메일",
    "customerId": "user_1234",
    "createdAt": "2026-09-18T02:13:44.512Z"
  }
}

이 메시지를 누가 받을 수 있는지는 우리가 정합니다

프로젝트 설정의 외부 서비스에 파트너의 결과 수신 도메인을 등록해 두면, 그 도메인에서 연 창일 때만 브라우저가 이 메시지를 전달합니다. 등록하지 않으면 어느 도메인이 열었든 전달됩니다 - 새 파트너를 연동할 때 꼭 함께 등록하세요. 등록 여부와 무관하게 파트너 쪽 event.origin 확인은 그대로 필요합니다(서로 다른 계층을 방어).

  • category, priority, status, channel은 포털 접수에서 항상 같은 값입니다.
  • replyChannel은 고객이 고른 회신 수단(이메일/문자)입니다. 고객이 안 골랐으면 null입니다 - 필수 항목이 아닙니다.
  • 본문 속 첨부 이미지 주소는 7일간 유효합니다.

접수 이후#

담당자의 답변은 파트너로 전달되지 않습니다. 고객이 같은 팝업의 접수 내역 탭에서 직접 확인합니다(같은 customerId로 연 팝업에서 본인 문의만 보임). 답변까지 파트너 시스템에 반영해야 한다면 REST API 방식을 쓰세요.

직접 해보기

API 테스트 콘솔의 포털 영역에서 토큰 발급, 팝업 열기, 결과 메시지 수신까지 실제로 확인할 수 있습니다.

API 테스트 프로젝트 설정 - 외부 서비스