API 개발로 파일 변환과 결과 전달 자동화하기

핵심 요약

1. 기존 ERP가 보낸 엑셀을 검증하고 변환 결과를 돌려주는 자동화 프로그램을 만듭니다. 2. FastAPI로 파일을 받고 pandas로 표를 읽으며, BullMQ로 처리 작업의 중복 접수를 줄입니다. 3. 요청번호, 진행조회, 실패 행 설명, 선택 재처리와 ERP 중복 반영 방지는 직접 개발합니다.

ERP에서 내려받은 엑셀을 사람이 고쳐 다시 올린다면, 파일을 주고받는 과정부터 연결할 수 있습니다. API 개발의 핵심은 파일 변환뿐 아니라 어떤 요청이 어디까지 처리됐는지 업무 담당자가 확인하게 만드는 것입니다. 아래는 이러한 프로그램을 제작할 때 필요한 기능과 검수 기준입니다.

FastAPI 파일 접수와 요청번호 발급

ERP가 보내는 파일에는 업무 구분과 원본 전송번호를 함께 받도록 합니다. FastAPI의 UploadFile은 업로드 파일을 받는 기능을 제공합니다. 접수 권한 확인, 허용 파일 형식과 크기 검사, 보관 기간은 업무 조건에 맞춰 별도로 구현합니다.

대용량 파일은 접수와 변환 처리를 나누고, 파일 보관과 처리 대기 등록을 마친 뒤 요청번호를 반환합니다. 담당자는 접수 화면에서 파일명과 요청번호를 확인하고 이후 같은 번호로 진행 상황을 조회합니다. 업로드 도중 연결이 끊긴 파일은 접수 완료로 표시하지 않으며, 다시 보냈을 때 이전 시도와 구분되는지도 검수합니다.

pandas로 엑셀 시트와 필수 항목 확인

개발 자료로는 ‘주문번호·상품코드·수량·납품일’ 열이 있는 실제 주문 엑셀의 익명화 사본을 요청합니다. pandas의 read_excel은 엑셀의 한 개 또는 여러 시트를 DataFrame이라는 표 형태로 읽을 수 있습니다. 어떤 시트를 읽고 어느 줄을 제목으로 볼지는 ERP 파일 규칙에 맞춰 직접 지정합니다.

필수 열 누락, 빈 주문번호, 숫자로 해석할 수 없는 수량을 찾는 검증 규칙은 별도 개발합니다. 상품코드 ‘00125’의 앞자리 0처럼 업무상 의미 있는 표기는 원본과 비교해 확인합니다. 파일 전체를 읽을 수 없는 오류와 특정 행의 오류를 나누면, 담당자가 파일을 다시 준비할지 일부 값만 고칠지 판단할 수 있습니다.

변환 규칙과 진행조회 화면 연결

두 번째 자료는 ERP에 돌려줄 결과 파일 예시와 항목 대응표입니다. 예를 들어 ‘납품일’을 어떤 날짜 표기로 바꾸고, 원본의 ‘상품코드’를 결과의 어느 열에 넣을지 정합니다. 값이 없을 때 기본값을 채울 항목과 반드시 실패로 처리할 항목도 발주 단계에서 구분합니다.

이 대응표에 따라 열 이름 변경, 날짜 표기 통일, 결과 파일 생성을 담당하는 변환 로직을 만듭니다. 진행조회 화면에는 전체 행 수, 처리한 행 수, 성공·실패 건수와 결과 다운로드 버튼을 연결합니다. 결과가 준비되기 전에 다운로드 버튼이 활성화되지 않는지, 성공과 실패 건수의 합계가 원본 처리 대상과 맞는지 확인합니다.

실패한 행 설명과 선택 재처리

오류 목록에는 원본 시트명, 행 번호, 항목명, 실패 이유와 수정 방향을 표시합니다. ‘처리 오류’만 보여주기보다 ‘주문 시트 18행의 수량이 비어 있습니다’처럼 고칠 위치를 알려줍니다. 원본 행과 결과를 연결하는 기록을 남겨야 파일을 정렬하거나 다시 처리해도 오류 설명이 뒤섞이지 않습니다.

검수용으로 18행 수량에 ‘미정’을 넣고, 해당 행이 실패 목록에 나타나는지 확인합니다. 담당자가 수량을 고친 파일을 올려 실패 행을 선택하면, 프로그램은 원래 요청과 대조한 뒤 선택한 대상만 다시 처리하도록 만듭니다. 이미 성공한 행이 바뀌거나 ERP에 다시 반영되지 않는지도 이 실패 사례로 함께 확인합니다.

BullMQ 중복 방지와 ERP 결과 반환

BullMQ의 Simple Mode는 같은 중복 방지 ID를 가진 미완료 작업이 있으면 추가 작업을 무시합니다. 이 기능을 적용할 때는 ERP 전송번호와 업무 구분을 조합해 같은 요청을 판별하는 기준을 직접 정합니다. 실패 행 재처리는 최초 접수와 구분해, 필요한 재실행까지 중복 요청으로 막히지 않도록 합니다.

작업의 중복 접수 방지만으로 외부 ERP의 중복 반영까지 보장되지는 않습니다. ERP가 결과를 받았지만 응답이 끊긴 경우에 대비해, 반환 식별자와 전송 기록을 남기고 수신 여부를 확인한 뒤 재전송하는 절차를 개발합니다. ERP가 이를 확인할 방법을 제공하지 않으면 담당자 확인 단계가 필요하며, 같은 결과를 두 번 보내는 검수에서 업무 데이터가 중복 생성되지 않는지 확인합니다.

주문 엑셀의 익명화 사본과 ERP 결과 파일 예시·항목 대응표를 준비해 트램스에 개발을 문의해 주세요. 예상 파일 크기, 하루 접수량, ERP의 결과 수신 확인 방식까지 알려주시면 API 개발과 자동화 프로그램의 구현 범위를 구체적으로 논의할 수 있습니다.

트램스 AI 제작 문의 (https://trams.co.kr/ai-si/contact/#inquiry)