시스템 연동 가이드
연결 범위와 실패 처리 방법을 확인할 수 있는 서버 연동을 만드세요.
연결할 고객 업무 한 가지를 정한 뒤 인증, 워크스페이스 범위, 권한, 요청 ID, 재시도, 오류 처리, 감사 기록, 미처리 업무 담당자를 정의합니다.
연동 구현 체크리스트
인증 정보는 서버에만 보관
제공된 인증 정보는 비밀 저장소에서 불러오고 브라우저 코드에는 넣지 마세요.
워크스페이스 지정
해당 고객사와 작업에 승인된 워크스페이스 정보만 사용합니다.
응답 제한 시간 설정
모든 외부 호출에 제한 시간을 설정하고 시간 초과를 성공으로 처리하지 마세요.
요청 추적 ID 기록
세일링고 요청 ID와 민감하지 않은 고객사 추적 ID를 함께 저장합니다.
요청과 처리 결과
const response = await fetch(`${origin}/knowledge/facts`, {
headers: { Authorization: `Bearer ${token}` },
signal: AbortSignal.timeout(5000)
});if (!response.ok) {
const failure = await decodeFailure(response);
return handleByStatus(failure);
}오류별 대응 방법
| 상태 | 의미 | 연동 측 조치 |
|---|---|---|
| 401 | 인증 정보가 없거나 만료되었거나 올바르지 않음 | 요청을 중지하고 승인된 서버 절차로 인증 정보를 갱신합니다. |
| 403 | 요청한 작업에 필요한 권한 또는 범위가 없음 | 다시 시도하지 말고 접근 권한 검토를 요청합니다. |
| 409 | 상태, 버전, 중복 처리 방지 키, 승인 상태가 충돌함 | 충돌 내용을 확인하고 상태를 맞춘 뒤 다음 요청을 보냅니다. |
| 422 | 요청 형식이 공개된 스키마와 일치하지 않음 | 오류에 표시된 필드를 수정한 뒤 다시 요청합니다. |
| 429 | 짧은 시간에 요청을 너무 많이 보냄 | 응답에 안내된 대기 시간에 맞춰 요청 간격을 늘립니다. |
| 5xx | 일시적인 서비스 오류가 발생했을 수 있음 | 요청 ID를 보관하고 해당 작업이 재시도를 허용할 때만 다시 시도합니다. |