SaaS API결제 및 예산
부족분 lock 생성/재계산
80% 의무 미달분만큼을 캠페인 예산 내에서 lock합니다.
부족분 lock 생성/재계산
캠페인의 80% 의무 기준 대비 부족분(threshold - sumLockedNormal)만큼을 캠페인 예산 내에서 lock합니다. 이미 lock 행이 존재하면 멱등적으로 재계산합니다.
기업 사용자(해당 캠페인 소유자)와 관리자 모두 호출 가능합니다.
개요
NORMAL lock(크리에이터별 reservation)만으로 80% 임계값을 충족하지 못할 때, 기업이 본 API를 호출하여 부족분을 캠페인 예산 안에서 lock 처리합니다. lock된 금액은 캠페인 종료 시 환급에서 제외되어 기업의 80% 의무가 충족됩니다.
이후 NORMAL lock이 증가하여 80% 임계를 넘으면 시스템이 자동으로 lock을 해제하며, 다시 감소하면 자동으로 lock을 복구합니다.
HTTP 요청
POST /ai/campaigns/{collabNo}/budget/deficit-lock
Authorization: Bearer {access_token}요청 본문 없음.
Path Parameters
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
collabNo | Integer | 예 | 캠페인 번호 |
동작 흐름
- 정책 활성화 확인 (
policyEnabled == true) - 최초 입금액 확인 (없으면 에러)
- 부족분 계산:
needed = max(0, floor(initialDeposit × 0.8) - sumLockedNormal) - 기존 DEFICIT row 있으면 → amount만 재계산하여 저장 (멱등)
- 신규 생성 시 캠페인 예산 풀의 여유분(
totalBudget - sumLocked)이needed이상인지 확인 후 row 생성
응답
성공 응답 (200 OK)
{
"status": 200,
"code": null,
"message": "부족분 lock 완료",
"data": {
"engaged": true,
"amount": 300000,
"status": "LOCKED",
"threshold": 800000,
"sumLockedNormal": 500000,
"policyEnabled": true
}
}자연 사용량이 이미 80%를 충족한 상태에서 호출하면 amount: 0, status: "UNLOCKED"로 row가 생성됩니다(가입 상태만 유지).
응답 필드
부족분 lock 조회 응답과 동일합니다.
에러 응답
| 상태 코드 | 코드 | 설명 |
|---|---|---|
200 (with error code) | POLICY_DISABLED | 캠페인 정책이 비활성화되어 있음 (admin이 OFF 처리) |
200 (with error code) | NO_INITIAL_DEPOSIT | 캠페인에 최초 입금이 없어 기준을 산출할 수 없음 |
200 (with error code) | INSUFFICIENT_CAMPAIGN_BUDGET | 캠페인 예산 풀에 lock할 여유가 없음 (추가 입금 필요) |
401 | — | 인증 실패 |
403 | — | 권한 없음 |
404 | — | 캠페인을 찾을 수 없음 |
본 프로젝트의 에러 응답은 HTTP 상태 200을 유지하며 응답 본문의 code 필드로 구분합니다. 예외 코드 매핑은 백엔드 BudgetExceptionEnum 참조.
사용 예시
curl -X POST "https://api.glowb.com/ai/campaigns/12345/budget/deficit-lock" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"관련 API
참고 사항
- 멱등성: 동일 캠페인에 대해 본 API를 여러 번 호출해도 안전합니다. 두 번째 호출부터는 amount 재계산만 수행하며 새 row를 만들지 않습니다.
- 자금 흐름: 본 API는 기업의 글로벌 크레딧(
remainCredit)에 영향을 주지 않습니다. 캠페인 예산 풀 내부의 reservation만 변경합니다. 정산은 캠페인 완료(refundCampaign) 시점에 일어납니다. - 캠페인 완료 시 DEFICIT이 LOCKED 상태로 남아있으면 환급에서 제외(소진 처리)되며, UNLOCKED 상태면 잔액 환급에 포함됩니다.