API 연동 명세서에 담을 구현 범위와 담당자별 완료 조건

“견적서에 API 연동이 포함돼 있는데, 관리자 화면에서 결과를 확인하는 것까지 해주는 걸까요?”

“외부 서비스 때문에 연결이 안 되면, 저희와 개발사 중 누가 먼저 확인해야 하나요?”

API 연동 범위는 업무별로 시작 조건과 완료 상태를 정하고, 그 사이에 필요한 준비와 구현, 확인 작업의 담당자를 연결해 문서화해야 합니다. 각 연동 업무에 ‘누가 무엇을 준비하고, 어떤 결과를 확인하면 끝나는가’가 적혀 있어야 범위를 판단할 수 있습니다.

저는 크로플에서 웹과 앱 수탁개발의 개발 총괄과 PM 역할을 함께 맡고 있습니다. 50건 이상의 SI 수탁개발과 Shopify API 기반 패션 마켓플레이스 앱 운영을 거치며, 구현할 기능만큼 구현하지 않을 범위를 명확히 적는 데 무게를 두고 있습니다.

이 글에서 말하는 책임은 계정 준비, 개발, 검수, 장애 확인 같은 업무의 담당 범위입니다. 손해배상이나 면책 등 법적 책임을 정하는 문구와는 구분해서 읽어주세요.

API 연동 범위는 어디서 시작하고 어디서 끝나나요?

API 연동 범위는 외부 서비스 이름이 아니라 업무의 시작과 끝을 기준으로 적어야 합니다. 호출 성공 이후의 저장, 화면 표시, 재처리까지 포함되는지도 각각 밝혀야 합니다.

‘배송 API 연동’이라는 항목만 보면 발주사는 송장 등록과 배송 상태 표시를 떠올릴 수 있습니다. 개발사는 송장 번호를 외부 서비스에 전달하는 작업으로 이해할 수도 있습니다. 같은 이름 아래 서로 다른 완료 상태를 생각하는 것입니다.

저는 이때 API 목록부터 늘리기보다 사용자의 행동을 한 문장으로 적습니다. 그다음 데이터가 어디서 출발해 어디에 반영되는지 연결합니다. 연동 범위를 정할 때 업무 흐름, 데이터 매핑, 호출 조건, 제외 범위를 함께 기록하는 방식은 누락된 작업과 시스템 간 경계를 검토하는 데 도움이 됩니다.

다음은 배송 연동을 가정한 작성 예시입니다. 실제 제공 기능은 해당 서비스의 명세를 확인한 뒤 확정해야 합니다.

범위 협의 중 한 고객은 외부 서비스에 주문을 전송하면 관리자 화면의 상태도 자동으로 바뀐다고 생각했습니다. 저는 전송 성공과 내부 상태 변경을 서로 다른 작업으로 나눠 설명하고, 화면 반영까지 완료 조건에 포함해 정리했습니다. 그 뒤 논의의 초점이 ‘연동이 되느냐’에서 ‘어떤 상태가 보여야 하느냐’로 바뀌었습니다.

이처럼 업무 문장의 마지막에는 결과가 남아야 합니다. ‘조회한다’, ‘연결한다’에서 끝내지 말고 무엇이 저장되거나 표시되는지까지 적어보세요.

발주사와 개발사의 담당 업무는 어떻게 나누나요?

회사별 역할을 크게 나누기보다, 연동에 필요한 준비물과 산출물마다 수행 담당자와 확인 담당자를 지정하세요. 외부 제공자의 승인처럼 양쪽이 직접 통제할 수 없는 조건도 따로 표시해야 합니다.

‘API는 발주사 제공, 연동은 개발사 수행’이라는 문장에는 빈칸이 많습니다. 계정은 있지만 운영 권한이 없을 수도 있고, 테스트는 가능하지만 실제 호출에 별도 승인이 필요할 수도 있습니다. 이런 조건을 누가 확인할지 정하지 않으면 개발 중에 일정이 멈춘 이유조차 설명하기 어려워집니다.

제가 구현 브리프를 작성할 때 적용하는 원칙은 준비 업무에도 결과물을 붙이는 것입니다. ‘인증 준비’보다는 ‘운영 계정의 필요한 권한을 확인하고 접근 가능 여부를 개발 담당자에게 전달한다’가 판단하기 쉽습니다.

