> ## 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.

# 운세 복호화 조회

<Info>
  **v1 Enterprise API (Coming Soon)**

  이 엔드포인트는 Enterprise 버전에서 제공될 예정입니다.
  현재는 [v0 API](/api-reference/v0/overview)를 사용하세요.
</Info>

암호화된 운세 데이터를 복호화하여 원본 데이터를 조회합니다. 이 엔드포인트는 민감한 개인정보를 반환하므로 모든 요청이 감사 로그에 기록됩니다.

<Warning>
  이 엔드포인트는 민감한 개인정보(프로필의 이름, 생년월일 등)를 평문으로 반환합니다. 모든 요청은 자동으로 감사 로그에 기록되며, 비정상적인 접근 패턴은 보안 검토 대상이 됩니다.
</Warning>

***

## Path 파라미터

<ParamField path="id" type="string" required>
  조회할 운세의 ID입니다. `ftn_` 접두사로 시작합니다.
</ParamField>

***

## Response

### 성공

운세 복호화 조회에 성공하면 마스킹되지 않은 원본 데이터가 포함된 Fortune 객체가 반환됩니다.

### 실패

| 상태 코드 | 에러 타입                  | 설명             |
| ----- | ---------------------- | -------------- |
| 401   | `authentication_error` | API 키가 유효하지 않음 |
| 403   | `forbidden`            | 복호화 권한이 없음     |
| 404   | `not_found`            | 운세를 찾을 수 없음    |
| 429   | `rate_limited`         | 요청 한도 초과       |

***

## 요청 예시

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.sajuapi.dev/v1/fortunes/ftn_xyz789abc123/unmasked \
    -H "X-API-Key: bs_live_xxx"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.sajuapi.dev/v1/fortunes/ftn_xyz789abc123/unmasked',
    {
      headers: {
        'X-API-Key': 'bs_live_xxx'
      }
    }
  );

  const fortune = await response.json();
  ```

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

  response = requests.get(
      'https://api.sajuapi.dev/v1/fortunes/ftn_xyz789abc123/unmasked',
      headers={'X-API-Key': 'bs_live_xxx'}
  )

  fortune = response.json()
  ```
</CodeGroup>

***

## 응답 예시

```json theme={null}
{
  "id": "ftn_xyz789abc123",
  "profile_id": "prf_abc123def456",
  "fortune_type": "daily",
  "fortune_date": "2025-01-16",
  "model": "sonnet",
  "score": 85,
  "summary": "오늘은 새로운 기회가 찾아오는 날입니다.",
  "categories": {
    "overall": {
      "score": 85,
      "description": "전반적으로 긍정적인 하루가 예상됩니다."
    },
    "wealth": {
      "score": 75,
      "description": "재물운이 안정적입니다."
    },
    "love": {
      "score": 90,
      "description": "인간관계가 원만합니다."
    },
    "health": {
      "score": 80,
      "description": "건강은 양호합니다."
    },
    "career": {
      "score": 88,
      "description": "업무에서 좋은 성과가 기대됩니다."
    }
  },
  "lucky_items": {
    "number": 7,
    "color": "빨강",
    "direction": "남쪽",
    "time": "오후 2시-4시"
  },
  "advice": "오늘은 적극적으로 행동하되, 중요한 결정은 신중하게 내리세요.",
  "profile": {
    "id": "prf_abc123def456",
    "name": "김철수",
    "birth_year": 1990,
    "birth_month": 3,
    "birth_day": 15,
    "birth_hour": 14,
    "gender": "male",
    "day_master": "병화",
    "day_master_element": "fire",
    "weakest_element": "water",
    "saju": {
      "pillars": {
        "year": { "stem": "경", "branch": "오", "element": "metal" },
        "month": { "stem": "기", "branch": "묘", "element": "earth" },
        "day": { "stem": "병", "branch": "인", "element": "fire" },
        "hour": { "stem": "을", "branch": "미", "element": "wood" }
      },
      "elements": {
        "wood": 2,
        "fire": 3,
        "earth": 1,
        "metal": 1,
        "water": 1
      }
    }
  },
  "analysis": {
    "day_energy": "오늘의 일진은 갑인(甲寅)으로 목(木) 기운이 강합니다. 병화(丙火) 일주인 당신에게 목 기운은 생기를 불어넣어 창의력과 활력이 높아집니다.",
    "element_interaction": "본인의 화(火) 기운과 오늘의 목(木) 기운이 상생 관계를 이루어 긍정적인 에너지가 흐릅니다.",
    "recommendations": [
      "새로운 프로젝트를 시작하기 좋은 날입니다",
      "창의적인 활동에 집중하세요",
      "오후 시간대에 중요한 미팅을 잡으세요"
    ]
  },
  "cached": false,
  "generated_at": "2025-01-16T09:00:00Z",
  "latency_ms": 2340
}
```

***

## 마스킹 vs 비마스킹 비교

| 필드                    | 마스킹 (GET /fortunes/{id}) | 비마스킹 (GET /fortunes/{id}/unmasked) |
| --------------------- | ------------------------ | ---------------------------------- |
| `profile.name`        | 김\*\*                    | 김철수                                |
| `profile.birth_year`  | 19\*\*                   | 1990                               |
| `profile.birth_month` | -                        | 3                                  |
| `profile.birth_day`   | -                        | 15                                 |
| `profile.birth_hour`  | -                        | 14                                 |
| `profile.saju`        | -                        | 완전한 사주 정보                          |
| `analysis`            | -                        | 상세 분석                              |

***

## 감사 로그

모든 복호화 요청은 자동으로 감사 로그에 기록됩니다.

```json theme={null}
{
  "action": "fortune.unmasked",
  "resource_type": "fortune",
  "resource_id": "ftn_xyz789abc123",
  "actor_ip": "203.0.113.42",
  "actor_api_key": "bs_live_xxx...",
  "request_id": "req_xyz789",
  "metadata": {
    "profile_id": "prf_abc123def456"
  },
  "created_at": "2025-01-16T15:00:00Z"
}
```

<Note>
  복호화 요청 빈도가 비정상적으로 높은 경우 보안 알림이 발생할 수 있습니다. 필요한 경우에만 이 엔드포인트를 사용하고, 가능하면 마스킹된 데이터를 사용하세요.
</Note>