Skip to main content

SHIELDEX File 연동 가이드

SHIELDEX File 무해화 시스템과 연동하는 프로세스를 설명합니다.
연동 방식은 크게 Callback 방식과 Polling 방식 두 가지를 지원합니다.

1. 전체 연동 프로세스​

무해화 연동은 무해화 요청 → 결과 확인 → 파일 다운로드 3단계로 진행됩니다.

Step 1. 무해화 요청​

연동 시스템에서 SHIELDEX 서버로 파일을 전송하여 작업을 등록하고, Job ID를 발급받습니다.

Step 2. 결과 확인​

무해화 작업 완료 여부를 확인합니다. 두 가지 방식 중 하나를 선택할 수 있습니다.

Type A: Callback 수신 (권장)​

서버가 작업 완료 시 연동 시스템으로 결과를 통지합니다.

Type B: 상태 조회 (Polling)​

연동 시스템이 주기적으로 서버에 상태를 질의하여 완료를 확인합니다.

Step 3. 파일 다운로드​

무해화가 성공적으로 완료되면 파일을 다운로드합니다.

2. 연동 방식 선택​

Type A: Callback 방식 (권장)​

무해화 요청 시 callbackURL을 포함하여 보내면, 처리가 완료되는 즉시 해당 URL로 결과를 통지받는 방식입니다.

  • 장점: 불필요한 조회 요청이 없고 실시간성이 보장됩니다.
  • 조건: 연동 시스템 측에 결과를 수신할 수 있는 API 서버가 있어야 합니다.

Type B: Polling 방식​

무해화 요청 후, 주기적으로 상태 조회 API를 호출하여 완료 여부를 확인하는 방식입니다.

  • 장점: 연동 시스템에 별도 수신 서버가 없어도 구현 가능합니다.
  • 주의: 너무 잦은 요청(200ms 미만)은 서버 부하를 유발할 수 있습니다.

3. 단계별 상세 가이드​

Step 1. 무해화 요청 (공통)​

파일과 메타데이터를 multipart/form-data로 전송하여 작업을 등록합니다.

Step 2. 결과 확인​

A. Callback 수신​

요청 시 설정한 URL로 JSON 결과가 도착합니다.

{
    "jobID": "test-job-001",
    "code": 0,
    "msg": "success",
    "logReason": 200000,
    "logReasonMsg": "파일 재구성 완료"
}

B. 상태 조회 (Polling)​

작업이 완료(code: 0, 1, 2)될 때까지 API를 주기적으로 호출합니다.

Step 3. 파일 다운로드​

결과 확인 단계에서 code: 0(성공) 또는 code: 1(예외/원본반입)인 경우 파일을 다운로드합니다.

4. 연동 시 주의사항​

  1. UTF-8 인코딩: 모든 요청의 문자셋은 UTF-8을 준수해야 합니다.
  2. 다운로드 시점: 상태 조회 API 응답이 완료(code: 0, 1) 상태일 때만 다운로드를 요청해야 합니다.