API 연동
인증과 공통 규격
인증 헤더, 응답 형식, 에러 코드, 허용 값, 본문 서식을 정리합니다.
기본 정보#
| Base URL | https://<도메인>/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은 필수입니다" } }에러 코드#
| HTTP | code | 언제 | 재시도 |
|---|---|---|---|
| 401 | UNAUTHORIZED | 키 누락, 잘못된 키, 폐기된 키 | X, 키 확인 |
| 403 | FORBIDDEN | 프로젝트에 연결되지 않은 키로 포털 토큰 발급 | X |
| 404 | NOT_FOUND | 없는 대상, 또는 다른 키가 접수한 이슈 | X |
| 422 | VALIDATION_FAILED | JSON 오류, 필수값 누락, 허용되지 않는 값, 이미 확정된 답변 | X, 요청 수정 |
| 500 | INTERNAL | 서버 오류 | O, 간격을 늘려가며 |
분기는 code로 하세요. message는 사람이 읽는 한국어 문장이라 예고 없이 바뀔 수 있습니다.
허용 값#
영문 코드 없이 한글 값 그대로 주고받습니다.
| 필드 | 값 |
|---|---|
category | 문의, 오류 |
priority | 낮음, 보통, 높음, 긴급 |
status | 접수, 진행중, 보류, 완료 |
channel | 자체, 채팅, 게시판, 메일, 유선, 대면, 외부 서비스 |
본문 서식#
이슈·댓글의 body는 아래 서식만 지원하는 일반 텍스트입니다. HTML 태그를 넣으면 글자 그대로 보입니다.
| 쓰는 법 | 결과 |
|---|---|
**굵게** | 굵게 |
*기울임* | 기울임 |
[글자](https://...) | 링크 |
 | 이미지 |
- 항목 (줄 맨 앞) | 목록 |
- 링크·이미지 주소는
http://,https://만 허용됩니다. - API로는 파일을 올릴 수 없습니다. 이미지는 파트너 쪽에 올려둔 주소를 본문에 넣습니다.
- 포털로 접수된 이슈를 조회하면 고객이 첨부한 이미지가 우리 쪽 서명 주소로 들어 있을 수 있습니다. 이 주소는 7일간만 유효하니 오래 보관하려면 그 안에 내려받아야 합니다.