사주 API v1은 RESTful 리소스 기반 설계로 전면 개편되었습니다.
기존 /api/* 엔드포인트는 deprecated되며, /v1/* 엔드포인트로 마이그레이션해야 합니다.
기존 엔드포인트는 2025년 6월까지 지원됩니다.
Deprecation 헤더가 포함된 응답을 받고 있다면 마이그레이션을 진행해 주세요.
주요 변경사항
엔드포인트 변경
| 기존 | 신규 | 변경 내용 |
|---|
| POST /api/daily-fortune | POST /v1/fortunes | 리소스 기반 URL |
| POST /api/daily-fortune-stream | POST /v1/fortunes/stream | 경로 구조 변경 |
| POST /api/saju | POST /v1/calculations/saju | 계산 리소스로 분리 |
| POST /api/fortune | POST /v1/calculations/yearly | 연간 운세 계산 |
| - | GET/POST/PUT/DELETE /v1/profiles | 프로필 CRUD 추가 |
| - | GET /v1/fortunes | 운세 목록 조회 추가 |
| - | /v1/*/unmasked | 복호화 엔드포인트 추가 |
요청 형식 변경
기존 방식
{
"saju": {
"pillars": { ... },
"dayMaster": { ... }
},
"userName": "김철수",
"model": "haiku"
}
신규 방식
{
"profile_id": "prf_abc123",
"type": "daily",
"model": "haiku"
}
v1에서는 사주 정보를 직접 전송하는 대신 프로필 ID를 참조합니다.
프로필에 사주 정보가 저장되어 있습니다.
마이그레이션 단계
1단계: 프로필 생성
기존에 클라이언트에서 관리하던 사용자 데이터를 프로필로 등록합니다:
# 프로필 생성
curl -X POST https://api.sajuapi.dev/v1/profiles \
-H "X-API-Key: bs_live_xxx" \
-d '{
"external_id": "user_12345",
"name": "김철수",
"birth_year": 1990,
"birth_month": 3,
"birth_day": 15,
"birth_hour": 14,
"gender": "male"
}'
id를 저장합니다:
{
"id": "prf_abc123", // ← 이 ID를 저장
"external_id": "user_12345",
"day_master": "병화",
...
}
2단계: 기존 사주 계산 코드 제거
프로필 생성 시 사주가 자동으로 계산되므로 클라이언트 측 사주 계산 로직을 제거합니다:
// 기존 코드 (제거)
const saju = SajuCalculator.calculate({
year: birthYear,
month: birthMonth,
day: birthDay,
hour: birthHour,
gender: gender
});
// 신규 코드 (프로필 ID만 사용)
const profileId = "prf_abc123";
3단계: 운세 요청 변경
// 기존 코드
const response = await fetch('/api/daily-fortune', {
method: 'POST',
headers: { 'X-API-Key': API_KEY },
body: JSON.stringify({
saju: saju,
userName: '김철수',
model: 'haiku',
date: '2025-01-15'
})
});
// 신규 코드
const response = await fetch('/v1/fortunes', {
method: 'POST',
headers: {
'X-API-Key': API_KEY,
'Idempotency-Key': `fortune-2025-01-15-${profileId}`
},
body: JSON.stringify({
profile_id: profileId,
type: 'daily',
model: 'haiku',
date: '2025-01-15'
})
});
4단계: 응답 형식 대응
응답 구조가 일부 변경되었습니다:
// 기존 응답
{
"success": true,
"data": {
"character": { ... },
"todayFortune": { ... }
},
"meta": { ... }
}
// 신규 응답
{
"id": "ftn_xyz789",
"profile_id": "prf_abc123",
"type": "daily",
"score": 78,
"data": {
"character": { ... },
"today_fortune": { ... } // camelCase → snake_case
},
"meta": { ... },
"created_at": "2025-01-15T09:00:00Z"
}
필드명 변경
| 기존 (camelCase) | 신규 (snake_case) |
|---|
userName | name (프로필) |
todayFortune | today_fortune |
dayMaster | day_master |
investmentTendency | investment_tendency |
actionItems | action_items |
overallAnalysis | overall_analysis |
호환성 레이어
마이그레이션 기간 동안 기존 엔드포인트는 리다이렉트됩니다:
POST /api/daily-fortune HTTP/1.1
HTTP/1.1 301 Moved Permanently
Location: /v1/fortunes
Deprecation: true
Sunset: 2025-06-30
Deprecation: true 헤더가 포함된 응답을 받으면
가능한 빨리 신규 엔드포인트로 전환하세요.
SDK 업데이트
JavaScript SDK
npm update @sajuapi/sdk@latest
// 기존 SDK
import { getDailyFortune } from '@sajuapi/sdk';
const fortune = await getDailyFortune(saju, userName);
// 신규 SDK
import { SajuClient } from '@sajuapi/sdk';
const client = new SajuClient({ apiKey: API_KEY });
// 프로필 생성 (최초 1회)
const profile = await client.profiles.create({
name: '김철수',
birthYear: 1990,
// ...
});
// 운세 조회
const fortune = await client.fortunes.create({
profileId: profile.id,
type: 'daily'
});
Python SDK
pip install --upgrade sajuapi
# 기존 SDK
from sajuapi import get_daily_fortune
fortune = get_daily_fortune(saju, user_name)
# 신규 SDK
from sajuapi import SajuClient
client = SajuClient(api_key=API_KEY)
# 프로필 생성 (최초 1회)
profile = client.profiles.create(
name="김철수",
birth_year=1990,
# ...
)
# 운세 조회
fortune = client.fortunes.create(
profile_id=profile.id,
type="daily"
)
체크리스트
마이그레이션 관련 문의는 아래 채널로 연락해 주세요:
