확정실적 목록 조회 API

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

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

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

(✅: 개발 필요한 부분)

확정 실적 조회 API Spec

요청

엔드포인트

GET /organization/{ORGANIZATION_PUBLIC_ID}/settled_transactions

Base URL: https://api.public.moment.fairytech.ai

헤더

헤더명	필수여부	설명
x-moment-api-key	O	Fairy에서 제공한 Server API Key

경로 파라미터

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

{ORGANIZATION_PUBLIC_ID}에는 Fairy에서 제공한 고객사 ID를 입력합니다. 값을 제공받지 못했다면 eng@fairytech.ai로 문의하세요.

쿼리스트링

파라미터	타입	설명	필수여부	기본값
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 파라미터는 필요하지 않습니다.

요청 예시

ORGANIZATION_PUBLIC_ID="{ORGANIZATION_PUBLIC_ID}"
SERVER_API_KEY="{SERVER_API_KEY}"
YEAR="2025"
MONTH="11"
PAGE="1"
LIMIT="20"

curl -X GET \
  "https://api.public.moment.fairytech.ai/organization/${ORGANIZATION_PUBLIC_ID}/settled_transactions?year=${YEAR}&month=${MONTH}&page=${PAGE}&limit=${LIMIT}" \
  -H "x-moment-api-key: ${SERVER_API_KEY}"

응답

데이터

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

• settlementItem

  필드명	타입	설명
  userId	string	사용자 ID
  confirmedAmount	number	해당 사용자의 실적 확정 커미션 총합

  • 조회 기간 동안 발생한 전체 거래에 대해 사용자별로 중복 없이 합산된 커미션을 반환하며, 응답은 userId 기준 오름차순으로 정렬됩니다.
  • confirmedAmount는 해당 사용자의 개별 커미션 금액을 각각 올림 처리후, 이를 모두 합산한 값입니다.

응답 예시

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