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

새 사용자 프로필을 생성합니다. 민감한 정보(이름, 생년월일)는 AES-256-GCM으로 암호화되어 저장됩니다.

프로필 생성 시 사주팔자(四柱八字)가 자동으로 계산되어 `day_master`, `day_master_element`, `weakest_element` 필드에 저장됩니다.

<Note>
  동일한 `external_id`로 프로필이 이미 존재하면 409 Conflict 에러가 발생합니다.
</Note>

***

## Request Body 파라미터

<ParamField body="external_id" type="string">
  클라이언트 시스템의 사용자 ID입니다. 내 상점에서 관리하는 사용자를 식별하는 데 사용됩니다. 최대 길이는 255자입니다.
</ParamField>

<ParamField body="name" type="string" required>
  사용자 이름입니다. 최대 길이는 20자입니다. 이 값은 암호화되어 저장됩니다.
</ParamField>

<ParamField body="birth_year" type="integer" required>
  출생 연도입니다. 1900에서 2100 사이의 값이어야 합니다.
</ParamField>

<ParamField body="birth_month" type="integer" required>
  출생 월입니다. 1에서 12 사이의 값이어야 합니다.
</ParamField>

<ParamField body="birth_day" type="integer" required>
  출생 일입니다. 1에서 31 사이의 값이어야 합니다.
</ParamField>

<ParamField body="birth_hour" type="integer">
  출생 시입니다. 0에서 23 사이의 값이어야 합니다. 시주(時柱) 계산에 사용됩니다. 값을 넣지 않으면 시주 없이 연주, 월주, 일주만 계산됩니다.
</ParamField>

<ParamField body="gender" type="string" required>
  성별입니다. `male` 또는 `female` 중 하나입니다. 대운(大運) 계산에 사용됩니다.
</ParamField>

***

## Response

### 성공

프로필 생성에 성공하면 Profile 객체가 돌아옵니다. 민감한 정보는 마스킹되어 반환됩니다.

### 실패

프로필 생성에 실패하면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

| 상태 코드 | 에러 타입                  | 설명                            |
| ----- | ---------------------- | ----------------------------- |
| 400   | `validation_error`     | 요청 데이터가 유효하지 않음               |
| 401   | `authentication_error` | API 키가 유효하지 않음                |
| 409   | `conflict`             | 동일한 external\_id의 프로필이 이미 존재함 |
| 429   | `rate_limited`         | 요청 한도 초과                      |

***

## 요청 예시

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.sajuapi.dev/v1/profiles \
    -H "X-API-Key: bs_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "external_id": "user_12345",
      "name": "김철수",
      "birth_year": 1990,
      "birth_month": 3,
      "birth_day": 15,
      "birth_hour": 14,
      "gender": "male"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.sajuapi.dev/v1/profiles', {
    method: 'POST',
    headers: {
      'X-API-Key': 'bs_live_xxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      external_id: 'user_12345',
      name: '김철수',
      birth_year: 1990,
      birth_month: 3,
      birth_day: 15,
      birth_hour: 14,
      gender: 'male'
    })
  });

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

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

  response = requests.post(
      'https://api.sajuapi.dev/v1/profiles',
      headers={'X-API-Key': 'bs_live_xxx'},
      json={
          'external_id': 'user_12345',
          'name': '김철수',
          'birth_year': 1990,
          'birth_month': 3,
          'birth_day': 15,
          'birth_hour': 14,
          'gender': 'male'
      }
  )

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

***

## 응답 예시

```json theme={null}
{
  "id": "prf_abc123def456",
  "external_id": "user_12345",
  "name": "김**",
  "birth_year": "19**",
  "gender": "male",
  "day_master": "병화",
  "day_master_element": "fire",
  "weakest_element": "water",
  "created_at": "2025-01-15T09:00:00Z",
  "updated_at": "2025-01-15T09:00:00Z"
}
```

***

## Profile 객체

| 필드                   | 타입     | 설명                                                            |
| -------------------- | ------ | ------------------------------------------------------------- |
| `id`                 | string | 프로필 ID입니다. `prf_` 접두사로 시작합니다.                                 |
| `external_id`        | string | 클라이언트 시스템의 사용자 ID입니다.                                         |
| `name`               | string | 사용자 이름입니다. 마스킹되어 반환됩니다. (예: 김\*\*)                            |
| `birth_year`         | string | 출생 연도입니다. 마스킹되어 반환됩니다. (예: 19\*\*)                            |
| `gender`             | string | 성별입니다. `male` 또는 `female` 중 하나입니다.                            |
| `day_master`         | string | 일주(日柱)입니다. 갑목, 을목, 병화, 정화, 무토, 기토, 경금, 신금, 임수, 계수 중 하나입니다.    |
| `day_master_element` | string | 일주의 오행입니다. `wood`, `fire`, `earth`, `metal`, `water` 중 하나입니다. |
| `weakest_element`    | string | 가장 약한 오행입니다. 사주에서 가장 부족한 원소를 나타냅니다.                           |
| `created_at`         | string | 프로필 생성 시간입니다. ISO 8601 형식입니다.                                 |
| `updated_at`         | string | 프로필 수정 시간입니다. ISO 8601 형식입니다.                                 |