행안부 고향사랑e음 연동 명세

🔒 IPsec VPN 전용 터널망 연동 규격 🌐 KLID(한국지역정보개발원) 중계 API 연동 규격 ⚙️ 실시간 적격성 판단 및 기부 원장 수납 처리

본 문서에서는 행정안전부 고향사랑e음의 민간 연계 플랫폼 API 기술 표준 명세를 다룹니다. VPN 하이브리드 보안 인프라 요건 및 실시간 원장 동기화에 필수적인 전문 구조를 규정합니다.

1. IPsec VPN 보안 인프라 요건

기부 수납 정보 및 개인정보 유출 방지를 위해 플랫폼 백엔드 서버와 KLID 중계 Gateway 간 AES-256 IPsec VPN 전용 암호화 터널을 개통합니다. 모든 API 요청 헤더에는 HMAC-SHA256 기반 서명 토큰(`X-Signature`) 첨부가 의무화됩니다.

2. e음 연동 주요 API 명세

📄 [EUM-API-01] 거주지 & 한도 실시간 조회

기부 진입 단계에서 사용자의 PASS인증 CI값과 기부 대상 지자체 코드를 전송해 적격 판정 여부 및 연간 잔여 기부 한도를 체크합니다.

POST /gateway/v1/limit/check
Request: {
  "userCi": "CI_STRING...",
  "targetGovCode": "4571000000"
}
Response (HTTP 200): {
  "isEligible": "Y",
  "remainingLimit": 19500000
}

📄 [EUM-API-02] 기부 수납 및 원장 등록

결제 완료 시점 혹은 Saga 오케스트레이터의 기부 확정 트랜잭션 단계에서 행안부 원장에 최종 수납을 승인 요청합니다.

POST /gateway/v1/donation/apply
Request: {
  "userCi": "CI_STRING...",
  "targetGovCode": "4571000000",
  "donationAmount": 100000
}
Response (HTTP 200): {
  "eumApprovalNo": "EUM_APP_2026_900124",
  "taxReceiptReceiptNo": "REC_2026..."
}