Docs

Docs

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

API 연동

REST 레퍼런스

엔드포인트별 요청·응답 규격입니다. 각 항목에서 API 테스트로 바로 실행할 수 있습니다.

Base URL은 https://<도메인>/api/v1이고 모든 요청에 X-API-Key 헤더가 필요합니다. 공통 응답 형식과 에러 코드는 인증과 공통 규격에 있습니다.

바로 실행해 보기

각 항목의 API 테스트에서 실행을 누르면 테스트 콘솔이 그 요청으로 채워진 채 열립니다. 프로젝트와 키만 고르면 실제 요청을 보낼 수 있습니다.

키 확인#

API 키가 유효한지 확인합니다. 아무것도 만들지 않으므로 연동 첫 단계에서 부담 없이 호출할 수 있습니다.

세부 규격 (파라미터 · 요청/응답 예시 · 에러)

응답 200

item.keyNamestring
키 발급 시 등록한 이름
item.projectIdstring | null
키에 연결된 프로젝트 ID
item.projectNamestring | null
프로젝트 이름
요청 예시
const res = await fetch("https://<도메인>/api/v1/ping", {
  method: "GET",
  headers: { "X-API-Key": process.env.CS_API_KEY! },
});
const data = await res.json();
응답 예시 200
{
  "success": true,
  "item": {
    "keyName": "쇼핑몰A",
    "projectId": "01920000-0000-7000-8000-000000000001",
    "projectName": "쇼핑몰A CS"
  }
}
HTTPcode발생 조건
401UNAUTHORIZED키 누락·오류·폐기

이슈 접수#

POST/api/v1/issues API 테스트에서 실행

새 문의를 접수합니다. 이슈는 항상 접수 상태로 시작하고, 키에 연결된 프로젝트로 들어갑니다.

주의

멱등하지 않습니다. 같은 요청을 두 번 보내면 이슈가 두 개 생기니, 응답을 확인하기 전에는 재시도하지 마세요.

세부 규격 (파라미터 · 요청/응답 예시 · 에러)

요청 본문 (JSON)

titlestring필수
1~200자
bodystring | null
문의 내용. 본문 서식 규칙을 따릅니다
categoryenum
문의(기본) · 오류
priorityenum
낮음 · 보통(기본) · 높음 · 긴급
channelenum
자체(기본) · 채팅 · 게시판 · 메일 · 유선 · 대면 · 외부 서비스
requesterNamestring | null
고객 이름
requesterEmailstring | null
고객 이메일. 이메일 형식
projectIdstring
생략 권장. 보내면 키의 프로젝트와 같아야 합니다

응답 201

item.idstring
이슈 ID. 이후 모든 호출에 이 값을 씁니다
item.issueNuminteger
프로젝트 안의 표시 번호. 식별자로 쓰지 마세요
요청 예시
const res = await fetch("https://<도메인>/api/v1/issues", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.CS_API_KEY!,
    "Content-Type": "application/json; charset=utf-8",
  },
  body: JSON.stringify({
    "title": "결제가 안 됩니다",
    "body": "카드 결제 시 오류가 발생합니다.",
    "category": "오류",
    "priority": "높음",
    "channel": "채팅",
    "requesterName": "홍길동",
    "requesterEmail": "hong@example.com"
  }),
});
const data = await res.json();
응답 예시 201
{
  "success": true,
  "item": {
    "id": "01920000-0000-7000-8000-00000000000a",
    "issueNum": 42
  }
}
HTTPcode발생 조건
401UNAUTHORIZED키 누락·오류·폐기
422VALIDATION_FAILEDJSON 오류, 필수값 누락, 허용되지 않는 값, 키와 다른 projectId

이슈 목록 (변경분 조회)#

이 키로 접수한 이슈를 수정 시각 오름차순으로 돌려줍니다. updatedFrom 을 커서로 써서 지난번 이후 바뀐 것만 가져갑니다.

주의

응답에 실린 확정 답변은 이 호출 시점에 전달 완료로 처리되어, 이후 담당자가 확정을 취소할 수 없게 됩니다. 테스트 조회도 마찬가지입니다.

세부 규격 (파라미터 · 요청/응답 예시 · 에러)

쿼리 파라미터

updatedFromstring
ISO 8601 시각(타임존 포함). 이 시각 이상(>=)으로 바뀐 이슈만
statusenum
접수 · 진행중 · 보류 · 완료
pageinteger
1 이상. 기본 1
perPageinteger
1~100. 기본 20

응답 200