문서에는 다음 항목을 한 묶음으로 남기면 됩니다.

• 준비 담당자: 계정 생성, 이용 신청, 외부 제공자 문의를 수행할 사람
• 구현 담당자: 인증 처리, 데이터 변환, 응답 저장을 구현할 사람
• 확인 담당자: 업무 규칙과 최종 화면 결과를 승인할 사람
• 선행 조건: 운영 권한 승인, 테스트 데이터 제공 등 착수에 필요한 조건
• 미충족 시 결정자: 기다릴지, 대체 테스트를 할지, 출시 범위를 조정할지 결정할 사람

예를 들어 운영 계정 발급을 발주사가 맡기로 했다면, 단순히 발급 예정일만 적지 않습니다. 발급 지연 시 개발사가 어디까지 진행하고, 실제 운영 검증은 언제 다시 할지도 함께 합의합니다. 테스트용 대체 응답으로 화면을 완성한 것과 실제 서비스에 연결한 것은 완료 상태가 다르기 때문입니다.

인증키 값 자체를 협의 문서에 붙일 필요는 없습니다. 문서에는 보관 위치와 전달 절차, 접근 담당자만 적고 실제 비밀값은 별도로 관리하는 방식으로 설계하세요.

외부 API가 실패하면 누가 무엇을 해야 하나요?

실패 대응은 원인 조사와 서비스 복구 행동을 나눠 적어야 합니다. 원인이 확정되기 전에도 누가 첫 확인을 하고 사용자에게 어떤 상태를 보여줄지는 정할 수 있습니다.

외부 서비스 장애라는 이유만으로 내부에서 할 일이 없어지는 것은 아닙니다. 반대로 내부 호출이 실패했다고 해서 개발 코드의 문제라고 바로 판단할 수도 없습니다. 먼저 확인할 기록과 다음 행동이 필요합니다.

저는 실패 처리 항목을 다음 순서로 구체화합니다. 요청을 식별할 수 있는 기록을 남기는지, 운영 화면에서 실패 건을 찾을 수 있는지, 수동 재처리가 필요한지, 외부 제공자에게 문의할 담당자가 누구인지 정합니다. 각 행동의 포함 여부와 구현 담당자를 함께 적는 것이 핵심입니다.

특히 타임아웃은 ‘외부에서 처리하지 않았다’는 뜻으로 단정하면 안 됩니다. 외부에서 처리는 끝났지만 응답을 받지 못했을 가능성도 고려해야 합니다. HTTP 요청의 자동 재시도는 멱등성과 실제 작업의 중복 방지 조건을 확인해 설계해야 하며, 비멱등 요청을 조건 없이 재전송하는 방식은 피해야 합니다.

멱등성은 같은 요청을 여러 번 수행해도 의도한 최종 효과가 한 번 수행한 것과 같다는 성질입니다. 주문 생성이나 결제처럼 중복 실행을 구분해야 하는 작업에서는 제공 API의 중복 방지 수단과 처리 결과 조회 방법을 확인해야 합니다.

문서에는 ‘실패 시 재시도’ 한 줄 대신 다음처럼 행동을 적습니다.

응답을 받지 못한 요청은 확인 필요 상태로 표시한다. 자동 재시도 여부는 제공 API의 처리 특성을 확인한 뒤 확정한다. 운영 담당자는 처리 결과를 확인하고 재처리 여부를 판단한다.

이 문장만으로 구현이 끝나는 것은 아닙니다. 확인 필요 상태를 저장할지, 관리자에게 보여줄지, 누가 재처리할지까지 앞서 정한 범위와 연결해야 합니다. 재처리 화면이 제외라면 그 대신 사용할 운영 절차도 남겨두세요.

연동 완료는 어떤 증거로 검수하나요?

연동 검수는 정상 응답 하나가 아니라 합의한 업무 결과를 확인하는 방식으로 설계하세요. 테스트 환경 검증과 실제 운영 환경 검증도 구분해 기록해야 합니다.

API 호출이 성공해도 잘못된 주문에 결과가 저장되거나 사용자가 상태를 확인하지 못하면 기대한 업무는 끝나지 않습니다. 그래서 저는 구현 브리프의 완료 조건을 그대로 검수 항목으로 연결합니다.

