Docs

Docs

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

API 연동

인증과 공통 규격

인증 헤더, 응답 형식, 에러 코드, 허용 값, 본문 서식을 정리합니다.

기본 정보#

Base URLhttps://<도메인>/api/v1
요청 형식Content-Type: application/json; charset=utf-8
문자 인코딩UTF-8 (허용 값이 한글입니다)
시각 형식ISO 8601 UTC, 예: 2026-09-10T02:00:00.000Z

인증#

모든 요청에 X-API-Key 헤더를 붙입니다. Authorization 헤더나 쿼리 문자열로는 받지 않습니다.

HTTP
GET /api/v1/ping HTTP/1.1
Host: <도메인>
X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • 키 하나는 프로젝트 하나에 묶입니다. 접수한 이슈는 그 프로젝트로 들어갑니다.
  • 조회·수정·삭제는 그 키로 접수한 이슈만 가능합니다. 다른 키의 이슈는 있어도 없는 것처럼 404가 납니다.

주의

키는 서버에만 두세요. 브라우저나 앱 코드에 넣으면 누구나 꺼내 쓸 수 있습니다.

응답 형식#

성공 여부는 항상 success 필드로 판단합니다.

형태별 예시
// 단건
{ "success": true, "item": { } }

// 목록
{ "success": true, "items": [ ], "totalCount": 12, "page": 1, "perPage": 20, "totalPages": 1 }

// 본문 없는 성공 (삭제, 확정 등)
{ "success": true }

// 실패
{ "success": false, "error": { "code": "VALIDATION_FAILED", "message": "title: title은 필수입니다" } }

에러 코드#

HTTPcode언제재시도
401UNAUTHORIZED키 누락, 잘못된 키, 폐기된 키X, 키 확인
403FORBIDDEN프로젝트에 연결되지 않은 키로 포털 토큰 발급X
404NOT_FOUND없는 대상, 또는 다른 키가 접수한 이슈X
422VALIDATION_FAILEDJSON 오류, 필수값 누락, 허용되지 않는 값, 이미 확정된 답변X, 요청 수정
500INTERNAL서버 오류O, 간격을 늘려가며

분기는 code로 하세요. message는 사람이 읽는 한국어 문장이라 예고 없이 바뀔 수 있습니다.

허용 값#

영문 코드 없이 한글 값 그대로 주고받습니다.

필드값
category문의, 오류
priority낮음, 보통, 높음, 긴급
status접수, 진행중, 보류, 완료
channel자체, 채팅, 게시판, 메일, 유선, 대면, 외부 서비스

본문 서식#

이슈·댓글의 body는 아래 서식만 지원하는 일반 텍스트입니다. HTML 태그를 넣으면 글자 그대로 보입니다.

쓰는 법결과
**굵게**굵게
*기울임*기울임
[글자](https://...)링크
![설명](https://...)이미지
- 항목 (줄 맨 앞)목록
  • 링크·이미지 주소는 http://, https://만 허용됩니다.
  • API로는 파일을 올릴 수 없습니다. 이미지는 파트너 쪽에 올려둔 주소를 본문에 넣습니다.
  • 포털로 접수된 이슈를 조회하면 고객이 첨부한 이미지가 우리 쪽 서명 주소로 들어 있을 수 있습니다. 이 주소는 7일간만 유효하니 오래 보관하려면 그 안에 내려받아야 합니다.