동기/비동기 처리 API 플로우
00.integration_guide.md를 기반으로, SHIELDEX File 무해화(CDR) 연동 시 비동기/동기 처리 플로우를 정리합니다.
- 비동기 플로우: 무해화 요청 → 상태조회(또는 Callback) → 다운로드
- 동기 플로우: 무해화 요청 → 다운로드 (SHIELDEX 서버가 내부적으로 상태조회를 반복하여 완료 시점에 결과를 응답)
1. 비동기 처리 플로우 (Async)
비동기 플로우는 서버가 작업을 큐에 등록하고 즉시 Job ID를 반환하며, 연동 시스템이 이후에 결과를 확인한 뒤 다운로드합니다.
2. 동기 처리 플로우 (Sync)
동기 처리 플로우는 SHIELDEX 서버가 외부로는 “동기 API”처럼 동작하도록 구성된 경우를 의미합니다.
서버는 내부적으로 기존 비동기 API(POST /v5/cdr, GET /v5/cdr/{jobID})를 자신에게 호출하여 완료 시점에 무해화 결과만 반환합니다.
호출자는 결과에 포함된 jobID로 다운로드 API를 별도로 호출합니다.
3. 구현 시 주의사항
- 상태 조회 주기: 상태 조회를 너무 잦게 호출(예: 루프에서 즉시 연속 호출)하면 서버 부하/차단의 원인이 될 수 있습니다. (200ms 간격 권장)
- 다운로드 조건: 상태 조회 결과가
code: 0(성공) 또는code: 1(예외/원본반입) 인 경우에만 다운로드를 요청해야 합니다. (code: 2차단은 다운로드 불가) - 동기 처리 타임아웃: 동기 플로우(서버 내부 폴링) 구성 시 무한 대기를 방지하기 위해 최대 대기 시간과 재시도 제한을 두어야 합니다.