← 블로그튜토리얼

사주팔자 API 연동 — Node.js/TypeScript 튜토리얼

2026. 6. 6.

갱신 (2026-11-03) — 코드 예제를 현행 API(v2) 기준으로 갱신했습니다. 예시 입력은 무료 키로 바로 실행되는 공개 샘플 사주입니다.

사주팔자 API 한 줄 호출

사주팔자 API 는 생년월일과 시간을 받아 연·월·일·시주를 돌려줍니다. 사주 API 에서 사주팔자를 받는 엔드포인트는 POST /v2/sazu/manse 입니다.

const res = await fetch('https://api.sazu.app/v2/sazu/manse', {
  method: 'POST',
  headers: { 'x-api-key': process.env.SAZU_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ birthYear: 1998, birthMonth: 5, birthDay: 19, birthHour: 10, isFemale: false }),
})
const { data } = await res.json()
console.log(data.modules.fourPillars) // 연·월·일·시주

타입 안전하게 다루기

TypeScript 라면 응답을 타입으로 감싸 안전하게 처리합니다. 공식 @sazuapp/client SDK 를 쓰면 타입이 함께 제공됩니다.

  • 필수 필드: birthYear, birthMonth, birthDay (camelCase, "birth" 접두사)
  • 주의: month 는 1~12 — JavaScript Date.getMonth() 의 0~11 을 그대로 보내면 거부됩니다
  • 성별(isFemale)은 대운 방향에 영향 — 명시 권장

에러 핸들링

429(한도 초과), 400(필드 오류)를 구분해 처리하세요. 본인 키의 최근 오류는 GET /v2/me/errors 로 조회할 수 있습니다.

다음 단계

응답 크기를 줄이고 싶다면 목적에 맞는 토픽을 선택하세요. v2 는 modules 파라미터 대신 토픽(/v2/sazu/yearly·/v2/sazu/today 등)이 필요한 모듈만 담아 보내고, detail 파라미터로 해석 텍스트의 양도 줄일 수 있습니다. 전체 토픽과 응답 스키마는 API 문서에 있습니다.

SAZU 의 사주 API 는 신용카드 없이 무료로 시작할 수 있습니다. 합형충파해·격국·용신·12운성 등 분석 모듈을 단일 호출로 제공하며, 응답은 평균 약 100ms 입니다. 무료 한도와 플랜별 요금은 요금 안내에 있습니다. 자세한 사용법은 API 문서에서 확인하세요.

SAZU API를 시작해보세요

신용카드 없이, 무료로 시작할 수 있습니다.