규제 기관 보고 인터페이스 연동: 필드 매핑, 서명, 수신 확인, 재보고
핵심 요약: 규제 보고에서 어려운 것은 요청을 보내는 일이 아니라 세 가지입니다. 기관마다 메시지 형식이 다르고 계속 바뀌며, 수신 확인은 비동기로 오는 경우가 많고, 보고 누락과 오보고 모두 결과가 따릅니다. 우리는 작업을 세 계층으로 나눕니다. 원천 데이터를 먼저 내부 표준 객체로 바꾼 뒤, 기관별·규격 버전별 메시지를 생성합니다. 공통 전송 계층이 서명, 암호화, 재시도, 수신 확인을 처리합니다. 모든 보고와 수신 확인은 감사 기록으로 남기고, 재보고와 대사 절차도 정해 둡니다.
1.0 ‘형식’과 ‘전송’을 분리한다
흔한 옛 방식은 지역마다 서비스를 하나씩 만들고 필드 매핑, 서명, 전송을 모두 코드에 박아 두는 것입니다. 규격이 바뀔 때마다 배포해야 하고, 지역별 서비스는 제각각 어긋나며, 같은 서명 버그를 여러 번 고치게 됩니다.
더 단단한 구조는 바뀌는 빈도에 따라 계층을 나누는 것입니다.
| 계층 | 역할 | 무엇에 따라 바뀌는가 |
|---|---|---|
| 수집 | 기업 시스템에서 데이터를 가져와 내부 표준 객체로 변환 | 기업 시스템 |
| 매핑 | 표준 객체를 특정 기관·특정 규격 버전의 메시지로 | 규격 버전 |
| 전송 | 인증, 서명, 암호화, 전달, 수신 확인, 재시도 | 거의 바뀌지 않음 |
매핑은 “기관 + 규격 버전” 단위로 관리합니다. 새 버전이 운영에 들어가도 옛 버전은 남겨 두고 시행일에 전환하며, 되돌릴 때는 날짜만 바꾸면 됩니다.
2.0 매핑은 설정으로, 단 테스트할 수 있게
매핑 규칙은 설정으로 작성합니다. 필드 대응, 코드표 변환, 단위 환산, 필수 항목 검증입니다. 구축 담당자는 코드가 아니라 화면에서 관리합니다. 설정도 틀릴 수 있으므로 다음과 같이 합니다.
- 매핑마다 샘플 데이터와 기대 메시지를 두고, 설정을 바꿀 때마다 자동으로 비교한다.
- 코드표(업종 코드, 행정 구역 등)는 별도로 버전을 관리하고 참조할 때 버전을 명시한다.
- 설정 변경에는 승인과 기록을 남겨 누가 언제 무엇을 바꿨는지 추적할 수 있게 한다.
설정으로 표현할 수 없는 경우는 반드시 생깁니다. 이런 예외에는 안정적인 플러그인 인터페이스를 마련하고, 설정 언어가 프로그래밍 언어처럼 불어나지 않게 합니다. 그렇게 되면 구축 담당자는 관리할 수 없고 개발자도 손대기 싫어합니다.
3.0 전송 계층
- 인증서와 키는 읽기 전용으로 마운트하고 데이터베이스에 저장하거나 설정 화면에 표시하지 않습니다. 키 교체는 문서화된 절차를 따릅니다.
- 기관이 요구하는 전송 방식(HTTP, 장기 연결 TCP, 메시지 큐)을 하나의 런타임에서 지원하고, 방식마다 재시도와 로그 체계를 따로 만들지 않습니다.
- 보고마다 고유한 업무 일련번호를 붙이고 재전송할 때도 같은 번호를 써서 기관이 중복을 제거할 수 있게 합니다. 기관이 중복을 제거하지 않으면 재전송 전에 로컬의 ‘확인됨’ 상태를 확인합니다.
- 동기 수신 확인은 보통 “받았다”는 뜻일 뿐입니다. 처리 결과는 비동기 수신 확인으로 오거나 조회해야 하며, 두 경로 모두 필요합니다.
4.0 재시도, 재보고, 대사
| 상황 | 처리 |
|---|---|
| 네트워크 실패, 타임아웃 | 상한이 있는 지수 백오프로 재시도. 상한을 넘으면 수동 처리 큐로 |
| 기관 검증에서 거부 | 자동 재시도하지 않음. 사유를 데이터 책임자에게 전달하고 수정 후 재보고 |
| 시스템 중단 중 누락된 보고 | 시간 구간별로 재보고하고 사유를 기록 |
| 정기적으로 | 기관 측 확인 기록과 대사해 미확인·불일치 항목을 목록화 |
검증 실패를 자동으로 재시도해 봐야 같은 오류가 줄줄이 쌓일 뿐이고, 기관 측 속도 제한에 걸릴 수도 있습니다.
5.0 감사
보고마다 원천 데이터 스냅숏, 생성된 메시지, 서명 요약, 전송 시각, 수신 확인 내용을 보관합니다. 분쟁이 생기면 특정 시점에 무엇을 보고했고 상대가 무엇을 돌려줬는지 보여 줄 수 있어야 합니다. 보관 기간은 기관의 요구와 기업 자체의 컴플라이언스 규정에 따릅니다.
코드에 박힌 옛 보고 서비스를 교체하거나 새 기관과 연결하려면 웹·클라우드·디바이스 관리를 참고하거나 프로젝트 상담으로 연락 주세요.
참고 자료
- Enterprise Integration Patterns, Guaranteed Delivery: https://www.enterpriseintegrationpatterns.com/patterns/messaging/GuaranteedMessaging.html
자주 묻는 질문
지역별 규격이 자주 바뀝니다. 설정만으로 정말 따라갈 수 있나요?
대부분의 변경은 필드 추가, 코드표 갱신, 검증 조정이고 이는 설정으로 처리됩니다. 메시지 구조나 전송 방식까지 바뀌면 매핑 템플릿이나 전송 계층을 고쳐야 합니다. 그래서 매핑을 규격 버전별로 관리하고, 신구 버전을 한동안 병행하다가 시행일에 전환합니다.
기관의 테스트 환경이 운영 환경과 다르게 동작합니다. 어떻게 하나요?
흔한 일입니다. 통합 테스트에서 받은 실제 수신 확인을 마스킹해 샘플로 저장하고, 성공·검증 실패·각 오류 코드를 모두 담습니다. 운영 전환 후에는 대사 빈도를 높여 테스트 환경에서 드러나지 않았던 문제를 빨리 찾습니다.
한 지역부터 시작해도 되나요?
한 지역부터 시작하는 것은 합리적입니다. 다만 구조는 여러 기관을 전제로 설계해서 표준 객체, 매핑 계층, 전송 계층을 분리해 둡니다. 두 번째 지역은 매핑만 추가하면 되고 서비스를 통째로 복제하지 않아도 됩니다.
구축 담당자가 코드를 모릅니다. 매핑을 관리할 수 있나요?
일상적인 필드 대응과 코드표 관리는 화면에서 할 수 있고, 변경할 때마다 샘플 데이터와 자동 비교되어 실수는 곧바로 차이로 드러납니다. 설정으로 표현할 수 없는 예외는 개발자가 플러그인 인터페이스로 구현합니다.