외부 API 연동, 왜 프로젝트를 망치나

시즌 개시 2주 전, 신규 오픈한 자사몰과 물류사 WMS가 연동이 안 된다는 연락을 받은 적 있으신가요? 개발사는 "API 스펙이 바뀌었다"고 하고, 물류사는 "우리 쪽 문제 아니다"라고 합니다. 그 사이 주문은 쌓이고, 출고는 멈춥니다.

이건 특정 개발사의 실력 문제가 아닙니다. 외부 API 연동은 구조적으로 프로젝트를 위험하게 만드는 요소를 품고 있습니다. 그 이유를 모르면, 다음 프로젝트에서도 같은 자리에서 같은 문제를 만납니다.

API 연동이 왜 유독 위험한가

내 시스템이 아닌 곳에서 결정이 난다

ERP를 새로 구축하거나 자사몰을 개편할 때, 실제로 연동해야 하는 외부 시스템 목록을 한번 세어보세요. 카카오페이·토스·네이버페이 같은 결제 PG, 네이버 스마트스토어·무신사·29CM 같은 판매 채널, CJ대한통운·한진·롯데글로벌로지스 같은 택배사 API, 그리고 자체 물류 창고의 WMS까지. 중형 패션 브랜드 기준으로 최소 5~8개, 많으면 15개 이상의 외부 시스템과 연결됩니다.

문제는 이 시스템들이 언제든 스펙을 바꿀 수 있다는 겁니다. 내 프로젝트 일정과 무관하게. 실제로 네이버 커머스 API는 연간 수차례 버전 업데이트가 있고, 일부 PG사는 보안 정책 변경으로 인증 방식을 전면 교체하기도 합니다. 내 개발팀이 아무리 완벽하게 작업해도, 외부 시스템이 변하면 연동은 깨집니다.

테스트 환경과 실제 환경이 다르다

개발 단계에서 API 연동 테스트는 대부분 샌드박스(sandbox) 환경에서 진행됩니다. 그런데 실제 운영 환경에서는 샌드박스에 없던 예외 케이스가 반드시 등장합니다. 예를 들어 특정 택배사 API는 운송장 번호가 13자리인 경우와 14자리인 경우의 응답 포맷이 다른데, 샌드박스에서는 13자리 케이스만 제공합니다. 오픈 첫날 14자리 운송장이 들어오면 시스템이 조용히 실패합니다. 에러 메시지도 없이.

이런 케이스는 문서에 없습니다. 직접 겪어봐야 압니다.

연동 실패가 만드는 실제 비용

지연은 단순 일정 문제가 아니다

패션 업계에서 시스템 오픈 지연은 곧 시즌 타이밍 손실입니다. 봄 시즌 신상품 론칭에 맞춰 자사몰을 개편하려 했는데, API 연동 이슈로 오픈이 3주 밀렸다고 가정해봅시다. 그 3주 동안 경쟁사는 신상품을 풀고, 인플루언서 협업 콘텐츠를 돌립니다. 시즌 초반 판매 모멘텀을 잃으면 재고 회전율에 직접 영향이 갑니다.

연매출 50억 원 브랜드에서 봄 시즌 3주 지연은 최소 1억~1.5억 원 규모의 매출 기회 손실로 추산됩니다. 개발 비용보다 훨씬 큰 숫자입니다.

운영 중 오류는 더 비싸다

오픈 전 지연보다 더 무서운 건 운영 중 발생하는 연동 오류입니다. 주문이 들어왔는데 재고 차감이 안 되거나, 출고 지시가 WMS에 전달이 안 되거나, 환불 처리가 PG에는 됐는데 내부 시스템에는 반영이 안 되는 상황. 이런 오류는 고객 컴플레인으로 먼저 발견됩니다. 그때는 이미 늦었습니다.

데이터 불일치를 수작업으로 복구하는 데 드는 인력 비용, CS 대응 비용, 그리고 브랜드 신뢰 손상까지 합산하면 단 하루의 연동 장애가 수천만 원짜리 문제가 됩니다.

연동 프로젝트에서 반드시 짚어야 할 세 가지

첫째, 연동 대상 목록을 프로젝트 초반에 확정하라

프로젝트 킥오프 미팅에서 흔히 빠지는 항목이 있습니다. "나중에 연동하면 되는 것들"입니다. 그런데 나중에 추가되는 연동은 항상 기존 구조를 건드려야 하는 연동이 됩니다. 처음부터 설계에 포함됐다면 깔끔하게 처리됐을 것들이, 나중에 추가되면서 임시방편 코드가 쌓입니다. 그 임시방편이 다음 오류의 씨앗이 됩니다.

연동 대상을 확정할 때는 현재 사용 중인 시스템뿐 아니라 향후 12개월 내 도입 가능성이 있는 채널과 서비스까지 같이 논의해야 합니다. 무신사 입점을 검토 중이라면, 지금 당장 연동하지 않더라도 그 구조를 염두에 두고 설계해야 합니다.

둘째, 연동 실패 시 동작 방식을 미리 정의하라

대부분의 프로젝트에서 "API가 정상 동작할 때" 시나리오는 꼼꼼하게 설계합니다. 그런데 "API가 실패했을 때" 시스템이 어떻게 동작해야 하는지는 논의조차 안 하는 경우가 많습니다.

택배사 API가 응답하지 않을 때, 주문을 보류 상태로 쌓아두고 재시도해야 할까요, 아니면 운영자에게 알림을 보내고 수동 처리로 넘겨야 할까요? PG 응답이 타임아웃됐을 때, 결제 완료로 처리해야 할까요, 실패로 처리해야 할까요? 이 판단은 비즈니스 정책 결정입니다. 개발자가 혼자 결정할 수 없고, 해서도 안 됩니다.

이 시나리오를 미리 정의하지 않으면, 실제 장애 상황에서 개발자와 운영자가 서로 다른 기준으로 대응하게 됩니다.

셋째, 연동 유지보수 책임을 계약에 명시하라

외부 API는 변합니다. 그럼에도 많은 계약서에는 "납품 후 하자보수 3개월"이라는 문구만 있습니다. 외부 API 스펙 변경으로 인한 연동 오류가 하자인지, 아니면 새로운 개발 요건인지 기준이 없습니다.

계약 시점에 외부 API 변경으로 인한 수정 작업의 처리 기준을 명확히 해야 합니다. 어떤 범위까지는 유지보수에 포함되고, 어떤 범위부터는 별도 비용이 발생하는지. 이걸 미리 정하지 않으면, 첫 번째 API 변경 시점에 개발사와 갈등이 생깁니다.

연동은 기술 문제가 아니라 설계 문제다

외부 API 연동이 프로젝트를 망치는 가장 근본적인 이유는 하나입니다. 연동을 기술적 구현 과제로만 보고, 비즈니스 설계 과제로 보지 않기 때문입니다.

어떤 시스템과 연결할지, 연동이 실패했을 때 어떻게 운영할지, 외부 변경에 어떻게 대응할지. 이 질문들은 개발팀이 알아서 결정할 수 없습니다. 브랜드 운영 방식을 가장 잘 아는 사람, 즉 여러분이 개발팀과 함께 결정해야 합니다.

그 대화를 프로젝트 초반에 충분히 하는 팀과 하지 않는 팀의 결과는, 오픈 직전에 극명하게 갈립니다.

외부 API 연동 설계를 처음부터 비즈니스 관점으로 함께 짚고 싶다면, 구체적인 연동 목록과 운영 시나리오부터 같이 검토해드립니다. → 문의하기