Skip to main content
고객사에서 매월 확정된 캐시백 실적을 자체 리워드(예: 자체 재화, 쿠폰 등)로 전환하고자 하는 경우, 페어리에서 제공하는 확정 실적 조회 API를 활용해 실적 데이터를 조회하고, 이를 기반으로 리워드 전환 처리를 수행하셔야 합니다. 매월 정산일(예: 5~7일경) 시점에 배치 작업 또는 정기 스케줄러를 통해 API를 호출하여, 해당 월의 확정된 실적을 조회하고 전환 로직을 실행하는 방식으로 구현하실 수 있습니다.

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

(✅: 개발 필요한 부분)
Image

​
확정 실적 조회 API Spec

​
요청

​
엔드포인트

GET <https://api.public.moment.fairytech.ai/organization/:organizationPublicId/settled_transactions>

​
헤더

헤더명필수여부설명
x-moment-api-keyOAPI 서버 인증키

​
경로 파라미터

파라미터타입설명필수여부기본값
organizationPublicIdstring고객사 IDO-
<aside>
💡 Tip: 기존에 이메일로 organizationPublicId 값을 전달받지 못하신 경우,
eng@fairytech.ai 로 이메일 부탁드립니다. </aside>

​
쿼리스트링

파라미터타입설명필수여부기본값
yearnumber조회할 연도 (YYYY)O-
monthnumber조회할 월 (1-12)O-
pagenumber페이지 번호X1
limitnumber페이지당 데이터 수 (1~100)X100
user_idstring조회할 단일 사용자 IDX-
user_id 값을 전달하면 해당 사용자에 대한 실적만 조회하며, 이 경우 결과는 단일 사용자 기준으로 응답하므로 page 및 limit 파라미터는 필요하지 않습니다.

​
예시

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

​
응답

​
데이터

필드명타입설명
totalCountnumber전체 데이터 수
totalPagenumber전체 페이지 수
currentPagenumber현재 페이지 번호
settlementItemssettlementItem[]트랜잭션 데이터 배열
  • settlementItem
    필드명타입설명
    userIdstring사용자 ID
    confirmedAmountnumber해당 사용자의 실적 확정 커미션 총합
    • 조회 기간 동안 발생한 전체 거래에 대해 사용자별로 중복 없이 합산된 커미션을 반환하며, 응답은 userId 기준 오름차순으로 정렬됩니다.
    • confirmedAmount는 해당 사용자의 개별 커미션 금액을 각각 올림 처리후, 이를 모두 합산한 값입니다.

​
예시

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