“ERP의 상품 정보를 쇼핑몰에 보내고 싶습니다.”
“결제 결과를 사내 시스템에 자동으로 반영하고 싶습니다.”
“배송 상태가 바뀌면 고객에게 알림이 전달되게 만들고 싶습니다.”
API연동 개발을 검토할 때는 보통 이렇게 필요한 기능부터 설명합니다. 겉으로 보면 한 시스템의 데이터를 다른 시스템으로 전달하는 작업처럼 보이지만, 실제 개발 범위는 연결 자체보다 어떤 데이터를 기준으로 삼고, 언제 전달하며, 실패했을 때 어떻게 복구할지에 따라 크게 달라집니다.
정상적인 상황만 가정하면 API 호출 몇 개로 끝날 수 있습니다. 그러나 실제 운영에서는 외부 시스템의 응답이 늦어지거나, 같은 요청이 두 번 전달되거나, 상품은 등록됐지만 옵션 일부가 누락되는 상황이 발생할 수 있습니다.
결제 승인은 완료됐지만 주문 상태가 바뀌지 않을 수도 있고, ERP에서 수정한 상품 정보가 쇼핑몰에 늦게 반영될 수도 있습니다. 배송사가 전달한 상태값과 내부 주문 시스템의 상태값이 서로 맞지 않는 경우도 있습니다.
따라서 API연동 개발업체에 문의하기 전에는 단순히 “연동할 수 있나요?”라고 묻기보다 다음 질문에 답할 수 있어야 합니다.
- 어떤 시스템과 어떤 시스템을 연결할 것인가?
- 데이터의 원본은 어느 시스템인가?
- 어떤 데이터를 가져오고 어떤 데이터를 보낼 것인가?
- 실시간으로 처리해야 하는가, 일정 주기로 처리해도 되는가?
- 같은 요청이 반복되면 어떻게 처리할 것인가?
- 일부 데이터만 처리된 경우 어떻게 복구할 것인가?
- 실패 내역을 누가 어디에서 확인할 것인가?
- 운영자가 직접 다시 처리할 수 있어야 하는가?
이 기준을 먼저 정리하면 개발업체마다 다른 방식으로 해석하는 일을 줄이고, 견적서의 포함 범위도 비교하기 쉬워집니다.
API연동 개발은 단순한 데이터 전달과 다릅니다
API는 시스템끼리 정해진 형식으로 요청과 응답을 주고받는 방법입니다.
예를 들어 쇼핑몰에서 주문이 발생했을 때 ERP에 주문 데이터를 전달할 수 있고, 배송 시스템에서 송장번호를 받아 쇼핑몰 주문에 반영할 수도 있습니다. 결제 서비스의 승인 결과를 받아 예약이나 주문 상태를 변경하는 것도 API연동의 한 사례입니다.
하지만 데이터를 전달할 수 있다는 사실만으로 실제 업무가 완성되지는 않습니다.
주문 연동을 예로 들면 다음과 같은 판단이 함께 필요합니다.
- 주문이 접수되는 즉시 ERP에 전달할 것인가?
- 결제 완료 주문만 전달할 것인가?
- 가상계좌 주문은 입금 전에 전달할 것인가?
- 주문 상품 중 일부가 ERP에 없는 경우 어떻게 처리할 것인가?
- ERP 등록에 실패하면 쇼핑몰 주문 상태를 어떻게 표시할 것인가?
- 운영자는 실패 사실을 어떻게 확인할 것인가?
- 실패한 주문을 자동으로 재전송할 것인가?
- 운영자가 확인한 뒤 수동으로 재전송할 것인가?
즉, API연동은 데이터를 보내는 기술 작업인 동시에 두 시스템 사이의 업무 규칙을 정의하는 작업입니다.
연동 대상 시스템이 늘어날수록 이 규칙도 복잡해집니다. 쇼핑몰, ERP, 결제사, 배송사, CRM이 함께 연결되면 동일한 주문 하나에 여러 시스템의 상태가 관여하게 됩니다.
이때 어느 한 시스템의 응답이 늦거나 실패하면 전체 업무가 어디까지 진행됐는지 판단하기 어려워질 수 있습니다. 그래서 API연동 범위는 정상 흐름보다 실패와 복구 흐름을 중심으로 확인하는 편이 안전합니다.
1. 먼저 연동할 시스템과 역할을 구분해야 합니다
API연동 개발업체에 전달할 첫 번째 정보는 기능 목록보다 현재 사용 중인 시스템의 구성입니다.
다음과 같이 정리할 수 있습니다.
| 구분 | 시스템 | 주요 역할 | 연동 대상 |<br>|---|---|---|---|<br>| 판매 | 자사 쇼핑몰 | 상품 노출, 주문 접수 | ERP, 결제사, 배송사 |<br>| 내부 업무 | ERP | 상품, 재고, 매출 관리 | 쇼핑몰 |<br>| 결제 | 외부 결제 서비스 | 결제 승인, 취소, 환불 | 쇼핑몰, 내부 관리자 |<br>| 배송 | 택배·배송 서비스 | 송장 등록, 배송 상태 제공 | 쇼핑몰, ERP |<br>| 고객 관리 | CRM | 고객 정보와 상담 이력 관리 | 쇼핑몰, 관리자 시스템 |
여기서 중요한 것은 시스템 이름만 나열하는 것이 아닙니다.
각 시스템이 어떤 데이터를 만들고, 수정하고, 최종 확정하는지를 함께 적어야 합니다.
예를 들어 상품명과 판매가는 ERP에서 관리하지만, 상품 상세 설명과 노출 이미지는 쇼핑몰 관리자에서 관리할 수 있습니다. 이 경우 ‘상품 정보의 기준 시스템’을 하나로 단순화하기 어렵습니다.
따라서 데이터 항목별로 역할을 구분해야 합니다.
| 데이터 항목 | 기준 시스템 | 다른 시스템의 역할 |<br>|---|---|---|<br>| 상품 코드 | ERP | 조회 및 연결 |<br>| 상품명 | ERP | 표시 |<br>| 판매가 | ERP 또는 쇼핑몰 | 정책에 따라 결정 |<br>| 상세 설명 | 쇼핑몰 | 직접 관리 |<br>| 재고 수량 | ERP | 판매 가능 수량 표시 |<br>| 판매 상태 | 쇼핑몰 | 노출 여부 관리 |
이 표가 없으면 양쪽 시스템에서 같은 정보를 수정할 수 있게 되고, 나중에 입력한 값이 이전 값을 덮어쓰는 문제가 생길 수 있습니다.
2. 데이터의 기준 시스템을 정해야 합니다
API연동에서 가장 먼저 정해야 할 항목 중 하나는 어느 시스템의 값을 원본으로 볼 것인가입니다.
기준 시스템은 특정 데이터가 최종적으로 생성되고 수정되는 곳을 의미합니다.
예를 들어 다음과 같이 정할 수 있습니다.
- 상품 기본정보의 기준: ERP
- 온라인 판매 여부의 기준: 쇼핑몰
- 결제 승인 상태의 기준: 결제사
- 주문 처리 상태의 기준: 자사 주문 시스템
- 배송 이동 상태의 기준: 배송사
- 고객 상담 처리 상태의 기준: CRM
기준 시스템을 정하지 않으면 양쪽에서 수정된 정보가 충돌합니다.
ERP에서 상품명을 변경한 직후 쇼핑몰 운영자가 이전 상품명으로 수정하면 어느 값을 유지해야 할지 판단할 수 없습니다. 단순히 마지막으로 전달된 값을 저장하면 운영자의 의도와 다른 결과가 생길 수 있습니다.
상태값도 마찬가지입니다.
결제사는 결제를 승인 완료로 전달했지만 내부 주문 시스템은 재고 부족으로 주문을 확정하지 못할 수 있습니다. 이 경우 결제 상태와 주문 상태를 하나의 값으로 관리하면 현재 상황을 정확히 표현하기 어렵습니다.
다음처럼 목적에 따라 상태를 분리하는 방법을 검토할 수 있습니다.
- 주문 상태: 접수, 확인 중, 확정, 출고 준비, 출고 완료, 취소
- 결제 상태: 결제 대기, 승인, 취소 요청, 부분 취소, 전체 취소
- 연동 상태: 전송 대기, 전송 중, 성공, 재시도 대기, 실패, 확인 필요
이렇게 상태를 분리하면 결제는 승인됐지만 주문 확정이 실패한 상황도 기록할 수 있습니다. 운영자는 고객에게 어떤 안내가 필요한지 판단하기 쉬워지고, 개발자는 어느 단계부터 재처리해야 하는지 구분할 수 있습니다.
3. 가져오기·보내기·양방향 동기화를 구분해야 합니다
API연동이라고 해서 모든 데이터를 양방향으로 주고받을 필요는 없습니다.
연동 방향은 크게 세 가지로 나눌 수 있습니다.
외부 시스템에서 가져오기
외부 시스템의 데이터를 자사 서비스로 가져오는 방식입니다.
예를 들면 다음과 같습니다.
- ERP의 상품과 재고를 쇼핑몰로 가져오기
- 배송사의 배송 상태를 주문 시스템으로 가져오기
- 외부 예약 채널의 예약 정보를 관리자 시스템으로 가져오기
- 공공데이터 API의 정보를 웹서비스에 표시하기
가져오기 방식에서는 조회 주기와 변경 데이터 판별 방법이 중요합니다.
매번 전체 데이터를 다시 가져올지, 마지막 조회 이후 변경된 데이터만 가져올지에 따라 처리량과 운영 방식이 달라질 수 있습니다.
외부 시스템으로 보내기
자사 서비스에서 발생한 데이터를 외부 시스템에 전달하는 방식입니다.
예를 들면 다음과 같습니다.
- 쇼핑몰 주문을 ERP로 보내기
- 회원 정보를 CRM에 전달하기
- 배송 요청을 물류 시스템에 등록하기
- 예약 정보를 외부 일정 시스템에 전달하기
보내기 방식에서는 어느 시점에 전송할지가 중요합니다.
주문 생성 직후 보낼지, 결제 승인 후 보낼지, 운영자가 주문을 확인한 뒤 보낼지에 따라 실패 처리와 취소 흐름도 달라집니다.
양방향 동기화
두 시스템 모두에서 데이터를 생성하거나 수정할 수 있는 방식입니다.
양방향 동기화는 편리해 보이지만 충돌 규칙이 추가로 필요합니다.
- 양쪽에서 같은 데이터를 수정하면 어느 값을 우선할 것인가?
- 수정 시간을 비교할 것인가?
- 특정 항목만 한쪽의 값을 우선할 것인가?
- 삭제도 동기화할 것인가?
- 한쪽 시스템의 일시적인 오류가 다른 쪽 데이터에 영향을 주지 않는가?
특별한 이유가 없다면 모든 데이터를 양방향으로 열기보다, 항목별 기준 시스템을 정하고 필요한 방향으로만 동기화하는 편이 구조를 단순하게 유지하는 데 도움이 됩니다.
4. 실시간 연동이 항상 필요한 것은 아닙니다
API연동 범위를 논의할 때 자주 등장하는 요구사항이 “실시간으로 반영해 주세요”입니다.
하지만 실시간이라는 표현은 사람마다 다르게 이해할 수 있습니다.
- 사용자가 버튼을 누른 즉시 처리
- 주문이나 결제 이벤트 발생 후 수초 안에 처리
- 1분마다 변경 데이터를 확인
- 10분마다 일괄 동기화
- 하루 한 번 정해진 시간에 처리
재고 차감이나 결제 승인처럼 즉시성이 필요한 업무도 있지만, 상품 설명이나 정산용 데이터처럼 일정 주기로 처리해도 되는 업무도 있습니다.
실시간 처리 범위가 넓어질수록 외부 시스템의 응답 속도와 장애가 사용자 경험에 직접 영향을 줄 수 있습니다.
예를 들어 사용자가 주문 버튼을 누른 뒤 ERP 등록이 끝날 때까지 기다리도록 설계하면, ERP 응답이 느려질 때 쇼핑몰의 주문 화면도 함께 느려질 수 있습니다.
이런 경우 다음과 같은 비동기 처리 구조를 검토할 수 있습니다.
- 자사 서비스에서 주문을 먼저 접수합니다.
- 전송할 주문을 대기 상태로 저장합니다.
- 별도 처리 과정에서 ERP API를 호출합니다.
- 성공하면 연동 완료로 변경합니다.
- 실패하면 재시도 대기 또는 확인 필요 상태로 변경합니다.
- 운영자는 관리자 화면에서 결과를 확인합니다.
웹훅을 사용하는 연동도 수신 즉시 모든 업무를 끝내려고 하기보다, 요청을 정상적으로 접수한 뒤 실제 처리는 별도로 진행하는 방식이 유리할 수 있습니다. GitHub 공식 문서도 웹훅 수신 서버가 제한 시간 안에 응답할 수 있도록 요청을 먼저 접수하고, 큐 등을 통해 비동기 처리하는 방식을 안내합니다. (docs.github.com)
다만 실시간과 배치 중 어느 방식이 더 좋다고 일률적으로 말할 수는 없습니다. 데이터의 중요도, 허용 가능한 반영 지연, 외부 API의 호출 제한, 사용자의 대기 여부를 함께 검토해야 합니다.
5. 상품·회원·주문 데이터의 식별자를 맞춰야 합니다
시스템마다 동일한 대상을 다른 값으로 관리할 수 있습니다.
예를 들어 한 상품이 ERP에서는 P-10025, 쇼핑몰에서는 3841, 물류 시스템에서는 SKU-A-77로 저장될 수 있습니다.
이때 상품명으로 데이터를 연결하면 이름이 변경되거나 비슷한 상품이 존재할 때 잘못 연결될 수 있습니다.
따라서 시스템별 식별자의 대응 관계를 별도로 관리해야 합니다.
| 내부 식별자 | ERP 상품 코드 | 쇼핑몰 상품 번호 | 물류 SKU |<br>|---|---|---|---|<br>| PRODUCT-001 | P-10025 | 3841 | SKU-A-77 |
회원, 주문, 결제, 배송 데이터도 같은 방식으로 연결 정보가 필요할 수 있습니다.
- 내부 회원번호와 외부 CRM 고객번호
- 내부 주문번호와 ERP 전표번호
- 내부 결제번호와 결제사 거래번호
- 내부 배송번호와 배송사 송장번호
- 내부 취소 요청번호와 결제사 취소 거래번호
연동 개발 범위에는 식별자 생성 규칙과 저장 위치, 중복 확인 기준이 포함되어야 합니다.
외부 시스템이 이미 등록된 데이터를 다시 전달했을 때 신규 데이터로 생성하지 않고 기존 데이터와 연결하려면 무엇을 기준으로 같은 데이터라고 판단할지도 정해야 합니다.
6. 상태값 매핑표가 필요합니다
두 시스템이 같은 업무를 처리하더라도 사용하는 상태값은 다를 수 있습니다.
예를 들어 내부 주문 시스템은 다음 상태를 사용할 수 있습니다.
- 주문 접수
- 결제 완료
- 상품 준비
- 출고 완료
- 취소 완료
반면 ERP는 다음과 같이 관리할 수 있습니다.
- 신규
- 승인
- 출고 지시
- 매출 확정
- 취소 전표
이 경우 상태 이름을 단순히 번역해서 연결하기 어렵습니다. 각 상태가 실제 업무에서 어떤 의미인지 확인해야 합니다.
| 내부 주문 상태 | ERP 상태 | 전송 조건 | 예외 처리 |<br>|---|---|---|---|<br>| 주문 접수 | 신규 | 주문 생성 완료 | 상품 코드가 없으면 실패 |<br>| 결제 완료 | 승인 | 결제 승인 확인 | 결제 검증 실패 시 보류 |<br>| 상품 준비 | 출고 지시 | 운영자 확인 완료 | 재고 부족 시 확인 필요 |<br>| 출고 완료 | 매출 확정 | 송장 등록 완료 | 일부 출고 시 별도 처리 |<br>| 취소 완료 | 취소 전표 | 취소 승인 완료 | 이미 출고된 경우 수동 확인 |
상태값 매핑표가 있으면 개발뿐 아니라 테스트와 운영 교육에도 활용할 수 있습니다.
또한 외부 시스템에 상태가 추가되거나 기존 의미가 변경될 때 어느 부분을 점검해야 하는지도 파악하기 쉬워집니다.
7. 중복 전송을 정상적인 상황으로 봐야 합니다
외부 API 호출 후 응답을 받지 못했다고 해서 요청이 처리되지 않은 것은 아닙니다.
예를 들어 ERP에 주문 등록 요청을 보낸 뒤 네트워크 연결이 끊겼다고 가정해 보겠습니다.
자사 시스템에서는 실패처럼 보이지만, ERP에는 주문이 이미 등록됐을 수 있습니다. 이때 같은 요청을 그대로 다시 보내면 ERP에 동일 주문이 두 번 생성될 가능성이 있습니다.
그래서 주문 등록, 결제 요청, 포인트 적립과 같이 중복 처리가 문제가 되는 작업에는 고유 요청값이나 업무 식별자를 활용한 중복 방지 구조가 필요합니다.
HTTP 표준에서도 여러 번 실행했을 때 의도한 결과가 한 번 실행한 것과 같아야 하는 성질을 멱등성이라고 설명하며, 멱등성이 보장되지 않는 요청을 자동으로 재시도할 때는 주의가 필요하다고 안내합니다. (datatracker.ietf.org)
일부 외부 서비스는 별도의 멱등성 키를 제공합니다. 예를 들어 Stripe는 동일한 키를 사용한 재요청이 같은 작업을 중복 실행하지 않도록 하는 방식을 공식 API에서 지원합니다. (docs.stripe.com)
하지만 모든 API가 같은 기능을 제공하는 것은 아닙니다. 연동 대상 API가 중복 방지 기능을 제공하지 않는다면 자사 시스템에서 다음과 같은 방법을 검토해야 합니다.
- 요청마다 고유한 연동 번호 생성
- 주문번호와 요청 유형의 조합 저장
- 동일 요청이 진행 중인지 확인
- 이미 완료된 요청이면 다시 실행하지 않음
- 외부 시스템에서 기존 처리 결과를 조회한 후 재전송
- 웹훅의 고유 전달 번호 저장
- 중복 수신 시 기존 처리 결과 반환
중복 전송은 특수한 오류가 아니라 네트워크 환경에서 발생할 수 있는 운영 상황으로 보는 편이 좋습니다.
8. 재시도는 횟수와 간격까지 정해야 합니다
일시적인 네트워크 오류나 외부 서버의 과부하는 잠시 후 다시 호출하면 정상 처리될 수 있습니다.
그렇다고 오류가 발생할 때마다 즉시 무제한으로 재시도해서는 안 됩니다. 외부 서비스가 이미 불안정한 상황에서 요청을 더 많이 보내면 장애가 확대될 수 있습니다.
AWS는 재시도를 설계할 때 호출 대상의 멱등성을 먼저 확인하고, 재시도 횟수를 제한하며, 요청 간격을 점차 늘리는 백오프와 재시도 시점이 한꺼번에 몰리지 않게 하는 지터를 함께 검토하도록 안내합니다. (docs.aws.amazon.com)
API에 호출 제한이 있다면 응답 코드와 헤더도 확인해야 합니다. Microsoft의 API 제한 대응 지침은 429 상태와 Retry-After 값을 확인하고, 즉시 반복 호출하기보다 안내된 시간만큼 대기한 뒤 재시도하도록 설명합니다. (learn.microsoft.com)
실제 개발 범위에서는 다음 항목을 정해야 합니다.
- 어떤 오류에 재시도할 것인가?
- 어떤 오류는 즉시 실패로 처리할 것인가?
- 최대 몇 번까지 재시도할 것인가?
- 재시도 간격은 어떻게 늘릴 것인가?
- 최종 실패 후 누구에게 알릴 것인가?
- 운영자가 다시 실행할 수 있는가?
- 재실행 전에 데이터를 수정할 수 있는가?
예를 들어 인증 정보가 잘못됐거나 필수 상품 코드가 누락된 오류는 같은 요청을 반복해도 해결되지 않습니다. 반면 일시적인 서버 오류나 호출 제한은 일정 시간 후 재시도할 수 있습니다.
모든 오류를 같은 방식으로 다루지 않고 원인에 따라 분류하는 것이 필요합니다.
9. 부분 성공을 어떻게 처리할지 정해야 합니다
여러 데이터를 한 번에 전송할 때는 전체 성공과 전체 실패만 발생하지 않습니다.
상품 100개를 ERP에서 쇼핑몰로 가져왔는데 97개는 성공하고 3개만 실패할 수 있습니다. 주문 한 건 안에서도 주문 기본정보는 등록됐지만 주문 상품 일부가 실패하거나, 주문은 등록됐지만 배송지 정보 반영에 실패할 수 있습니다.
이런 상황에서 무조건 전체를 다시 전송하면 성공한 데이터까지 중복 처리될 수 있습니다.
따라서 처리 단위를 정해야 합니다.
- 요청 전체를 하나의 단위로 처리할 것인가?
- 상품 한 건씩 결과를 저장할 것인가?
- 주문 기본정보와 주문 상품을 분리할 것인가?
- 부분 성공을 허용할 것인가?
- 일부 실패 시 성공한 작업도 되돌릴 것인가?
- 실패한 항목만 다시 처리할 수 있는가?
결제, 포인트, 재고처럼 금액과 수량에 영향을 주는 데이터는 특히 신중하게 설계해야 합니다.
외부 요청이 성공한 뒤 내부 데이터 저장에 실패하면 외부 상태와 내부 상태가 달라질 수 있습니다. 이때 단순히 처음부터 다시 실행하면 중복 승인이나 중복 차감이 발생할 수 있으므로, 각 단계의 처리 결과를 기록하고 현재 상태를 확인한 뒤 이어서 처리할 수 있어야 합니다.
10. 웹훅은 순서와 누락을 가정해야 합니다
웹훅은 외부 시스템에서 특정 이벤트가 발생했을 때 자사 시스템으로 알려주는 방식입니다.
결제 승인, 결제 취소, 배송 상태 변경처럼 외부 상태 변화를 빠르게 반영할 때 활용할 수 있습니다.
하지만 웹훅이 항상 한 번만, 정확한 순서로, 누락 없이 들어온다고 가정해서는 안 됩니다.
서비스에 따라 자동 재전송 정책이 다를 수 있으며, GitHub의 경우 실패한 웹훅을 자동으로 다시 전달하지 않는다고 명시하고 별도의 재전송 절차를 제공합니다. 또한 웹훅이 실제 이벤트 발생 순서와 다르게 도착할 수 있다고 안내합니다. (docs.github.com)
따라서 웹훅 연동에서는 다음 항목을 확인해야 합니다.
- 전달 고유값을 저장하는가?
- 같은 웹훅이 다시 들어와도 중복 처리되지 않는가?
- 서명이나 인증값을 검증하는가?
- 오래된 상태 이벤트가 나중에 도착하면 어떻게 하는가?
- 수신 실패 건을 다시 받을 수 있는가?
- 웹훅이 누락됐을 때 상태 조회 API로 보완할 수 있는가?
- 원본 요청 내용을 어느 범위까지 기록할 것인가?
웹훅만 믿고 상태를 확정하기보다, 중요한 거래는 외부 시스템의 조회 API를 통해 현재 상태를 다시 확인하는 절차를 함께 검토할 수 있습니다.
11. 실패 로그와 재처리 관리자 화면이 필요합니다
API연동이 운영 가능한 구조인지 판단하려면 사용자 화면보다 관리자 화면에서 실패를 어떻게 다루는지 확인해야 합니다.
개발자만 서버 로그를 확인할 수 있는 구조라면 작은 오류도 매번 개발업체에 요청해야 할 수 있습니다.
운영자가 확인할 수 있는 관리자 기능에는 다음 항목을 검토할 수 있습니다.
연동 이력 조회
- 연동 대상 시스템
- 데이터 종류
- 내부 식별자
- 외부 식별자
- 요청 시각
- 처리 완료 시각
- 처리 상태
- 재시도 횟수
- 최종 오류 원인
검색과 필터
- 기간별 조회
- 성공·실패·대기 상태별 조회
- 주문번호나 상품 코드 검색
- 외부 시스템별 필터
- 오류 유형별 필터
- 재시도 횟수별 필터
상세 확인
- 어떤 데이터가 전달됐는지
- 어떤 응답을 받았는지
- 어느 단계에서 실패했는지
- 이전에 몇 번 재시도했는지
- 관련 주문이나 회원 정보가 무엇인지
다만 요청과 응답 원문에 개인정보, 인증 토큰, 결제 정보가 포함될 수 있으므로 모든 내용을 그대로 노출하거나 장기간 저장하는 방식은 주의해야 합니다.
OWASP API Security Top 10은 객체와 기능에 대한 권한 통제, 인증, 민감한 업무 흐름, 외부 API를 안전하지 않게 사용하는 문제 등을 주요 API 보안 위험으로 다루고 있습니다. 따라서 연동 관리자 화면에도 역할별 조회·재처리 권한과 민감정보 마스킹을 함께 검토해야 합니다. (api-security.owasp.org)
재처리 기능
- 실패한 한 건 재처리
- 선택한 여러 건 일괄 재처리
- 오류 원인을 수정한 뒤 재처리
- 자동 재시도 중지
- 이미 완료된 건의 중복 실행 방지
- 관리자 재처리 이력 저장
재처리 버튼만 만드는 것으로 끝나서는 안 됩니다.
이미 외부 시스템에는 반영됐지만 내부에서 성공 응답을 저장하지 못한 건을 다시 처리하면 중복 데이터가 만들어질 수 있습니다. 재처리 전 외부 처리 여부를 조회할 수 있는지, 같은 업무 식별자로 재요청해도 안전한지 함께 확인해야 합니다.
12. 개발업체 문의 전 준비할 자료
API연동 상담을 받을 때 완성된 기획서가 반드시 필요한 것은 아닙니다.
다만 다음 자료가 있으면 개발업체가 범위를 더 구체적으로 검토할 수 있습니다.
1. 연동 대상 시스템 목록
- 현재 사용 중인 시스템
- 새로 도입할 시스템
- 각 시스템의 운영 업체
- 계약 또는 계정 보유 주체
- 테스트 계정 제공 가능 여부
2. API 문서
가능하다면 다음 내용을 확인합니다.
- API 문서 주소 또는 파일
- 인증 방식
- 제공되는 기능
- 요청과 응답 예시
- 오류 코드
- 호출 제한
- 웹훅 지원 여부
- 테스트 환경 제공 여부
- 운영 환경 사용 승인 절차
API 문서가 있다는 이유만으로 필요한 기능을 모두 구현할 수 있는 것은 아닙니다. 화면에서는 제공되는 기능이 API에는 없을 수 있고, 계약 상품이나 계정 권한에 따라 사용할 수 있는 API가 달라질 수도 있습니다.
3. 현재 업무 흐름
현재 담당자가 실제로 처리하는 순서를 적는 것이 좋습니다.
예를 들면 다음과 같습니다.
- 쇼핑몰에서 주문을 확인한다.
- 결제 완료 주문만 엑셀로 내려받는다.
- ERP 양식에 맞게 항목을 수정한다.
- ERP에 업로드한다.
- 상품 코드가 없는 주문은 별도로 확인한다.
- 출고 후 송장번호를 쇼핑몰에 입력한다.
- 고객에게 배송 알림을 보낸다.
이 과정을 보면 자동화할 단계와 사람이 확인해야 할 단계를 구분할 수 있습니다.
4. 데이터 샘플
- 상품 엑셀
- 주문 내역
- 회원 데이터
- 배송 데이터
- 상태값 목록
- 코드 체계
- 필수 입력값
실제 개인정보가 포함됐다면 불필요한 항목을 제거하거나 예시 데이터로 바꿔 전달하는 것이 좋습니다.
5. 예외 상황 목록
- 외부 상품 코드가 없는 경우
- 재고가 부족한 경우
- 주문 상품 일부만 처리된 경우
- 결제 승인 후 주문 저장이 실패한 경우
- 취소 요청 시 이미 출고된 경우
- 회원 정보가 중복된 경우
- 외부 시스템이 점검 중인 경우
예외 상황이 완벽하게 정리되지 않았더라도 현재 자주 발생하는 사례를 전달하면 초기 범위를 판단하는 데 도움이 됩니다.
13. 견적서에서는 연결 기능 밖의 범위를 확인해야 합니다
API연동 개발 견적을 비교할 때는 API 호출 기능의 개수만 보지 않는 것이 좋습니다.
다음 항목이 포함됐는지 확인해야 합니다.
사전 분석
- API 문서 검토
- 기능 제공 여부 확인
- 데이터 항목 매핑
- 상태값 매핑
- 인증과 권한 방식 검토
- 호출 제한 확인
개발
- 데이터 조회와 전송
- 식별자 연결
- 중복 방지
- 타임아웃 처리
- 오류 유형 분류
- 자동 재시도
- 부분 실패 처리
- 연동 이력 저장
관리자 기능
- 연동 결과 조회
- 실패 원인 확인
- 검색과 필터
- 수동 재처리
- 일괄 재처리
- 관리자 작업 이력
테스트
- 정상 요청
- 잘못된 데이터
- 인증 만료
- 응답 지연
- 외부 서버 오류
- 중복 요청
- 호출 제한
- 부분 성공
- 웹훅 중복 및 순서 변경
배포와 전환
- 테스트 환경과 운영 환경 분리
- 운영 API 키 등록
- 초기 데이터 동기화
- 기존 데이터와 신규 데이터 구분
- 전환 시점 결정
- 문제 발생 시 복구 절차
유지보수
- 외부 API 버전 변경 대응
- 인증서나 API 키 갱신
- 신규 오류 유형 대응
- 데이터 항목 변경
- 연동 모니터링
- 장애 발생 시 대응 범위
API연동은 외부 시스템에 의존하기 때문에 개발이 완료된 뒤에도 상대 서비스의 정책이나 문서가 변경될 수 있습니다.
따라서 하자 수정과 유지보수의 범위, 외부 API 변경으로 발생한 추가 작업을 어떻게 구분할지도 계약 전에 확인하는 것이 좋습니다.
14. 모든 데이터를 한 번에 연동할 필요는 없습니다
연동 대상이 많다면 1차 범위와 이후 확장 범위를 나눌 수 있습니다.
예를 들어 쇼핑몰과 ERP를 연결하는 경우 1차에는 다음 범위만 포함할 수 있습니다.
1차 구축
- ERP 상품 정보 가져오기
- 재고 수량 반영
- 결제 완료 주문 전달
- ERP 처리 결과 저장
- 실패 이력 조회
- 운영자 수동 재처리
이후 확장
- 상품 정보 양방향 수정
- 부분 취소 자동 반영
- 복수 창고 재고 계산
- 거래처별 가격 동기화
- 정산 데이터 연동
- 연동 현황 통계와 알림
초기부터 모든 예외와 자동화를 포함하면 범위가 커지고 테스트할 경우의 수도 많아집니다.
먼저 핵심 업무 흐름을 안정적으로 연결하고, 실제 운영에서 반복되는 수작업과 오류를 확인한 뒤 확장하는 방법도 고려할 수 있습니다.
다만 초기 범위를 줄이더라도 식별자 구조, 상태값, 연동 이력처럼 이후 확장에 영향을 주는 기본 구조는 함께 검토해야 합니다.
API연동 개발업체에 문의하기 전 체크리스트
아래 내용을 정리하면 상담과 견적 비교가 수월해집니다.
- [ ] 연결할 시스템과 각 시스템의 역할을 정리했는가?
- [ ] 데이터 항목별 기준 시스템을 정했는가?
- [ ] 가져오기, 보내기, 양방향 동기화를 구분했는가?
- [ ] 실시간 처리와 주기 처리 항목을 나눴는가?
- [ ] 시스템별 식별자 연결 방법을 확인했는가?
- [ ] 상태값 매핑표를 만들었는가?
- [ ] 중복 요청을 판단할 기준이 있는가?
- [ ] 자동 재시도의 대상과 횟수를 정했는가?
- [ ] 부분 성공 시 처리 방법을 정했는가?
- [ ] 외부 장애 중에도 유지해야 할 내부 업무를 정했는가?
- [ ] 운영자가 실패 원인을 확인할 수 있는가?
- [ ] 운영자가 안전하게 재처리할 수 있는가?
- [ ] API 문서와 테스트 계정을 확보했는가?
- [ ] 테스트·배포·초기 동기화 범위가 견적에 포함됐는가?
- [ ] 외부 API 변경에 대한 유지보수 조건을 확인했는가?
연결 가능 여부보다 운영 가능한 범위를 확인해야 합니다
API연동 개발은 두 시스템이 한 번 데이터를 주고받는 데서 끝나지 않습니다.
어느 시스템의 데이터를 기준으로 볼 것인지, 언제 전달할 것인지, 같은 요청이 반복됐을 때 어떻게 중복을 막을 것인지, 일부만 성공했을 때 어디서부터 복구할 것인지가 함께 설계되어야 합니다.
특히 실제 운영에서는 외부 시스템의 응답 지연과 장애를 완전히 피하기 어렵습니다. 실패를 예외적인 사건으로 숨기기보다, 기록하고 확인하고 안전하게 재처리할 수 있는 구조를 만드는 것이 필요합니다.
원소프트는 웹·앱·관리자 시스템과 외부 API·ERP 연동을 검토할 때 사용자 화면뿐 아니라 데이터 구조, 상태값, 관리자 운영 흐름을 함께 살펴봅니다. 필요한 경우 현재 수작업으로 처리하는 업무를 기준으로 1차 연동 범위와 이후 확장 범위를 나누어 정리할 수 있습니다.
경기도 화성시 동탄순환대로 823, 영천동 에이팩시티에 위치하고 있으며, 동탄·화성을 비롯해 수원·용인·기흥·오산 등 경기 남부에서 웹서비스와 업무 시스템 개발을 검토하고 있다면 현재 운영 방식과 API 자료를 바탕으로 필요한 범위를 함께 확인해볼 수 있습니다.
API 문서가 아직 준비되지 않았더라도 현재 사용하는 시스템, 주고받아야 할 데이터, 담당자가 수작업으로 처리하는 과정을 정리해 주시면 연동 가능 여부와 먼저 확인해야 할 조건을 검토하는 데 도움이 됩니다.
제목 후보
- API연동 개발업체 문의 전, 데이터 흐름과 실패 대응 범위를 정하는 방법
- API연동 개발, 연결보다 먼저 정해야 할 데이터·동기화·오류 처리 기준
- API연동 업체 선정 전 확인할 기준, 중복 전송과 실패 재처리까지
- ERP·결제·배송 API연동, 운영 가능한 개발 범위를 정하는 체크리스트
- API연동 견적 비교, 데이터 기준과 관리자 재처리 기능을 확인하세요
추천 제목
API연동 개발업체 문의 전, 데이터 흐름과 실패 대응 범위를 정하는 방법
메인 키워드
API연동
서브 키워드
- API연동 개발업체
- 외부 API연동
- ERP API연동
- API연동 개발
- API연동 견적
추천 해시태그
#API연동 <br>#API연동개발 <br>#외부API연동 <br>#ERP연동 <br>#시스템연동 <br>#관리자시스템개발 <br>#업무자동화 <br>#웹개발외주 <br>#동탄웹개발 <br>#화성웹개발
썸네일 문구
- API연동, 연결보다 운영이 먼저입니다
- 데이터 흐름과 실패 대응 범위
- 중복·지연·오류까지 설계해야 합니다
글 요약
API연동은 단순히 데이터를 주고받는 기능이 아니라 기준 시스템, 동기화 방향과 시점, 식별자 및 상태값을 정의하는 작업입니다. 중복 전송, 응답 지연, 부분 성공과 외부 장애에 대비해 재시도 기준, 실패 로그, 관리자 확인·재처리 기능까지 개발 및 견적 범위에 포함하는 방법을 정리했습니다.
CTA 후보
- 연동할 시스템과 API 문서는 있지만 개발 범위를 정하기 어렵다면, 현재 데이터 흐름과 수작업 처리 과정을 기준으로 필요한 기능을 함께 정리해볼 수 있습니다.
- ERP·결제·배송·CRM 연동을 검토하고 계신다면 사용 중인 시스템, 주고받을 데이터, 오류 발생 시 운영 방식을 전달해 주세요. 1차 연동 범위와 이후 확장 항목을 구분해 검토할 수 있습니다.
관련 포트폴리오
사용하지 않음
다음에 작성하면 좋은 연관 글
- API연동 테스트, 정상 처리보다 먼저 확인해야 할 오류 시나리오
- ERP연동 개발, 상품·재고·주문 데이터의 기준 시스템을 정하는 방법
- API연동 관리자 페이지, 실패 로그와 안전한 재처리 기능 설계 기준
