용어 및 상태값 정리

Adit 서비스에서 사용하는 용어, 데이터 구조, 상태값을 정리했습니다.

참여자

참여자	설명	시스템
광고주 (Advertiser)	캠페인을 의뢰하고 비용을 지불	광고주 프론트
파트너 (Partner)	콘텐츠를 제작/업로드하고 정산금 수령	파트너 콘솔
대행사 (Agency)	정산을 중개하는 주체 (Adit, 미드나잇웨이브 등)	어드민
채널 (Channel)	파트너가 운영하는 SNS 계정	파트너 콘솔

데이터 관계도

전체 구조

┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│  Advertiser │         │   Partner   │         │   Agency    │
│   (광고주)   │         │   (파트너)   │         │   (대행사)   │
└──────┬──────┘         └──────┬──────┘         └──────┬──────┘
       │                       │                       │
       │                       ▼                       │
       │               ┌─────────────┐                 │
       │               │   Channel   │                 │
       │               │   (채널)    │                 │
       │               └──────┬──────┘                 │
       │                      │                        │
       ▼                      ▼                        ▼
┌────────────────────────────────────────────────────────────┐
│                         Campaign                            │
│                          (캠페인)                           │
│  • advertiserId, partnerId, channelId                       │
│  • agencyId (정산 주체)                                      │
│  • settlementType (ADIT_SETTLEMENT / DIRECT_INVOICE)        │
│  • commissionRate (캠페인별 수수료 오버라이드)                  │
└─────────────────────────────┬──────────────────────────────┘
                              │
                              │ 1:1 (업로드 완료 시 자동 생성)
                              ▼
┌────────────────────────────────────────────────────────────┐
│                        Settlement                           │
│                          (정산)                             │
│  • campaignId (1:1)                                         │
│  • commissionRate, withholdingTaxRate, payoutAmount          │
│  • advertiserInvoiceId (N:1) - 청구서 연결                   │
│  • partnerPayoutId (N:1) - 지급 연결                         │
└────────────┬───────────────────────────────┬───────────────┘
             │                               │
             ▼                               ▼
┌────────────────────────┐       ┌────────────────────────┐
│   AdvertiserInvoice    │       │     PartnerPayout      │
│    (광고주 청구서)      │       │     (파트너 지급)       │
│  • 건별 또는 월별 합산  │       │  • 건별 또는 월별 합산   │
└────────────────────────┘       └────────────────────────┘

정산 3계층 구조

계층	모델	설명	관계
1계층	Settlement	캠페인 단위 정산 레코드	캠페인 1건 = 정산 1건
2계층-A	AdvertiserInvoice	광고주에게 발행하는 청구서	건별: 1:1 / 월별: N:1
2계층-B	PartnerPayout	파트너에게 지급하는 배치	건별: 1:1 / 월별: N:1

견적서 (Quotation)

채널/상품 조합으로 구성된 견적서입니다. 실행(Execute)하면 캠페인이 일괄 생성됩니다.

필드	설명
`quoId`	견적서 고유 ID (예: QUO001)
`advertiserId`	광고주 (선택)
`items`	견적 항목 배열 (JSON): 채널, 상품, 수량
`totalAmount`	총 금액
`status`	견적서 상태 (QuotationStatus)
`executedAt`	실행(캠페인 생성) 일시

견적서 상태 (QuotationStatus)

상태	코드	설명
📝 초안	`DRAFT`	수정/삭제 가능
📤 발송됨	`SENT`	광고주에게 전달됨
✅ 실행됨	`EXECUTED`	캠페인 생성 완료 (종료 상태)
❌ 취소됨	`CANCELLED`	소프트 삭제 (종료 상태)

사업자 검증 (NTS)

국세청 API를 통한 사업자등록정보 검증입니다.

기능	설명
상태조회	사업자번호만으로 휴/폐업 상태, 과세유형 확인
진위확인	사업자번호 + 개업일자 + 대표자명 → NTS 기록 일치 여부

API: POST /api/public/business/verify (인증 불필요)
가입/온보딩/설정 변경 시 사업자번호 실시간 검증
Rate limit: 15분당 IP당 30회

Bolta 세금계산서

BoltaCustomer (볼타 고객)

Bolta API 연동을 위한 발행 주체 등록 정보입니다.

필드	설명
`boltaCustomerId`	Bolta에서 발급한 고객 ID
`agencyId`	소속 대행사 (null = Adit 본사)
`businessNumber`	사업자등록번호
`certificateExpiresAt`	공동인증서 만료일

