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

# 확정실적 목록 조회 API

고객사에서 매월 확정된 캐시백 실적을 자체 리워드(예: 자체 재화, 쿠폰 등)로 전환하고자 하는 경우, 페어리에서 제공하는 **확정 실적 조회 API**를 활용해 실적 데이터를 조회하고, 이를 기반으로 리워드 전환 처리를 수행하셔야 합니다.

**매월 정산일(예: 5\~7일경) 시점에 배치 작업 또는 정기 스케줄러를 통해 API를 호출**하여, 해당 월의 확정된 실적을 조회하고 전환 로직을 실행하는 방식으로 구현하실 수 있습니다.

### 확정 실적 기반 고객사 리워드 전환 및 사용자 조회 시나리오

(✅: 개발 필요한 부분)

<Frame>
  <img src="https://mintcdn.com/fairytech/W2ba7D5O-OwnnDf5/images/image-6.png?fit=max&auto=format&n=W2ba7D5O-OwnnDf5&q=85&s=fb2004fd882fd69398df3db785bf8ef5" alt="Image" width="766" height="976" data-path="images/image-6.png" />
</Frame>

# 확정 실적 조회 API Spec

## 요청

### 엔드포인트

```json theme={null}
GET <https://api.public.moment.fairytech.ai/organization/:organizationPublicId/settled_transactions>
```

### 헤더

| 헤더명              | 필수여부 | 설명         |
| :--------------- | :--- | :--------- |
| x-moment-api-key | O    | API 서버 인증키 |

### 경로 파라미터

| 파라미터                 | 타입     | 설명     | 필수여부 | 기본값 |
| :------------------- | :----- | :----- | :--- | :-- |
| organizationPublicId | string | 고객사 ID | O    | -   |

\<aside>\
💡 **Tip:** 기존에 이메일로 organizationPublicId 값을 전달받지 못하신 경우,\
[eng@fairytech.ai](mailto:eng@fairytech.ai) 로 이메일 부탁드립니다.

\</aside>

### 쿼리스트링

| 파라미터     | 타입     | 설명                  | 필수여부 | 기본값 |
| :------- | :----- | :------------------ | :--- | :-- |
| year     | number | 조회할 연도 (YYYY)       | O    | -   |
| month    | number | 조회할 월 (1-12)        | O    | -   |
| page     | number | 페이지 번호              | X    | 1   |
| limit    | number | 페이지당 데이터 수 (1\~100) | X    | 100 |
| user\_id | string | 조회할 단일 사용자 ID       | X    | -   |

`user_id` 값을 전달하면 해당 사용자에 대한 실적만 조회하며, 이 경우 결과는 단일 사용자 기준으로 응답하므로 page 및 limit 파라미터는 필요하지 않습니다.

### 예시

```sql theme={null}
GET <https://api.public.moment.fairytech.ai/organization/fairy_card/settled_transactions?year=2025&month=11&page=1&limit=20>
```

## 응답

### 데이터

| 필드명             | 타입                  | 설명          |
| :-------------- | :------------------ | :---------- |
| totalCount      | number              | 전체 데이터 수    |
| totalPage       | number              | 전체 페이지 수    |
| currentPage     | number              | 현재 페이지 번호   |
| settlementItems | `settlementItem`\[] | 트랜잭션 데이터 배열 |

* `settlementItem`
  | 필드명             | 타입     | 설명                   |
  | :-------------- | :----- | :------------------- |
  | userId          | string | 사용자 ID               |
  | confirmedAmount | number | 해당 사용자의 실적 확정 커미션 총합 |
  * 조회 기간 동안 발생한 전체 거래에 대해 사용자별로 중복 없이 합산된 커미션을 반환하며, 응답은 userId 기준 오름차순으로 정렬됩니다.
  * confirmedAmount는 해당 사용자의 개별 커미션 금액을 각각 올림 처리후, 이를 모두 합산한 값입니다.

### 예시

```json theme={null}
{
  "totalCount": 40,
  "totalPage": 20,
  "currentPage": 1,
  "settlementItems": [
    {
      "userId": "USER-123",
      "confirmedAmount": 957
    },
    {
      "userId": "USER-456",
      "confirmedAmount": 4877
    },
  ]
}
```