items[]object[]
id, issueNum, title, category, status, priority, channel, completedAt, createdAt, updatedAt
items[].confirmedCommentobject | null
확정 답변 { id, body, authorName, confirmedAt }. 없으면 null
totalCount · page · perPage · totalPagesinteger
페이지 정보
요청 예시
const res = await fetch("https://<도메인>/api/v1/issues?updatedFrom=2026-09-01T00:00:00.000Z&perPage=50", {
  method: "GET",
  headers: { "X-API-Key": process.env.CS_API_KEY! },
});
const data = await res.json();
응답 예시 200
{
  "success": true,
  "items": [
    {
      "id": "01920000-0000-7000-8000-00000000000a",
      "issueNum": 42,
      "title": "결제가 안 됩니다",
      "category": "오류",
      "status": "완료",
      "priority": "높음",
      "channel": "채팅",
      "completedAt": "2026-09-10T02:00:00.000Z",
      "createdAt": "2026-09-09T01:00:00.000Z",
      "updatedAt": "2026-09-10T02:00:00.000Z",
      "confirmedComment": {
        "id": "01920000-0000-7000-8000-00000000000b",
        "body": "환불 처리했습니다.",
        "authorName": "김상담",
        "confirmedAt": "2026-09-10T02:00:00.000Z"
      }
    }
  ],
  "totalCount": 1,
  "page": 1,
  "perPage": 50,
  "totalPages": 1
}
HTTPcode발생 조건
401UNAUTHORIZED키 누락·오류·폐기
422VALIDATION_FAILED쿼리 값 형식 오류

이슈 상세#

GET/api/v1/issues/{id} API 테스트에서 실행

이슈 하나의 본문, 요청자 정보, 확정 답변을 돌려줍니다.

주의

확정 답변이 있으면 이 호출 시점에 전달 완료로 처리됩니다.

세부 규격 (파라미터 · 요청/응답 예시 · 에러)

경로 파라미터

idstring필수
이슈 ID (UUID)

응답 200

itemobject
목록 필드 + projectId, projectName, body, authorName, requesterName, requesterEmail, emailOptIn
item.confirmedCommentobject | null
{ id, body, authorName, confirmedAt, updatedAt, syncedAt }
요청 예시
const res = await fetch("https://<도메인>/api/v1/issues/01920000-0000-7000-8000-00000000000a", {
  method: "GET",
  headers: { "X-API-Key": process.env.CS_API_KEY! },
});
const data = await res.json();
응답 예시 200
{
  "success": true,
  "item": {
    "id": "01920000-0000-7000-8000-00000000000a",
    "issueNum": 42,
    "projectId": "01920000-0000-7000-8000-000000000001",
    "projectName": "쇼핑몰A CS",
    "title": "결제가 안 됩니다",
    "body": "카드 결제 시 오류가 발생합니다.",
    "category": "오류",
    "status": "완료",
    "priority": "높음",
    "channel": "채팅",
    "authorName": null,
    "requesterName": "홍길동",
    "requesterEmail": "hong@example.com",
    "emailOptIn": false,
    "completedAt": "2026-09-10T02:00:00.000Z",
    "createdAt": "2026-09-09T01:00:00.000Z",
    "updatedAt": "2026-09-10T02:00:00.000Z",
    "confirmedComment": {
      "id": "01920000-0000-7000-8000-00000000000b",
      "body": "환불 처리했습니다.",
      "authorName": "김상담",
      "confirmedAt": "2026-09-10T02:00:00.000Z",
      "updatedAt": "2026-09-10T02:00:00.000Z",
      "syncedAt": "2026-09-11T05:00:00.000Z"
    }
  }
}
HTTPcode발생 조건
401UNAUTHORIZED키 누락·오류·폐기
404NOT_FOUND없는 이슈이거나 다른 키로 접수된 이슈

이슈 수정#

PATCH/api/v1/issues/{id} API 테스트에서 실행

보낸 필드만 고칩니다. 최소 한 개는 보내야 합니다. 프로젝트와 담당자는 바꿀 수 없습니다.

참고

status 로 완료는 지정할 수 없습니다. 완료는 답변 확정(confirm 또는 answer)으로만 됩니다. 완료가 아닌 값으로 바꾸면 completedAt 이 비워집니다.

세부 규격 (파라미터 · 요청/응답 예시 · 에러)

경로 파라미터

idstring필수
이슈 ID (UUID)

요청 본문 (JSON)

titlestring
1~200자
bodystring | null
본문
categoryenum
문의 · 오류
statusenum
접수 · 진행중 · 보류
priorityenum
낮음 · 보통 · 높음 · 긴급

응답 200

