API 명세

공통 Base URL (Host)

Preview (테스트): https://app-api-reward.unifi.me
Production (라이브): https://api-reward.unifi.me

사용자 매핑 상태 확인

특정 사용자가 현재 Unifi 계정에 연결되어 있는지 확인합니다.

GET /v1/mission-users

Section	Name	Type	Req	Description

Header	X-Partner-Id	String	Y	발급된 Partner ID
Header	X-Api-Key	String	Y	발급된 API Key
Query	partnerUid	String	Y	서비스 내 고유 사용자 ID
Response	result	Boolean	Y	매핑 상태(true: 연결됨, false: 연결 안 됨)

Unifi Login용 Auth URL (Auth)

사용자를 Unifi 로그인 화면으로 리다이렉트하고 일회성 매핑 토큰 발급을 트리거하는 프론트엔드 전용 API입니다. (브라우저 직접 이동 방식이므로 헤더 인증 키를 포함하지 않습니다.)

GET /v1/mission-users/auth

Section	Name	Type	Req	Description

Query	partnerId	String	Y	발급된 Partner ID
Query	redirectUrl	String	Y	로그인 후 복귀할 서비스 Mini App URL (*URL 인코딩 필요)
Query	browserType	String	N	접속 환경 지정(MINI: LINE MINI, LIFF: LINE LIFF, WEB: 그 외. 비어 있으면 WEB으로 동작)
Response	302 Found	-	-	구성된 LINE LIFF 로그인 URL로 브라우저를 즉시 리다이렉트합니다

사용자 매핑 등록 (Connect)

일회성 매핑 토큰을 사용하여 Unifi 계정과 서비스 계정 간의 연결을 최종 확정합니다.

POST /v1/mission-users/connect

Section	Name	Type	Req	Description

Header	X-Partner-Id	String	Y	발급된 Partner ID
Header	X-Api-Key	String	Y	발급된 API Key
Body (JSON)	token	String	Y	URL 파라미터로 수신한 일회성 매핑 토큰
Body (JSON)	partnerUid	String	Y	서비스 내 고유 사용자 ID
Body (JSON)	region	String	Y	사용자의 국가 코드(예: KR, JP, TW 등)
Response	200 OK	-	-	빈 본문, 매핑 성공

미션 달성 (Achieve Mission)

사용자의 미션 진행 상황과 최종 완료 상태를 Unifi 서버에 실시간으로 upsert합니다. (보안 및 IP 제한: 사전에 합의된 서비스 서버의 Outbound IP(Whitelist)에서만 호출할 수 있습니다.)

이 API가 호출되면 Unifi는 요청에 담긴 missionKey로 어떤 미션인지 찾은 다음, 유효한 달성인지 확인하고 보상을 지급합니다.

POST /v1/achieve

Section	Name	Type	Req	Description

Header	X-Partner-Id	String	Y	발급된 Partner ID
Header	X-Api-Key	String	Y	발급된 API Key
Body (JSON)	partnerUid	String	Y	서비스 내 고유 사용자 ID
Body (JSON)	missionKey	String	Y	Unifi가 전달한 Mission Key
Body (JSON)	completed	Boolean	Y	미션 완료 상태(true로 저장되면 되돌릴 수 없습니다)
Body (JSON)	metadata.target	Int	N	미션의 최대 목표 값(진행률 게이지 UI용)
Body (JSON)	metadata.current	Int	N	미션의 현재 진행 값
Response	200 OK	-	-	빈 본문, 저장 성공

데이터 전송 예시 (JSON Payload)

{
  "partnerUid": "user_77799",
  "missionKey": "SAMPLE_MISSION_KEY_001",
  "completed": false,
  "metadata": {
    "target": 30,
    "current": 5
  }
}

에러 코드

Code	Name	Category

901	ADMIN_PERMISSION_DENIED	Admin
1101	NOT_FOUND_MISSION_GROUP	MissionGroup
1201	NOT_FOUND_MISSION	Mission
1401	NOT_FOUND_REWARD_ASSET	RewardAsset
1402	NOT_SET_REWARD_ASSET_DECIMALS	RewardAsset
1902	NOT_FOUND_REWARD_BUDGET	Budget
2101	NOT_FOUND_PROMOTION	Promotion
2102	IMMUTABLE_PROMOTION_FIELD	Promotion

Enum 정의

Enum Name	Values	Description

PromotionType	COMPOSITE, DAILY_CHECK	프로모션 유형
PromotionStatus	ACTIVE, INACTIVE	프로모션 활성/비활성 상태
RecurrenceType	ONE_TIME, DAILY, WEEKLY, MONTHLY	반복 주기
RewardType	FIXED, LUCKY_DRAW	고정 리워드 / 럭키 드로우
BudgetType	FIXED, LUCKY_DRAW	예산 유형
AssetType	FT	에셋 유형
ClaimStatus	RESERVED, REQUESTED, REJECTED, SUCCEEDED, FAILED	리워드 클레임 상태
TicketFilter	NOT_RECEIVED, RECEIVED, DRAWN	티켓 필터

공통 Base URL (Host)​

사용자 매핑 상태 확인​

Unifi Login용 Auth URL (Auth)​

사용자 매핑 등록 (Connect)​

미션 달성 (Achieve Mission)​

에러 코드​

Enum 정의​