IDoc Adapter 없이 S/4HANA 연동 실패 3가지 #shorts #SAP #BTP

개요: 왜 "그냥 HTTP로 쏘면 되지"가 실패로 끝나는가

가상의 유통사 '한빛리테일'이 물류센터 출하 정보를 SAP S/4HANA로 전송하는 프로젝트를 상상해 봅시다. 개발팀은 "IDoc도 결국 XML이니까 HTTP Adapter로 엔드포인트에 POST하면 끝"이라고 판단했고, 오픈 2주 만에 출하 IDoc 3,000건이 유실되는 사고를 겪습니다. 이 글은 SAP Integration Suite(Cloud Integration)에서 S/4HANA 연동 시 전용 Adapter(IDoc Adapter, RFC Adapter 등)와 범용 HTTP Adapter의 구성 차이, 그리고 HTTP Adapter만으로 구성했을 때 발생하는 구체적인 실패 지점을 다룹니다.

IDoc Adapter와 HTTP Adapter의 프로토콜 처리 방식 차이 이해
인증(CSRF, Principal Propagation)에서 갈리는 실패 지점 파악
출하 IDoc 연동 iFlow를 3단계로 직접 구성
재처리(JMS 큐)와 에러 핸들링까지 포함한 프로덕션 구성 완성

이 글을 읽기 전에 알아두면 좋은 것

SAP BTP Integration Suite에서 iFlow를 한 번이라도 만들어 본 경험, IDoc이 Control Record(제어 레코드)와 Data Record(세그먼트)로 구성된다는 기본 구조, 그리고 Cloud Connector가 온프레미스 시스템과 BTP를 잇는 터널 역할을 한다는 정도의 이해가 있으면 충분합니다. Groovy 스크립트는 짧은 예제만 등장하므로 깊은 지식은 필요 없습니다.

테스트 환경

이 글의 예제는 다음 환경을 기준으로 합니다.

SAP Integration Suite (Cloud Integration capability, BTP Cloud Foundry 환경, 2025~2026 시점 릴리스 기준)
SAP S/4HANA 2023 온프레미스 (Private Cloud Edition에서도 동일하게 적용 가능)
SAP Cloud Connector 2.16 이상 — 온프레미스 S/4HANA 연결용
S/4HANA 측 준비: 파트너 프로파일(WE20), 포트(WE21), IDoc 수신용 서비스 활성화(SICF)
Integration Suite 측 준비: Process Integration Runtime 서비스 인스턴스, JMS 리소스(Enterprise Edition 또는 별도 자원 할당)

일반적으로 IDoc Adapter는 Cloud Integration의 표준 수신/발신 어댑터로 제공되며, 별도 라이선스 없이 사용할 수 있습니다.

핵심 개념: 전용 Adapter는 '통역사', HTTP Adapter는 '전화선'

비유하자면 HTTP Adapter는 전화선만 연결해 주는 통신사입니다. 상대방이 어떤 언어를 쓰는지, 말이 끊기면 어떻게 다시 이어야 하는지는 전혀 관여하지 않습니다. 반면 IDoc Adapter나 RFC Adapter 같은 S/4HANA 전용 어댑터는 통역사까지 동석시키는 것과 같습니다. 프로토콜 세부 사항을 어댑터가 흡수해 주기 때문입니다.

구체적으로 두 방식은 다음 네 가지 층위에서 갈립니다.

층위	IDoc Adapter (전용)	HTTP Adapter (범용)
프로토콜	IDoc-XML over SOAP를 어댑터가 자동 래핑	SOAP Envelope, 네임스페이스를 직접 구성해야 함
인증	Basic/클라이언트 인증서/Principal Propagation 선택형	CSRF 토큰 페치, 세션 쿠키 관리를 직접 구현
신뢰성	EOIO(Exactly Once In Order) 품질 옵션, IDoc 번호 회신	재전송 시 중복 수신 — 멱등성 보장 없음
모니터링	SAP 측 IDoc 번호가 메시지 헤더로 반환되어 추적 가능	HTTP 200만 확인 가능, S/4HANA 내부 상태와 단절

가장 치명적인 부분은 신뢰성 층위입니다. IDoc은 원래 tRFC 기반의 '정확히 한 번' 전달 철학 위에 설계된 메시지입니다. HTTP Adapter로 이 철학을 우회하면, 네트워크 타임아웃 시 "전송이 됐는지 안 됐는지 모르는 상태"가 발생하고, 재전송하면 출하 IDoc이 이중 처리되어 재고가 두 번 차감되는 식의 업무 사고로 이어집니다. 한빛리테일 사례에서 유실된 3,000건도 결국 타임아웃 후 응답 코드만 보고 실패로 간주해 폐기한 케이스였습니다.

