본문으로 건너뛰기
버전: 개발 버전 (최신)

문의하기 API

사용자가 시스템에 대한 문의사항을 제출할 수 있는 API입니다. 제출된 문의사항은 사용자 정보와 함께 담당자들에게 이메일로 전달됩니다.

문의하기 제출​

사용자의 문의사항을 접수하고 담당자들에게 이메일로 전달합니다.

  • HTTP Method: POST
  • Path: /v1/support/inquiry
  • 인증: 사용자 액세스 토큰 (accessToken) 필요

Headers​

HeaderTypeDescriptionRequired
AuthorizationstringBearer 토큰 형식의 JWT 액세스 토큰이 필요합니다. 사용자 인증을 통해 발급받은 액세스 토큰입니다.Yes
Accept-Languagestring응답 언어 (de-DE, ko-KR, en-US). 기본값: de-DENo

Request Body​

{
  "subject": "앱 사용 중 오류 발생",
  "message": "수면 데이터 입력 시 앱이 종료되는 문제가 발생합니다. 해결 방법을 알려주세요."
}
필드타입설명필수 (Yes/No)Validation
subjectstring문의 제목Yes최소 1자, 최대 200자
messagestring문의 내용Yes최소 10자, 최대 2000자

Responses​

HTTP Status Code설명Error Code(s)
201 Created문의 접수 성공-
400 Bad Request잘못된 요청 (필수 필드 누락, 유효성 검사 실패)1001
401 Unauthorized인증 실패 (토큰 누락, 만료, 유효하지 않음)1000
429 Too Many Requests요청 횟수 제한 초과1013
500 Internal Server Error서버 내부 오류1007
201 Created - 문의 접수 성공

문의가 성공적으로 접수되면 접수 정보가 반환됩니다.

{
  "inquiryId": "inq_c1e7c5cf-6fc2-4f4f-8e2f-9b8a3c5e2d1b",
  "status": "SUBMITTED",
  "submittedAt": 1714523700000
}
필드타입설명예시필수 (Yes/No)
inquiryIdstring문의 고유 식별자inq_c1e7c5cf-6fc2-4f4f-8e2f-9b8a3c5e2d1bYes
statusstring문의 상태 (SUBMITTED, IN_PROGRESS, RESOLVED)SUBMITTEDYes
submittedAtnumber문의 제출 시간 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64)1714523700000Yes
400 Bad Request - 잘못된 요청

예시: 유효성 검사 실패 (VALIDATION_FAILED - 1001)

{
  "code": 1001,
  "message": "VALIDATION_ERROR",
  "detail": "입력값이 유효하지 않습니다"
}
401 Unauthorized - 인증 실패
{
  "code": 1000,
  "message": "Invalid app token format or signature",
  "detail": "Unauthorized"
}
429 Too Many Requests - 요청 횟수 제한 초과
{
  "code": 1013,
  "message": "TOO_MANY_REQUESTS",
  "detail": "요청 횟수가 제한을 초과했습니다"
}
500 Internal Server Error - 서버 내부 오류
{
  "code": 1007,
  "message": "INTERNAL_SERVER_ERROR",
  "detail": "서버 내부 오류가 발생했습니다"
}

설명​

  • 이 API는 사용자의 액세스 토큰을 통해 사용자를 식별하고, 사용자 정보와 함께 문의사항을 담당자들에게 이메일로 전달합니다.
  • 주요 처리 단계:
    1. 액세스 토큰을 통한 사용자 인증 및 식별
    2. 요청 데이터 유효성 검사 (제목, 내용 길이 등)
    3. 사용자별 문의 제출 횟수 제한 확인 (일일 10회 제한)
    4. 문의 데이터베이스 저장
    5. 사용자 정보와 함께 담당자들에게 이메일 발송
  • 이메일 내용 포함 정보:
    • 사용자 기본 정보 (이메일, 사용자 ID)
    • 사용자 계정 상태 및 주기 정보
    • 문의 제목 및 내용
    • 제출 시간 및 문의 ID
  • 제한 사항:
    • 사용자당 일일 문의 제출 횟수: 10회
    • 제목 길이: 1-200자
    • 내용 길이: 10-2000자
  • 보안 고려사항:
    • 사용자 인증 필수
    • 입력 데이터 검증 및 XSS 방지
    • 스팸 방지를 위한 요청 횟수 제한

사용 예시​

기본 문의 제출​

curl -X POST "https://api.example.com/v1/support/inquiry" \
  -H "Authorization: Bearer {{USER_ACCESS_TOKEN}}" \
  -H "Accept-Language: de-DE" \
  -d '{
    "subject": "앱 사용 중 오류 발생",
    "message": "수면 데이터 입력 시 앱이 종료되는 문제가 발생합니다. 기기 정보: iPhone 14 Pro, iOS 17.1. 해결 방법을 알려주세요."
  }'

참고사항​

  • 문의 추적: 반환된 inquiryId를 통해 문의 상태를 추적할 수 있습니다.

변경 이력​

버전날짜작성자변경 내용
0.1.02025-10-13jeff@weltcorp.com최초 문서 작성