BoltaIssuance (정발행 추적)

광고주에게 발행하는 세금계산서 추적 레코드입니다.

필드	설명
`settlementId`	연결된 정산 ID
`issuanceKey`	Bolta 발행 키
`status`	PENDING / SUCCESS / FAILURE / CANCELLED
`invoiceNumber`	세금계산서 번호 (성공 시)
`failureMessage`	실패 사유

BoltaReverseIssuance (역발행 추적)

파트너(법인)가 Adit/대행사에게 발행하는 세금계산서 추적 레코드입니다.

필드	설명
`settlementId`	연결된 정산 ID
`issuanceKey`	Bolta 발행 키
`status`	PENDING / SUCCESS / FAILURE / CANCELLED
`grantUrl`	역발행 승인 URL (10분 유효)

캠페인 상태 (CampaignStatus)

상태	코드	설명
🟠 광고주 대기	`PENDING_ADVERTISER`	광고주가 등록, 파트너 검토 전
🟡 대기	`PENDING`	파트너/어드민 확정 대기
🟢 확정	`CONFIRMED`	캠페인 확정, 진행 예정
🔵 진행 중	`IN_PROGRESS`	콘텐츠 제작/업로드 기간
✅ 업로드 완료	`UPLOADED`	콘텐츠 업로드됨, 정산 대기
💰 완료	`COMPLETED`	정산까지 모두 완료
⛔ 거절	`REJECTED`	파트너가 거절
🔴 취소	`CANCELLED`	캠페인 취소

상태 전이 다이어그램

PENDING_ADVERTISER ──→ PENDING ──┬──→ CONFIRMED ──→ IN_PROGRESS ──→ UPLOADED ──→ COMPLETED
                                 │         │              │
                                 │         ▼              ▼
                                 │    CANCELLED      CANCELLED
                                 │
                                 └──→ REJECTED

사용자별 상태 변경 권한

현재 상태	가능한 액션
PENDING	취소 (삭제)
그 외	액션 없음 (조회만)

광고주는 PENDING 상태에서만 캠페인을 취소(삭제)할 수 있습니다.

정산 상태 (SettlementStatus)

상태	코드	설명
🕐 정산 대기	`SETTLEMENT_PENDING`	파트너 정산 요청 전
📤 결제 대기	`AWAITING_ADVERTISER_PAYMENT`	파트너가 정산 요청함, 광고주 입금 대기
✅ 결제 완료	`ADVERTISER_PAID`	광고주 입금 확인됨
🔄 지급 처리 중	`PARTNER_PAYOUT_PROCESSING`	파트너 지급 처리 중
💰 정산 완료	`SETTLEMENT_COMPLETED`	파트너 송금 완료
❌ 정산 취소	`SETTLEMENT_CANCELLED`	정산 취소

정산 방식별 플로우

ADIT_SETTLEMENT - Adit/대행사가 중개

SETTLEMENT_PENDING (정산 대기)
      │
      │ [파트너] 정산 요청
      ▼
AWAITING_ADVERTISER_PAYMENT (결제 대기)
      │
      │ [어드민] 세금계산서 발급 → 광고주에게 발송
      │ [어드민] 입금 확인
      ▼
ADVERTISER_PAID (결제 완료)
      │
      │ [어드민] 파트너 지급 시작
      ▼
PARTNER_PAYOUT_PROCESSING (지급 처리 중)
      │
      │ [어드민] 정산 완료
      ▼
SETTLEMENT_COMPLETED (정산 완료)
      │
      └─→ 캠페인 상태도 COMPLETED로 변경

청구서 상태 (InvoiceStatus)

광고주에게 발행하는 청구서 상태입니다.

상태	코드	설명
📝 초안	`DRAFT`	청구서 생성됨, 세금계산서 미발행
📤 발행됨	`ISSUED`	세금계산서 발행됨, 입금 대기
✅ 입금 완료	`PAID`	광고주 입금 확인됨
⚠️ 연체	`OVERDUE`	납기일 초과
❌ 취소	`CANCELLED`	청구서 취소

지급 상태 (PayoutStatus)

파트너에게 송금하는 지급 상태입니다.

상태	코드	설명
🕐 대기	`PENDING`	지급 배치 생성됨, 세금계산서 미수령
📥 세금계산서 수령	`INVOICE_RECEIVED`	파트너 세금계산서 수령 확인
🔄 처리 중	`PROCESSING`	송금 처리 중
✅ 완료	`COMPLETED`	송금 완료
❌ 취소	`CANCELLED`	지급 취소

