API 연동
REST 레퍼런스
엔드포인트별 요청·응답 규격입니다. 각 항목에서 API 테스트로 바로 실행할 수 있습니다.
Base URL은 https://<도메인>/api/v1이고 모든 요청에 X-API-Key 헤더가 필요합니다. 공통 응답 형식과 에러 코드는 인증과 공통 규격에 있습니다.
/ping키 확인POST/issues이슈 접수GET/issues이슈 목록 (변경분 조회)GET/issues/{id}이슈 상세PATCH/issues/{id}이슈 수정DELETE/issues/{id}이슈 삭제POST/issues/{id}/comments댓글 작성PATCH/issues/{id}/comments/{commentId}댓글 수정DELETE/issues/{id}/comments/{commentId}댓글 삭제POST/issues/{id}/comments/{commentId}/confirm답변 확정POST/issues/{id}/answer답변 작성 + 확정바로 실행해 보기
각 항목의 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();{
"success": true,
"item": {
"keyName": "쇼핑몰A",
"projectId": "01920000-0000-7000-8000-000000000001",
"projectName": "쇼핑몰A CS"
}
}| HTTP | code | 발생 조건 |
|---|---|---|
| 401 | UNAUTHORIZED | 키 누락·오류·폐기 |
이슈 접수#
새 문의를 접수합니다. 이슈는 항상 접수 상태로 시작하고, 키에 연결된 프로젝트로 들어갑니다.
주의
멱등하지 않습니다. 같은 요청을 두 번 보내면 이슈가 두 개 생기니, 응답을 확인하기 전에는 재시도하지 마세요.
세부 규격 (파라미터 · 요청/응답 예시 · 에러)
요청 본문 (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();{
"success": true,
"item": {
"id": "01920000-0000-7000-8000-00000000000a",
"issueNum": 42
}
}| HTTP | code | 발생 조건 |
|---|---|---|
| 401 | UNAUTHORIZED | 키 누락·오류·폐기 |
| 422 | VALIDATION_FAILED | JSON 오류, 필수값 누락, 허용되지 않는 값, 키와 다른 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();{
"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
}| HTTP | code | 발생 조건 |
|---|---|---|
| 401 | UNAUTHORIZED | 키 누락·오류·폐기 |
| 422 | VALIDATION_FAILED | 쿼리 값 형식 오류 |
이슈 상세#
이슈 하나의 본문, 요청자 정보, 확정 답변을 돌려줍니다.
주의
확정 답변이 있으면 이 호출 시점에 전달 완료로 처리됩니다.
세부 규격 (파라미터 · 요청/응답 예시 · 에러)
경로 파라미터
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();{
"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"
}
}
}| HTTP | code | 발생 조건 |
|---|---|---|
| 401 | UNAUTHORIZED | 키 누락·오류·폐기 |
| 404 | NOT_FOUND | 없는 이슈이거나 다른 키로 접수된 이슈 |
이슈 수정#
보낸 필드만 고칩니다. 최소 한 개는 보내야 합니다. 프로젝트와 담당자는 바꿀 수 없습니다.
참고
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();{
"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"
}
}| HTTP | code | 발생 조건 |
|---|---|---|
| 401 | UNAUTHORIZED | 키 누락·오류·폐기 |
| 404 | NOT_FOUND | 없는 이슈이거나 다른 키로 접수된 이슈 |
| 422 | VALIDATION_FAILED | JSON 오류, 허용되지 않는 값, 수정 필드 0개 |
이슈 삭제#
이슈를 삭제합니다. 조회에서 즉시 사라지고 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();{
"success": true
}| HTTP | code | 발생 조건 |
|---|---|---|
| 401 | UNAUTHORIZED | 키 누락·오류·폐기 |
| 404 | NOT_FOUND | 없는 이슈이거나 다른 키로 접수된 이슈 |
댓글 작성#
이슈에 댓글을 남깁니다. 상태는 바뀌지 않고 아직 공식 답변도 아닙니다. 고객에게 되묻는 중간 대화 등에 쓰고, 나중에 하나를 확정합니다.
세부 규격 (파라미터 · 요청/응답 예시 · 에러)
경로 파라미터
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();{
"success": true,
"item": {
"id": "01920000-0000-7000-8000-00000000000b"
}
}| HTTP | code | 발생 조건 |
|---|---|---|
| 401 | UNAUTHORIZED | 키 누락·오류·폐기 |
| 404 | NOT_FOUND | 없는 이슈이거나 다른 키로 접수된 이슈 |
| 422 | VALIDATION_FAILED | body·authorName 누락, 2,000자 초과 |
댓글 수정#
이 키가 쓴 댓글의 내용을 고칩니다. 확정된 답변도 고칠 수 있으며, 그 경우 전달 상태가 초기화되어 다음 조회 때 바뀐 내용이 다시 실립니다.
세부 규격 (파라미터 · 요청/응답 예시 · 에러)
경로 파라미터
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();{
"success": true
}| HTTP | code | 발생 조건 |
|---|---|---|
| 401 | UNAUTHORIZED | 키 누락·오류·폐기 |
| 404 | NOT_FOUND | 없는 댓글이거나 이 키가 쓴 댓글이 아님 |
| 422 | VALIDATION_FAILED | body 누락, 2,000자 초과 |
댓글 삭제#
이 키가 쓴 댓글을 삭제합니다. 확정된 답변을 삭제하면 이슈가 진행중으로 돌아갑니다.
세부 규격 (파라미터 · 요청/응답 예시 · 에러)
경로 파라미터
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();{
"success": true
}| HTTP | code | 발생 조건 |
|---|---|---|
| 401 | UNAUTHORIZED | 키 누락·오류·폐기 |
| 404 | NOT_FOUND | 없는 댓글이거나 이 키가 쓴 댓글이 아님 |
| 422 | VALIDATION_FAILED | 답글이 달린 댓글 |
답변 확정#
댓글을 공식 답변으로 확정합니다. 이슈가 완료로 바뀌고, 이 경로로 확정한 답변은 즉시 전달 완료로 처리됩니다. 요청 본문은 없습니다.
참고
확정 취소 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();{
"success": true
}| HTTP | code | 발생 조건 |
|---|---|---|
| 401 | UNAUTHORIZED | 키 누락·오류·폐기 |
| 404 | NOT_FOUND | 다른 키의 이슈이거나 그 이슈에 해당 댓글이 없음 |
| 422 | VALIDATION_FAILED | 이미 확정된 답변이 있음 (이슈당 1개) |
답변 작성 + 확정#
댓글 작성과 확정을 한 번에 합니다. 되묻는 대화 없이 바로 최종 답변을 보낼 때 이 호출 하나면 됩니다.
세부 규격 (파라미터 · 요청/응답 예시 · 에러)
경로 파라미터
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();{
"success": true,
"item": {
"id": "01920000-0000-7000-8000-00000000000b"
}
}| HTTP | code | 발생 조건 |
|---|---|---|
| 401 | UNAUTHORIZED | 키 누락·오류·폐기 |
| 404 | NOT_FOUND | 없는 이슈이거나 다른 키로 접수된 이슈 |
| 422 | VALIDATION_FAILED | body·authorName 누락, 2,000자 초과, 이미 확정된 답변이 있음 |