연동 검수에는 정상 흐름뿐 아니라 인증 실패, 잘못된 입력, 응답 지연, 중복 요청 등 해당 업무에 중요한 예외 조건과 기대 결과를 포함하는 것이 적절합니다. 다만 모든 예외를 같은 깊이로 시험하기보다 실제 사용하는 기능과 위험에 맞춰 선정해야 합니다.

검수 항목은 다음 순서로 작성할 수 있습니다.

1. 전제: 어떤 환경과 권한, 테스트 데이터를 사용하는지 적습니다.
2. 행동: 누가 어떤 화면이나 작업으로 요청을 발생시키는지 적습니다.
3. 기대 결과: 외부 처리 결과와 내부 저장 상태, 화면 표시를 적습니다.
4. 확인 기록: 실행 시각, 요청 식별자, 민감정보를 가린 결과 기록을 연결합니다.
5. 승인과 잔여 항목: 확인자와 미검증 조건, 후속 확인 일정을 남깁니다.

외부 서비스가 특정 오류를 테스트 환경에서 재현하도록 지원하지 않는다면, 내부 대체 응답으로 검증한 부분과 실제 서비스에서 확인한 부분을 구분합니다. 대체 응답 테스트는 내부 처리 로직을 살피는 데 쓸 수 있지만 실제 연결 확인을 대신했다고 표시하지는 않습니다.

범위 문서와 검수 문서의 항목 이름도 맞추는 편이 좋습니다. 저는 시스템 설계에서 하나의 기준을 여러 곳에서 일관되게 참조하는 방식을 중시합니다. ‘송장 번호 저장과 표시’라는 범위가 있다면 동일한 이름의 검수 항목과 변경 기록으로 이어지도록 구성합니다.

결론

API 연동 문서는 업무별 완료 조건을 중심으로 범위와 담당자를 연결해야 실제 판단에 사용할 수 있습니다.

작성 중인 문서에서 연동 항목 하나를 골라보세요. 시작 조건, 저장하거나 표시할 결과, 준비 담당자, 실패 시 행동, 검수 증거를 차례로 채우면 됩니다. 비어 있는 칸은 착수 전에 확인할 질문입니다.

크로플에서 개발과 PM을 함께 맡으며 제가 구현 브리프에 남기려는 것도 이 연결입니다. 기능의 이름보다 완료를 확인할 수 있는 문장이 발주사와 개발사의 기대를 맞추는 기준이 됩니다.

자주 묻는 질문

외부 제공자의 API 문서만 전달하면 충분한가요?

충분하지 않습니다. 제공자의 문서는 호출 가능한 기능과 기술 조건을 설명하지만, 우리 프로젝트에서 어떤 기능을 사용하고 어떤 화면까지 구현할지는 별도로 정해야 합니다. 기술 문서를 첨부하고 프로젝트의 업무 범위를 연결해두세요.

개발 중 외부 API 버전이 바뀌면 어떻게 기록하나요?

기존 합의 버전과 변경 내용을 먼저 남기고, 영향받는 범위와 재검수 항목을 검토해야 합니다. 대응 일정과 추가 작업 여부를 결정한 뒤 문서 이력에 승인 내용을 기록하는 방식으로 협의할 수 있습니다.

작은 프로젝트도 별도 연동 명세서가 필요한가요?

작은 프로젝트는 기존 요구사항 문서 안에 연동 항목을 넣어도 됩니다. 문서를 늘리는 것보다 범위, 담당자, 완료 조건이 한곳에서 확인되고 최신 내용으로 유지되는지가 중요합니다.

제 도움이 필요하시다면

외부 API 문서는 받았지만 견적 범위나 담당 업무를 정하기 어렵다면, 업무 흐름을 기준으로 구현 브리프를 구체화하는 도움을 드릴 수 있습니다.

크로플은 웹과 앱, 업무 시스템 수탁개발과 프로젝트 관리를 수행합니다. 연동할 기능의 포함 범위와 제외 범위를 정리하거나, 계정 준비부터 구현과 검수까지 담당 업무를 연결하거나, 이미 진행 중인 개발의 완료 조건을 다시 맞춰야 할 때 함께 검토할 수 있습니다.

연동하려는 서비스의 기술 문서와 현재 요구사항, 아직 합의하지 못한 항목을 준비해주시면 어디부터 결정해야 할지 논의하기 좋습니다.