ERP와 주문 연동하기: 수동 검토, 멱등 전송, 동기화 로그
핵심 요약: ERP 연동에서 가장 흔한 오해는 “ERP가 주문을 받았다”를 “주문이 성공했다”와 같게 보는 것입니다. 많은 ERP는 주문을 받은 뒤에도 사람이 검토하고 그다음에 출고를 전기하며, 플랫폼은 기다릴 수밖에 없습니다. 우리는 전송마다 안정적인 업무 키를 붙여 안전하게 재시도할 수 있게 하고, 상태는 한 번의 응답을 믿지 않고 주기적으로 조회해서 확인하며, 모든 동기화 동작을 동기화 로그에 기록하고, 매일 대사를 돌려 양쪽이 어긋난 전표를 찾습니다.
1.0 먼저 업무 흐름을 그린다
연동 코드를 한 줄 쓰기 전에 ERP 구축 담당, 업무 담당과 함께 주문부터 송장까지 모든 단계를 적습니다. 각 단계가 어느 쪽에서 일어나는지, 자동인지 수동인지도 표시합니다. 전형적인 흐름은 고객 등록, 주문 전송, ERP 검토, 출고 전기, 배송과 운송장 번호, 입금 확인, 송장 가져오기입니다.
수동 단계를 표시하는 것이 중요합니다. 플랫폼에서 ‘처리 중’으로 보이는 주문은 ERP 안 누군가의 할 일 목록에 머물러 있을 수 있고, 아무리 재시도해도 움직이지 않습니다. 화면과 알림이 “ERP를 기다리는 중”과 “전송 실패”를 구분하지 않으면, 운영팀은 두 종류의 문제를 모두 개발자에게 가져옵니다.
2.0 전송은 안전하게 재시도할 수 있어야 한다
가장 까다로운 것은 타임아웃입니다. 요청이 도착했는지 아닌지 알 수 없습니다. 재시도할 때 ERP가 전표를 하나 더 만들면 중복 주문이 됩니다.
- 전표마다 안정적인 업무 키(보통 플랫폼 주문 번호)를 붙이고, ERP는 그 키로 중복을 제거합니다. ERP가 중복 제거를 지원하지 않으면 전송 전에 그 전표가 이미 있는지 조회합니다.
- 의존하는 마스터 데이터를 먼저 보냅니다. 신규 고객은 주문보다 먼저 등록합니다. 의존 대상이 준비되지 않았다면 전표는 로컬 큐에서 기다리게 하고 억지로 보내지 않습니다.
- 코드가 맞지 않는 것은 예외가 아니라 일상입니다. 상품이나 고객이 아직 ERP에 없을 때 무엇을 보낼지, 어느 쪽이 빈칸을 채울지 문서로 미리 정합니다.
- ERP 오류는 HTTP 200 응답 본문에 숨어 있는 경우가 많습니다. 하나의 클라이언트가 오류 의미를 일괄 판정해서 호출 지점마다 해석이 달라지지 않게 합니다.
3.0 상태는 조회로 얻는다
전송 응답이 알려 주는 것은 “받았다”는 사실뿐입니다. 이후 상태는 예약 작업으로 조회합니다.
| 설계 항목 | 우리의 선택 |
|---|---|
| 스캔 방식 | OFFSET 대신 기본 키 기반 키셋 페이지네이션. 건수가 늘어도 안정적이고 페이지 사이에서 누락이 없다 |
| 스캔 순서 | 커서를 순환시키며 지난번 멈춘 위치부터 이어 간다. 같은 실패 전표만 반복 처리하지 않는다 |
| 백오프 | 계속 실패하는 전표는 조회 간격을 늘리고 상한을 둔다. 상한을 넘으면 사람에게 넘긴다 |
| 동시성 | 한 전표는 한 번에 하나의 워커만 처리한다. 행 잠금이나 리스로 보장한다 |
4.0 동기화 로그가 장애 조사의 입구다
호출할 때마다 한 줄을 기록합니다. 전표 번호, 동작, 요청 요약, 결과 코드, ERP 메시지, 소요 시간, 시도 횟수입니다. 비밀번호, 토큰, 개인정보 전체는 로그에 넣지 않습니다.
이 테이블이 있으면 “이 주문은 왜 아직 출고되지 않았나”라는 조사를 애플리케이션 로그를 뒤지거나 ERP 쪽에 스크린숏을 부탁하기 전에 쿼리 하나로 시작할 수 있습니다. 우리는 장애 대응 문서도 함께 관리합니다. 새 문제를 해결할 때마다 증상, 근본 원인, 해결 방법, 진단용 쿼리를 적고 새 항목을 맨 위에 둡니다. ERP 연동 문제는 모습을 바꿔 되풀이되는 경우가 많아서, 이 문서가 어떤 대시보드보다 쓸모 있습니다.
5.0 대사
모든 단계가 맞게 돌아가도 양쪽은 조금씩 어긋납니다. 누군가 ERP에서 주문을 직접 수정하거나 취소하고, 조회 결과가 기록되지 않는 일도 생깁니다. 매일 대사를 돌려 주문 상태, 금액, 송장을 비교하고 차이를 목록으로 만들어 담당자에게 넘깁니다. 대사는 어느 쪽도 자동으로 “고치지” 않습니다. 결과물은 작업 목록입니다.
6.0 개발과 테스트
- ERP 어댑터는 인터페이스로 만들고 로컬과 CI에서는 시뮬레이션 구현을 써서, 송장을 포함한 주문 수명 주기 전체를 오프라인으로 돌립니다.
- ERP 테스트 환경은 운영과 다르거나 아예 없는 경우가 많습니다. 통합 테스트 중에 각 엔드포인트의 실제 요청과 응답을 마스킹해 저장하고 회귀 테스트 사례로 씁니다.
- 운영 전환 직후 몇 주는 대사 빈도를 높여 테스트 환경에서 보이지 않던 경우를 빨리 찾아냅니다.
주문 시스템을 ERP에 연결하거나 기존 연동이 자주 끊긴다면 웹·클라우드·디바이스 관리를 참고하거나 프로젝트 상담으로 연락 주세요.
참고 자료
- Stripe, 멱등 요청: https://docs.stripe.com/api/idempotent_requests
- Use The Index, Luke, 키셋 페이지네이션: https://use-the-index-luke.com/no-offset
자주 묻는 질문
ERP가 데이터베이스 뷰만 열어 주고 API가 없습니다. 연동할 수 있나요?
읽기 전용 뷰로 상품과 재고를 가져오는 것은 문제없습니다. ERP 데이터베이스에 전표를 직접 쓰는 것은 위험합니다. ERP 자체 검증을 우회하고, 문제가 생겼을 때 책임 소재가 모호해집니다. 쓰기는 ERP의 API나 가져오기 기능을 통하고, 읽기·쓰기 경계는 먼저 ERP 구축 담당과 합의해야 합니다.
재고는 얼마나 자주 동기화해야 하나요?
초과 판매의 비용과 ERP가 감당할 수 있는 호출 빈도에 따라 다릅니다. 주문 확정 시점에 재고를 실시간으로 한 번 더 확인하는 편이 정기 동기화 빈도를 아주 높이는 것보다 대개 더 확실하고 ERP 부담도 적습니다.
ERP 쪽 검토가 느려서 고객은 계속 '처리 중'만 봅니다. 어떻게 하나요?
어디서 기다리는지 솔직하게 보여 줍니다. 예를 들어 'ERP 검토 대기'라고 표시하고 업무 측과 합의한 처리 기한을 함께 알립니다. ERP 안의 검토를 플랫폼이 대신할 수는 없지만, 기다림을 보이게 하고 기한을 넘기면 담당자에게 자동으로 알릴 수는 있습니다.
나중에 ERP를 바꾸면 플랫폼을 다시 만들어야 하나요?
연동 코드가 하나의 어댑터에 모여 있다면 ERP 교체는 주로 어댑터 재작성, 코드 매핑 재작업, 종단 간 테스트로 끝납니다. 업무 코드 곳곳에서 ERP API를 직접 호출한다면 변경 범위가 훨씬 커집니다. 처음부터 어댑터 계층을 만드는 이유입니다.