본문으로 건너뛰기

Saju API

사주 등록·수정·조회 및 오늘의 기운, 연운, 정통사주 관련 엔드포인트입니다.

엔드포인트 목록​

메서드경로설명인증
POST/api/saju사주 등록 (오늘의 기운 함께 생성)필요
GET/api/saju/me내 사주 기본 정보 조회필요
PUT/api/saju/me사주 수정필요
GET/api/saju/me/traditional정통사주 조회 (8자·오행·대운)필요
GET/api/saju/me/daily오늘의 기운 조회필요
GET/api/saju/me/year올해운세 조회 (비동기)필요
GET/api/saju/me/traditional-fortune정통사주풀이 연간 운세 조회필요
GET/api/saju/me/compatibility/{partnerId}파트너와의 궁합 조회 (비동기)필요
GET/api/saju/me/zodiac-compatibility띠별 궁합 조회필요

POST /api/saju​

사주 8자를 계산하고 저장합니다. 오늘의 기운도 함께 생성됩니다.

처리 흐름:

  1. Ablecity → 사주 8자·오행·용신·격국 계산
  2. Ablecity → 오늘 기운 점수·요약 조회
  3. GPT → 일별 인사이트 생성 (기분·추천 행동 등)
  4. saju_info + daily_energy DB 저장
  5. 사주 + 오늘의 기운 통합 응답 반환

에러:

상황HTTP에러 코드
중복 등록409SAJU_ALREADY_EXISTS
Ablecity 장애502EXTERNAL_API_ERROR
GPT 오류500LLM_ERROR

GET /api/saju/me​

이메일·닉네임·사주 입력값(생년월일·성별·음양력·도시)을 반환합니다. 사주 미등록 시 사주 필드는 null입니다.

PUT /api/saju/me​

생년월일 등 변경 시 외부 API를 재호출하여 사주를 다시 계산합니다. 수정 시 오늘 날짜의 기운 캐시도 함께 삭제되어 다음 조회 시 새 사주 기준으로 재생성됩니다.

GET /api/saju/me/daily​

오늘의 기운을 조회합니다. DB 캐시 히트 시 즉시 반환하고, 미스 시 Ablecity + GPT를 호출 후 저장합니다.

GET /api/saju/me/year​

올해 연운을 조회합니다. Ablecity의 연산이 수 초~수십 초 소요되므로 비동기 웹훅 방식으로 처리합니다.

  • 캐시 히트: status: COMPLETE + 데이터 반환
  • 캐시 미스: Ablecity 비동기 요청 후 대기 → 완료 시 COMPLETE, 타임아웃 시 PENDING 반환

GET /api/saju/me/compatibility/{partnerId}​

파트너와의 궁합을 조회합니다. 연운과 동일한 비동기 웹훅 방식으로 처리됩니다.

파라미터위치설명
partnerIdpath파트너 ID

에러:

상황HTTP에러 코드
사주 미등록404SAJU_NOT_FOUND
파트너 없음404PARTNER_NOT_FOUND