보정내역 조회 API

확정 실적 외에 별도로 지급된 보정 금액을 사용자별로 조회하는 API입니다.

정산 시 확정 실적 조회 API(V2)의 confirmedAmount에 더해, 본 API에서 조회한 adjustmentAmount를 반영하여 최종 정산 금액을 산출할 수 있습니다.

요청

엔드포인트

GET /organization/{ORGANIZATION_PUBLIC_ID}/adjustments

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를 입력합니다.

요청 쿼리스트링

파라미터	타입	설명	필수여부	기본값
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 값을 전달하면 해당 사용자에 대한 보정 내역만 조회합니다.

요청 예시

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

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

응답 데이터

필드명	타입	설명
totalCount	number	전체 데이터 수
totalPage	number	전체 페이지 수
currentPage	number	현재 페이지 번호
adjustmentItems	adjustmentItem[]	보정 내역 데이터 배열

• adjustmentItem 구조

  필드명	타입	설명
  userId	string	사용자 ID
  adjustmentAmount	number	해당 사용자의 보정 순금액

  • 조회 기간 동안 발생한 보정 지급과 회수를 합산한 순금액을 사용자별로 반환하며, 응답은 userId 기준 오름차순으로 정렬됩니다.
  • adjustmentAmount가 양수이면 추가 지급, 음수이면 회수가 더 많았음을 의미합니다.

응답 예시

{
  "totalCount": 3,
  "totalPage": 1,
  "currentPage": 1,
  "adjustmentItems": [
    {
      "userId": "USER-123",
      "adjustmentAmount": 500
    },
    {
      "userId": "USER-456",
      "adjustmentAmount": 1200
    },
    {
      "userId": "USER-789",
      "adjustmentAmount": 300
    }
  ]
}

에러 응답

HTTP 상태	조건
400 Bad Request	year, month 누락 / page < 1 / limit < 1
403 Forbidden	해당 기능이 활성화되지 않은 조직

Error Codes

HTTP	Code	설명
400	INVALID_REQUEST	필수 필드 누락 / 포맷 오류
401	UNAUTHORIZED	API Key 오류
409	DUPLICATE_TRANSACTION	이미 동일한 transactionId가 존재
422	INVALID_AMOUNT	금액·통화 조합이 잘못됨
500	INTERNAL_ERROR	서버 오류, 재시도 필요