정산 유형 (SettlementType)

유형	코드	설명	수수료	원천징수
Adit 정산	`ADIT_SETTLEMENT`	광고주 → 대행사 → 파트너	있음 (기본 20%)	개인 3.3%
매체사 직정산	`DIRECT_INVOICE`	광고주 → 파트너 직접	없음 (0%)	없음 (0%)

어드민이 정산 유형을 변경할 수 있습니다. 변경 시 수수료/원천징수가 재계산되며 상태가 초기화됩니다.

청구/지급 유형

유형	코드	설명
건별	`PER_CAMPAIGN`	캠페인 1건 = 청구서/지급 1건
월별	`MONTHLY`	여러 캠페인 합산하여 청구/지급

💡

현재는 건별 정산만 지원됩니다. 월별 정산은 추후 지원 예정입니다.

슬롯 (PartnerSlot)

파트너의 날짜별 캠페인 예약 가능 여부를 관리합니다.

필드	설명	기본값
`date`	날짜	-
`isAvailable`	예약 가능 여부	true
`maxCampaigns`	최대 캠페인 수 (0=무제한)	0
`currentCampaigns`	현재 예약된 캠페인 수	0

슬롯 카운트 변화

시점	변화
캠페인 생성	+1
캠페인 업로드 완료	-1
캠페인 완료	-1
캠페인 취소	-1
캠페인 거절	-1

슬롯 반환은 최초 1회만 발생합니다 (중복 반환 방지).

금액 계산

수수료 기본값

항목	기본값	비고
Adit 정산 수수료율	20%	파트너별/캠페인별 설정 가능
직정산 수수료율	0%	고정
원천징수율 (개인+ADIT)	3.3%	하드코딩

수수료율 적용 우선순위

Campaign.commissionRate (캠페인별)
Partner.commissionRate (파트너 기본)
시스템 기본값 20%

정산금 계산 (ADIT 정산)

수수료 금액 = 캠페인 가격 × 수수료율
정산금 (공급가액) = 캠페인 가격 - 수수료 금액
원천징수 = 정산금 × 원천징수율 (개인사업자 3.3%, 법인 0%)
실지급액 = 정산금 - 원천징수

예시 (캠페인 100만원, 수수료 20%, 개인사업자):

항목	금액
캠페인 가격	1,000,000원
수수료 (20%)	200,000원
정산금	800,000원
원천징수 (3.3%)	26,400원
실지급액 (payoutAmount)	773,600원

예시 (캠페인 100만원, 수수료 20%, 법인사업자):

항목	금액
캠페인 가격	1,000,000원
수수료 (20%)	200,000원
정산금	800,000원
원천징수 (0%)	0원
실지급액 (payoutAmount)	800,000원

매체사 직정산

수수료/원천징수 모두 0%이므로 캠페인 가격 전액이 실지급액입니다.

주요 필드 설명

Campaign

필드	설명
`settlementType`	정산 유형 (ADIT_SETTLEMENT / DIRECT_INVOICE)
`commissionRate`	캠페인별 수수료율 (null이면 파트너 기본값 사용)
`agencyId`	담당 대행사 ID (ADIT 정산 시 정산 주체)
`uploadDate`	업로드 예정일
`status`	캠페인 상태

Settlement

필드	설명
`campaignPrice`	캠페인 가격 (스냅샷)
`commissionRate`	수수료율 (%)
`commissionAmount`	수수료 금액
`settlementAmount`	정산금 (캠페인가격 - 수수료)
`withholdingTaxRate`	원천징수율 (개인+ADIT: 3.3%, 그 외: 0)
`withholdingTaxAmount`	원천징수 금액
`payoutAmount`	실지급액 (정산금 - 원천징수)
`requestedAt`	정산 요청 일시
`completedAt`	정산 완료 일시
`invoiceIssuedAt`	세금계산서 발급일 (DIRECT_INVOICE)
`invoicePaidAt`	입금 확인일 (DIRECT_INVOICE)
`partnerInvoiceReceivedAt`	Bolta 역발행 수령 확인일

상태 이모지 빠른 참조

캠페인

🟠	🟡	🟢	🔵	✅	💰	⛔	🔴
광고주대기	대기	확정	진행중	업로드완료	완료	거절	취소

정산

🕐	📤	✅	🔄	💰	❌
정산대기	결제대기	결제완료	지급처리중	정산완료	취소

홈 캠페인 진행 흐름