itemobject
수정된 이슈. 상세 조회와 같은 구조에서 confirmedComment 만 빠집니다
요청 예시
const res = await fetch("https://<도메인>/api/v1/issues/01920000-0000-7000-8000-00000000000a", {
  method: "PATCH",
  headers: {
    "X-API-Key": process.env.CS_API_KEY!,
    "Content-Type": "application/json; charset=utf-8",
  },
  body: JSON.stringify({
    "status": "진행중",
    "priority": "긴급"
  }),
});
const data = await res.json();
응답 예시 200
{
  "success": true,
  "item": {
    "id": "01920000-0000-7000-8000-00000000000a",
    "issueNum": 42,
    "projectId": "01920000-0000-7000-8000-000000000001",
    "projectName": "쇼핑몰A CS",
    "title": "결제가 안 됩니다",
    "body": "카드 결제 시 오류가 발생합니다.",
    "category": "오류",
    "status": "진행중",
    "priority": "긴급",
    "channel": "채팅",
    "authorName": null,
    "requesterName": "홍길동",
    "requesterEmail": "hong@example.com",
    "emailOptIn": false,
    "completedAt": null,
    "createdAt": "2026-09-09T01:00:00.000Z",
    "updatedAt": "2026-09-10T02:00:00.000Z"
  }
}
HTTPcode발생 조건
401UNAUTHORIZED키 누락·오류·폐기
404NOT_FOUND없는 이슈이거나 다른 키로 접수된 이슈
422VALIDATION_FAILEDJSON 오류, 허용되지 않는 값, 수정 필드 0개

이슈 삭제#

DELETE/api/v1/issues/{id} API 테스트에서 실행

이슈를 삭제합니다. 조회에서 즉시 사라지고 API로 되살릴 수 없습니다.

세부 규격 (파라미터 · 요청/응답 예시 · 에러)

경로 파라미터

idstring필수
이슈 ID (UUID)
요청 예시
const res = await fetch("https://<도메인>/api/v1/issues/01920000-0000-7000-8000-00000000000a", {
  method: "DELETE",
  headers: { "X-API-Key": process.env.CS_API_KEY! },
});
const data = await res.json();
응답 예시 200
{
  "success": true
}
HTTPcode발생 조건
401UNAUTHORIZED키 누락·오류·폐기
404NOT_FOUND없는 이슈이거나 다른 키로 접수된 이슈

댓글 작성#

POST/api/v1/issues/{id}/comments API 테스트에서 실행

이슈에 댓글을 남깁니다. 상태는 바뀌지 않고 아직 공식 답변도 아닙니다. 고객에게 되묻는 중간 대화 등에 쓰고, 나중에 하나를 확정합니다.

세부 규격 (파라미터 · 요청/응답 예시 · 에러)

경로 파라미터

idstring필수
이슈 ID (UUID)

요청 본문 (JSON)

bodystring필수
1~2,000자(보이는 글자 기준). 본문 서식 규칙을 따릅니다
authorNamestring필수
화면에 표시할 작성자 이름. 계정과 연결되지 않는 자유 텍스트

응답 201

item.idstring
댓글 ID. 확정·수정·삭제에 씁니다
요청 예시
const res = await fetch("https://<도메인>/api/v1/issues/01920000-0000-7000-8000-00000000000a/comments", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.CS_API_KEY!,
    "Content-Type": "application/json; charset=utf-8",
  },
  body: JSON.stringify({
    "body": "주문 번호를 알려주시겠어요?",
    "authorName": "김상담"
  }),
});
const data = await res.json();
응답 예시 201
{
  "success": true,
  "item": {
    "id": "01920000-0000-7000-8000-00000000000b"
  }
}
HTTPcode발생 조건
401UNAUTHORIZED키 누락·오류·폐기
404NOT_FOUND없는 이슈이거나 다른 키로 접수된 이슈
422VALIDATION_FAILEDbody·authorName 누락, 2,000자 초과

댓글 수정#

PATCH/api/v1/issues/{id}/comments/{commentId} API 테스트에서 실행

이 키가 쓴 댓글의 내용을 고칩니다. 확정된 답변도 고칠 수 있으며, 그 경우 전달 상태가 초기화되어 다음 조회 때 바뀐 내용이 다시 실립니다.

세부 규격 (파라미터 · 요청/응답 예시 · 에러)

경로 파라미터

idstring필수
이슈 ID (UUID)
commentIdstring필수
댓글 ID

요청 본문 (JSON)