실전 예제: 출하 통지 IDoc 연동 3단계

시나리오를 정의합니다. 한빛리테일의 물류센터 시스템(WMS)이 출하 완료 시 JSON을 Integration Suite로 보내면, iFlow가 이를 커스텀 IDoc ZOUTBDLV01(메시지 타입 ZSHIP_NOTICE)로 변환해 S/4HANA에 전달합니다.

1단계 — 기본 iFlow: IDoc Receiver Adapter 연결

먼저 Cloud Connector에 S/4HANA 시스템을 가상 호스트 s4prod-virtual:44300으로 등록하고, SICF에서 IDoc SOAP 서비스가 활성화되어 있는지 확인합니다. iFlow의 Receiver 채널에 IDoc Adapter를 선택하고 다음과 같이 설정합니다.

# IDoc Receiver Adapter 주요 설정
Address: https://s4prod-virtual:44300/sap/bc/srt/idoc?sap-client=300
Proxy Type: On-Premise            # Cloud Connector 경유
Location ID: HANBIT-DC1           # Cloud Connector에 지정한 Location
Authentication: Basic
Credential Name: S4_IDOC_COMM_USER  # Security Material에 등록한 자격 증명
IDoc Content Type: Application/x-sap.doc

매핑 후 어댑터로 넘기는 IDoc-XML 페이로드는 다음 구조입니다. Control Record의 필수 필드는 어댑터가 아닌 매핑 단계에서 채웁니다.

<ZOUTBDLV01>
  <IDOC BEGIN="1">
    <EDI_DC40 SEGMENT="1">
      <IDOCTYP>ZOUTBDLV01</IDOCTYP>
      <MESTYP>ZSHIP_NOTICE</MESTYP>
      <SNDPRT>LS</SNDPRT>
      <SNDPRN>HANBIT_WMS</SNDPRN>
      <RCVPRT>LS</RCVPRT>
      <RCVPRN>S4PRODCLNT300</RCVPRN>
    </EDI_DC40>
    <ZE1SHPHDR SEGMENT="1">
      <SHIP_NO>DC1-20260814-0042</SHIP_NO>
      <WAREHOUSE>DC01</WAREHOUSE>
      <CARRIER_CD>HBEXP</CARRIER_CD>
      <ZE1SHPITM SEGMENT="1">
        <ITEM_NO>000010</ITEM_NO>
        <SKU>HB-TUMBLER-500</SKU>
        <QTY_SHIPPED>120</QTY_SHIPPED>
      </ZE1SHPITM>
    </ZE1SHPHDR>
  </IDOC>
</ZOUTBDLV01>

같은 작업을 HTTP Adapter로 하려면 위 XML을 SOAP Envelope로 감싸고, CSRF 토큰을 먼저 GET으로 받아온 뒤 쿠키와 함께 POST해야 합니다. 이 왕복 로직을 직접 짜는 순간부터 실패 확률이 누적되기 시작합니다.

2단계 — 실무 시나리오: 에러 분기와 로깅 추가

IDoc Adapter는 전송 성공 시 S/4HANA가 발번한 IDoc 번호를 SapIDocDbId 계열 헤더로 돌려줍니다. 이를 로깅해 두면 장애 시 WE02 화면과 즉시 대조할 수 있습니다. Exception Subprocess와 함께 Groovy 스크립트를 배치합니다.

import com.sap.gateway.ip.core.customdev.util.Message

def Message logIdocResult(Message message) {
    def msgLog = messageLogFactory.getMessageLog(message)
    def shipNo = message.getHeaders().get("HanbitShipNo") ?: "UNKNOWN"
    def idocNum = message.getHeaders().get("SapIDocDbId") ?: "N/A"

    msgLog?.addAttachmentAsString(
        "IDocResult_" + shipNo,
        "shipNo=" + shipNo + ", idocNumber=" + idocNum,
        "text/plain")
    // 커스텀 헤더 상태 기록 — 모니터링 검색용
    message.setProperty("SAP_MessageProcessingLogCustomStatus",
        idocNum == "N/A" ? "SHIP_FAILED" : "SHIP_SENT")
    return message
}

