시스템 연동 프로젝트, API보다 먼저 데이터 계약을 정해야 하는 이유

두 시스템을 연결할 때 가장 먼저 API 목록부터 만드는 경우가 많습니다. 하지만 호출 방법을 정해도 어떤 데이터를 기준으로 볼지, 같은 요청이 다시 들어오면 어떻게 할지 합의되지 않았다면 연동은 쉽게 불안정해집니다.

연동의 목표는 데이터를 많이 오가는 것이 아니라 업무가 끊기지 않도록 필요한 정보를 정확한 시점에 전달하는 것입니다. 이를 위해 개발 전에 데이터 계약과 운영 규칙을 문서로 맞춰야 합니다.

1. 연동의 시작과 끝을 업무 문장으로 적습니다

“주문을 동기화한다”처럼 기술 용어로 시작하지 말고 어떤 사건이 발생해 어떤 결과를 만들어야 하는지 적습니다. 예를 들어 “결제가 완료되면 주문 시스템에 주문을 만들고 재고 시스템에 차감 요청을 보낸다”처럼 시작 조건, 처리 대상, 완료 상태를 한 문장에 담습니다. 이 문장이 있어야 불필요한 필드와 호출을 줄일 수 있습니다.

2. 데이터의 기준 시스템을 정합니다

고객 정보는 CRM, 상품 가격은 쇼핑몰, 계약 상태는 별도 문서에 있다면 같은 고객이나 상품을 두고 값이 달라질 수 있습니다. 항목마다 어느 시스템이 최종 기준인지, 누가 수정할 권한을 갖는지, 변경 내용이 언제 전파되는지를 정해야 합니다.

• 고객·상품·주문처럼 식별자가 필요한 데이터의 원천을 지정합니다.

• 값이 충돌할 때 적용할 우선순위를 정합니다.

• 변경을 허용하는 시스템과 읽기만 하는 시스템을 구분합니다.

• 보관 기간과 삭제 요청 처리 주체를 확인합니다.

3. 필드와 상태값을 표로 맞춥니다

한쪽의 “완료”가 다른 쪽의 “정산 대기”일 수 있습니다. 필드 이름만 맞추지 말고 자료형, 필수 여부, 단위, 시간대, 상태값의 의미를 함께 기록해야 합니다. 비어 있는 값과 더 이상 사용하지 않는 상태값도 어떻게 변환할지 정해 두면 운영 중 임의의 해석을 줄일 수 있습니다.

4. 중복·순서·재시도를 먼저 다룹니다

네트워크 지연이나 사용자의 재요청으로 같은 이벤트가 두 번 전달될 수 있고, 여러 이벤트가 순서대로 도착하지 않을 수도 있습니다. 요청마다 고유 키를 두고 이미 처리한 요청은 다시 결과를 만들지 않도록 해야 합니다. 재시도할 오류와 즉시 중단할 오류도 구분해야 합니다.

• 같은 주문번호로 생성 요청이 반복돼도 중복 데이터가 생기지 않게 합니다.

• 이벤트가 늦게 도착했을 때 최신 상태를 확인하는 규칙을 둡니다.

• 재시도 횟수와 간격을 제한합니다.

• 사람의 확인이 필요한 오류는 자동 재시도 대상에서 제외합니다.

5. 인증과 권한을 운영 기준으로 설계합니다

연동용 계정은 개인 계정 대신 용도별 전용 계정을 사용하고 필요한 API 권한만 부여하는 편이 안전합니다. 키와 토큰의 보관 위치, 교체 방법, 접근 기록도 정해야 합니다. 고객 연락처나 결제 정보처럼 민감한 데이터는 꼭 필요한 필드만 전달하고 로그에 원문이 남지 않게 합니다.

6. 실패를 발견하고 복구할 수 있어야 합니다

연동이 실패했을 때 담당자가 대상과 원인을 찾을 수 있어야 합니다. 요청 식별자, 처리 시각, 응답 결과, 마지막 성공 지점을 남기고 실패 목록에서 한 건만 다시 처리할 수 있게 설계하면 전체 작업을 반복하지 않아도 됩니다.

• 성공·실패 건수와 지연 시간을 확인할 수 있게 합니다.

• 실패한 데이터와 오류 원인을 함께 보관합니다.

• 재처리 전에 원본 상태가 바뀌었는지 확인합니다.

• 장애가 끝난 뒤 누락이나 중복이 없었는지 대조합니다.

작은 거래 흐름 하나로 검증합니다

처음부터 모든 데이터를 연결하기보다 주문 생성이나 문의 접수처럼 업무 가치가 분명한 한 흐름을 고릅니다. 정상 입력뿐 아니라 중복 요청, 빈 값, 외부 서비스 지연을 실제에 가까운 데이터로 시험하고 담당자가 실패 건을 복구할 수 있는지 확인합니다.

좋은 연동은 API 문서의 길이로 판단하지 않습니다. 기준 데이터와 상태값이 명확하고, 중복과 실패를 통제하며, 운영자가 원인을 추적할 수 있을 때 비로소 업무 자산이 됩니다. 데이터 계약을 먼저 맞추는 작은 준비가 이후의 재개발과 수동 보정을 줄여 줍니다.