bodystring필수
1~2,000자(보이는 글자 기준). 본문 서식 규칙을 따릅니다
요청 예시
const res = await fetch("https://<도메인>/api/v1/issues/01920000-0000-7000-8000-00000000000a/comments/01920000-0000-7000-8000-00000000000b", {
  method: "PATCH",
  headers: {
    "X-API-Key": process.env.CS_API_KEY!,
    "Content-Type": "application/json; charset=utf-8",
  },
  body: JSON.stringify({
    "body": "확인 결과 내일 환불 처리 예정입니다."
  }),
});
const data = await res.json();
응답 예시 200
{
  "success": true
}
HTTPcode발생 조건
401UNAUTHORIZED키 누락·오류·폐기
404NOT_FOUND없는 댓글이거나 이 키가 쓴 댓글이 아님
422VALIDATION_FAILEDbody 누락, 2,000자 초과

댓글 삭제#

DELETE/api/v1/issues/{id}/comments/{commentId} API 테스트에서 실행

이 키가 쓴 댓글을 삭제합니다. 확정된 답변을 삭제하면 이슈가 진행중으로 돌아갑니다.

세부 규격 (파라미터 · 요청/응답 예시 · 에러)

경로 파라미터

idstring필수
이슈 ID (UUID)
commentIdstring필수
댓글 ID
요청 예시
const res = await fetch("https://<도메인>/api/v1/issues/01920000-0000-7000-8000-00000000000a/comments/01920000-0000-7000-8000-00000000000b", {
  method: "DELETE",
  headers: { "X-API-Key": process.env.CS_API_KEY! },
});
const data = await res.json();
응답 예시 200
{
  "success": true
}
HTTPcode발생 조건
401UNAUTHORIZED키 누락·오류·폐기
404NOT_FOUND없는 댓글이거나 이 키가 쓴 댓글이 아님
422VALIDATION_FAILED답글이 달린 댓글

답변 확정#

POST/api/v1/issues/{id}/comments/{commentId}/confirm API 테스트에서 실행

댓글을 공식 답변으로 확정합니다. 이슈가 완료로 바뀌고, 이 경로로 확정한 답변은 즉시 전달 완료로 처리됩니다. 요청 본문은 없습니다.

참고

확정 취소 API는 없습니다. 잘못 확정했다면 그 댓글을 수정하거나 삭제하세요.

세부 규격 (파라미터 · 요청/응답 예시 · 에러)

경로 파라미터

idstring필수
이슈 ID (UUID)
commentIdstring필수
댓글 ID
요청 예시
const res = await fetch("https://<도메인>/api/v1/issues/01920000-0000-7000-8000-00000000000a/comments/01920000-0000-7000-8000-00000000000b/confirm", {
  method: "POST",
  headers: { "X-API-Key": process.env.CS_API_KEY! },
});
const data = await res.json();
응답 예시 200
{
  "success": true
}
HTTPcode발생 조건
401UNAUTHORIZED키 누락·오류·폐기
404NOT_FOUND다른 키의 이슈이거나 그 이슈에 해당 댓글이 없음
422VALIDATION_FAILED이미 확정된 답변이 있음 (이슈당 1개)

답변 작성 + 확정#

POST/api/v1/issues/{id}/answer API 테스트에서 실행

댓글 작성과 확정을 한 번에 합니다. 되묻는 대화 없이 바로 최종 답변을 보낼 때 이 호출 하나면 됩니다.

세부 규격 (파라미터 · 요청/응답 예시 · 에러)

경로 파라미터

idstring필수
이슈 ID (UUID)

요청 본문 (JSON)

bodystring필수
1~2,000자(보이는 글자 기준). 본문 서식 규칙을 따릅니다
authorNamestring필수
화면에 표시할 작성자 이름. 계정과 연결되지 않는 자유 텍스트

응답 201

item.idstring
생성과 동시에 확정된 댓글 ID
요청 예시
const res = await fetch("https://<도메인>/api/v1/issues/01920000-0000-7000-8000-00000000000a/answer", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.CS_API_KEY!,
    "Content-Type": "application/json; charset=utf-8",
  },
  body: JSON.stringify({
    "body": "환불 처리했습니다.",
    "authorName": "김상담"
  }),
});
const data = await res.json();
응답 예시 201
{
  "success": true,
  "item": {
    "id": "01920000-0000-7000-8000-00000000000b"
  }
}
HTTPcode발생 조건
401UNAUTHORIZED키 누락·오류·폐기
404NOT_FOUND없는 이슈이거나 다른 키로 접수된 이슈
422VALIDATION_FAILEDbody·authorName 누락, 2,000자 초과, 이미 확정된 답변이 있음