# 06. API And Integration Plan

## 1. 연동 원칙

- 외부 시스템 결과를 단일 성공/실패로 단순화하지 않는다.
- 기부/결제/영수증 계열 요청은 반드시 중복 방지 키를 사용한다.
- 외부 장애는 사용자에게 명확히 보여주되 내부 재시도 상태를 보존한다.
- 법령상 검증 결과는 프론트 계산보다 e음 또는 공식 검증 응답을 우선한다.

## 2. 고향사랑e음 연동 경계

확정 필요 영역:

| 영역 | 필요 기능 | 우리 시스템 역할 |
|---|---|---|
| 본인확인 | 기부자 식별 | 인증 결과 저장, 만료 관리 |
| 주소지 검증 | 기부 가능 지자체 판정 | 사전 안내 + 최종 검증 결과 반영 |
| 연간 한도 | 누적 기부액 확인 | 입력 금액 제한, 실패 처리 |
| 기부 접수 | 일반/지정기부 접수 | 요청 생성, 상태 관리 |
| 영수증/세액공제 | 접수 결과/영수증 | 마이페이지 표시, 재동기화 |
| 답례품/포인트 | 기부 포인트 생성 | 지역별 포인트 표시/사용 연결 |

## 3. 연동 상태 모델

```text
not_started
request_created
submitted
pending
confirmed
failed_retryable
failed_final
cancelled
reconciled
```

## 4. 기부 요청 시퀀스

```text
Client
  -> API: create donation intent
API
  -> validate local input
  -> create Donation(status=started, idempotency_key)
Client
  -> auth/identity verification
API
  -> request address/limit validation
Eum Adapter
  -> submit validation
API
  -> update status
Client
  -> payment/donation confirmation
API
  -> submit donation to Eum
Eum Adapter
  -> receive receipt/status
API
  -> create DonationPoint if applicable
Client
  -> completion page
```

## 5. 장애 처리

| 상황 | 사용자 안내 | 내부 처리 |
|---|---|---|
| e음 검증 지연 | "검증이 지연되고 있습니다. 완료되면 알림을 보내드립니다." | pending 상태, polling/job 재시도 |
| e음 검증 실패 | 실패 사유 표시, 재시도/문의 | failed_retryable 또는 failed_final |
| 기부 접수 중복 | 기존 접수 상태 표시 | idempotency_key로 중복 차단 |
| 영수증 동기화 실패 | 기부 완료, 영수증 준비 중 | reconciliation job |
| 답례품 품절 | 포인트 유지, 대체품 제안 | stock refresh, CS task |

## 6. 결제/정산

확정 필요:

- 기부금 납부가 PG를 직접 경유하는지, e음/공공 경유인지.
- 예약/스토어 결제와 기부금 납부의 회계 계정 분리.
- 공급자 정산과 지자체/플랫폼 수수료 정산의 분리.
- 환불/취소 가능 범위와 e음 상태 역전파 방식.

권장 설계:

```text
PaymentIntent
  ├ payment_type: reservation/order/donation
  ├ amount
  ├ provider
  ├ external_transaction_id
  ├ status
  └ idempotency_key

Settlement
  ├ target_type: supplier/local_gov/platform
  ├ gross_amount
  ├ fee_amount
  ├ net_amount
  ├ status
  └ period
```

## 7. 지도/주소/배송

필요 연동:

- 주소 검색: 도로명주소 API.
- 지도: 카카오/네이버/구글 중 정책 결정.
- 배송 추적: 택배사 또는 배송조회 통합 API.
- 본인확인: PASS/나이스/카카오 인증 등 실제 계약에 따라 결정.

## 8. 추천/AI

AI는 법령 판정자가 아니다. AI는 추천 이유와 콘텐츠 초안을 돕고, 금액/공제/기부 가능 여부는 deterministic service가 계산한다.

```text
Recommendation Service
  -> reads user preferences, region tags, catalog tags, campaign tags
  -> returns ranked bundles

TaxBenefit Calculator
  -> deterministic rules
  -> versioned by effective date
```

## 9. 로그/모니터링

필수 로그:

- e음 request/response correlation id.
- donation idempotency key.
- validation failure reason.
- user-facing error code.
- admin retry actor.
- reconciliation result.

지표:

- e음 검증 성공률.
- 평균 검증 시간.
- failed_retryable 누적 건수.
- reconciliation 미완료 건수.
- 기부 완료 후 포인트 생성 지연 시간.