Exception Subprocess에서는 실패 페이로드를 Data Store에 ShipNotice_Failed 이름으로 Write하고, 운영팀 알림용 메일 어댑터로 분기합니다. HTTP Adapter 구성이라면 이 지점에서 "HTTP 500이지만 실제로는 IDoc이 51 상태로 생성된" 애매한 케이스를 구분할 방법이 없습니다. IDoc Adapter는 전송 계층 실패와 애플리케이션 계층 실패를 명확히 분리해 줍니다.

3단계 — 프로덕션: JMS 큐 기반 재처리와 보안 강화

프로덕션에서는 iFlow를 둘로 나눕니다. 수신 iFlow는 WMS의 JSON을 받아 검증 후 JMS 큐 Q_SHIP_NOTICE에 적재만 하고 즉시 202를 반환합니다. 발신 iFlow가 큐를 폴링해 IDoc으로 전송합니다.

# JMS Sender 채널 (발신 iFlow)
Queue Name: Q_SHIP_NOTICE
Number of Concurrent Processes: 1     # 출하 순서 보장을 위해 단일 처리
Retry Interval (min): 3
Exponential Backoff: true
Max Retry Interval (min): 60
Dead-Letter Queue: 활성화             # 반복 실패 건 격리

이 구조에서 S/4HANA가 점검으로 내려가도 메시지는 큐에서 3분 → 6분 → 12분 간격으로 자동 재시도되며, 순서(EOIO 성격)도 유지됩니다. 보안 측면에서는 Basic 인증 대신 Cloud Connector의 Principal Propagation 또는 클라이언트 인증서 인증으로 전환하는 것이 권장됩니다. IDoc Adapter는 채널 설정에서 인증 방식만 바꾸면 되지만, HTTP Adapter는 인증서 체인과 세션 갱신 로직을 다시 검증해야 합니다. 테스트는 부하 상황을 가정해 큐에 500건을 적재한 뒤 S/4HANA를 의도적으로 차단하고, 복구 후 전량이 상태 53(정상 처리)으로 수렴하는지 WE02에서 확인하는 방식으로 진행합니다.

삽질 노트

Q1. HTTP Adapter로 보냈더니 403 Forbidden이 반환됩니다.

대부분 CSRF 토큰 누락입니다. S/4HANA의 상태 변경 요청은 일반적으로 X-CSRF-Token: Fetch로 토큰을 먼저 받고, 발급된 세션 쿠키와 토큰을 함께 보내야 합니다. IDoc Adapter는 이 과정 자체가 필요 없는 방식으로 통신하므로, 403이 반복된다면 어댑터 교체가 가장 빠른 해결책입니다.

Q2. IDoc Adapter로 전송은 성공했는데 S/4HANA에서 IDoc이 상태 56(수신 오류)입니다.

Control Record의 파트너 정보(SNDPRN, RCVPRN)가 WE20 파트너 프로파일과 일치하지 않는 경우입니다. 네트워크 문제가 아니라 매핑 문제이므로, 매핑 단계에서 파트너 값을 Externalized Parameter로 빼서 환경별(개발/운영)로 관리하는 것이 좋습니다.

Q3. Cloud Connector 경유 연결에서 "Opening provider connection failed"가 발생합니다.

iFlow 채널의 Location ID와 Cloud Connector에 설정한 Location ID 불일치가 가장 흔한 원인입니다. 둘 다 비어 있거나 둘 다 같은 값이어야 하며, 가상 호스트의 접근 제어 목록에 /sap/bc/srt/idoc 경로가 허용되어 있는지도 확인해야 합니다.

Q4. 같은 출하 건이 두 번 처리됐습니다.

HTTP 타임아웃 후 무조건 재전송하는 로직이 원인일 가능성이 큽니다. JMS 재시도와 IDoc Adapter 조합으로 전환하고, S/4HANA 수신 펑션에서 SHIP_NO 기준 중복 검사를 추가하는 이중 방어가 일반적인 해법입니다.

더 파볼 주제

이 예제를 소화했다면 다음 주제로 확장해 보세요. 첫째, S/4HANA에서 BTP로 나가는 방향의 IDoc Sender Adapter 구성(WE21 XML HTTP 포트 설정 포함). 둘째, IDoc 대신 OData V4 Adapter로 릴리스된 API를 호출하는 API 우선 접근과의 비교 — 신규 구축이라면 일반적으로 OData/SOAP API가 우선 검토 대상입니다. 셋째, Exception Subprocess에서 격리한 실패 건을 재주입하는 재처리 iFlow 설계. 넷째, Edge Integration Cell을 활용해 IDoc 트래픽을 온프레미스 경계 안에서 처리하는 하이브리드 배포 구성입니다.

댓글 0