> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sajuapi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 빠른 시작

> 5분 안에 사주 API 시작하기

## 1단계: API 키 발급받기

<Steps>
  <Step title="계정 생성">
    [dashboard.sajuapi.dev](https://dashboard.sajuapi.dev)에서 회원가입
  </Step>

  <Step title="API 키 생성">
    **설정** → **API 키** → **새 키 생성**으로 이동
  </Step>

  <Step title="키 복사">
    API 키는 다음과 같은 형식입니다: `bs_live_xxxxxxxxxxxxxxxxxxxxxxxx`
  </Step>
</Steps>

<Warning>
  API 키를 안전하게 보관하세요. 클라이언트 코드나 공개 저장소에 노출하지 마세요.
</Warning>

## 2단계: 사주 계산하기

운세 API를 호출하기 전에 사용자의 사주팔자를 계산해야 합니다. 두 가지 방법이 있습니다:

### 옵션 A: SDK 계산기 사용 (권장)

```javascript theme={null}
// SDK 설치
npm install @sajuapi/sdk

// 사주 계산
import { SajuCalculator } from '@sajuapi/sdk';

const saju = SajuCalculator.calculate({
  year: 1990,
  month: 5,
  day: 15,
  hour: 14,  // 24시간 형식, 모르면 null
  gender: 'male'
});

console.log(saju.pillars);
// { year: { stem: {...}, branch: {...} }, month: {...}, day: {...}, hour: {...} }
```

### 옵션 B: 사주 API 엔드포인트 사용

```bash theme={null}
curl -X POST https://api.sajuapi.dev/api/saju \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "year": 1990,
    "month": 5,
    "day": 15,
    "hour": 14,
    "gender": "male"
  }'
```

## 3단계: 오늘의 운세 가져오기

개인화된 운세를 조회합니다:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.sajuapi.dev/api/daily-fortune', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'your_api_key'
    },
    body: JSON.stringify({
      saju: saju,           // 2단계에서 계산한 값
      userName: '홍길동',
      model: 'haiku'        // 또는 'sonnet', 'gpt4o'
    })
  });

  const { data } = await response.json();
  console.log(data.todayFortune.score);        // 78
  console.log(data.todayFortune.actionItems);  // [{ type: 'do', text: '...' }]
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.sajuapi.dev/api/daily-fortune',
      headers={
          'Content-Type': 'application/json',
          'X-API-Key': 'your_api_key'
      },
      json={
          'saju': saju,
          'userName': '홍길동',
          'model': 'haiku'
      }
  )

  data = response.json()['data']
  print(data['todayFortune']['score'])  # 78
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.sajuapi.dev/api/daily-fortune \
    -H "Content-Type: application/json" \
    -H "X-API-Key: your_api_key" \
    -d '{
      "saju": {...},
      "userName": "홍길동",
      "model": "haiku"
    }'
  ```
</CodeGroup>

## 4단계: 운세 표시하기

운세를 표시하는 간단한 React 컴포넌트 예시:

```tsx theme={null}
function FortuneCard({ fortune }) {
  return (
    <div className="fortune-card">
      <div className="score">
        <span className="value">{fortune.todayFortune.score}</span>
        <span className="label">오늘의 투자운</span>
      </div>

      <p>{fortune.todayFortune.overallAnalysis}</p>

      <div className="actions">
        {fortune.todayFortune.actionItems.map((item, i) => (
          <div key={i} className={`action ${item.type}`}>
            <span>{item.type === 'do' ? '✓' : '✕'}</span>
            <span>{item.text}</span>
          </div>
        ))}
      </div>

      <div className="timing">
        <div>추천 시간: {fortune.todayFortune.timing.best}</div>
        <div>피해야 할 시간: {fortune.todayFortune.timing.avoid}</div>
      </div>
    </div>
  );
}
```

## 다음 단계

<CardGroup cols={2}>
  <Card title="API 레퍼런스" icon="book" href="/api-reference/overview">
    모든 엔드포인트 살펴보기
  </Card>

  <Card title="캐싱 가이드" icon="database" href="/guides/caching">
    캐싱으로 성능 최적화하기
  </Card>

  <Card title="스트리밍" icon="bolt" href="/api-reference/endpoints/fortune-stream">
    실시간 응답을 위한 SSE 사용하기
  </Card>

  <Card title="에러 처리" icon="triangle-exclamation" href="/api-reference/errors">
    에러를 우아하게 처리하기
  </Card>
</CardGroup>