API 변경사항을 검토하고 고객사에 전달하는 방법

01. 변경 기준과 전달 대상을 정하세요

공식 문서의 현재 버전과 배포 문서의 외부 제공 버전을 먼저 확인합니다. 내부 공식 문서가 최신이어도 외부에는 이전 배포본을 유지할 수 있습니다.

연습용 주문 API 샘플의 응답 설명 하나를 바꾸는 작업부터 시작하세요. 필수 필드 추가, 타입 변경, 오류 코드 추가처럼 연동에 영향을 주는 변경은 영향 받는 고객사와 전환 계획도 함께 기록합니다.

변경안 메뉴에서 대상 문서의 수정본을 만들고 수정합니다. 문서 설명, 필드 타입, 필수 여부와 예제 중 바뀌는 항목을 함께 맞춰 주세요.

AI가 제안한 수정 내용도 실제 구현과 대조한 뒤 반영합니다. 이전 버전의 예제가 새 필드 정의와 충돌하지 않는지 확인하고, 준비가 끝나면 검토 요청을 보냅니다.

검토자는 변경 검토 메뉴에서 기준 문서와 수정본을 비교합니다. 추가·삭제·변경된 필드와 설명을 확인하고, 문제가 있으면 반려하여 수정 요청을 남깁니다.

검토가 끝나면 승인합니다. 승인은 공식 문서에 반영하기 위한 단계이며, 고객사가 보는 외부 배포 버전을 선택하는 작업과는 구분됩니다.

배포 문서에서 외부에 제공할 버전을 확인하고 배포합니다. 아직 고객사에 공개하면 안 되는 변경이라면 기존 배포본을 유지하세요.

새 버전이 배포되면 이미 수락된 공유와 해당 공개 링크에는 최신 배포본이 반영됩니다. 고객사가 이미 내려받은 파일까지 자동으로 바뀌는 것은 아니므로 파일 전달이 필요한 경우에는 별도 재전달이 필요합니다.

공유 버전 현황에서 전달 대상, 문서와 수락 상태를 확인합니다. 직접 공유는 지정한 사용자나 워크스페이스가 수락한 뒤 확인하는 방식입니다.

공개 링크를 쓰면 상대방은 계정 없이 열람할 수 있습니다. 필요한 문서만 포함하고 비밀번호·만료일을 설정한 뒤, 수신자와 같은 조건으로 링크를 확인하세요. 연동에 영향을 주는 변경은 별도 안내 채널에서도 알리는 것이 좋습니다.

문서를 수정하면 고객사 화면도 바로 바뀌나요?

수정본과 외부 배포본은 분리됩니다. 외부에 제공할 새 버전을 배포하면 수락된 공유와 해당 공개 링크에 반영됩니다. 내려받은 파일은 자동 갱신되지 않습니다.

AI가 정확한 변경인지 승인해 주나요?

아닙니다. 이 흐름의 비교·승인 주체는 권한을 가진 사용자입니다. AI 생성 결과나 변경 제안의 정확성을 개발자가 확인해야 합니다.