채팅 위젯

이 그룹은 고객 웹사이트에서 임베디드 채팅 위젯이 사용하는 모든 공개 엔드포인트를 묶습니다: 상태 확인(`GET /api/public/widget/health`), 공개 위젯 구성 가져오기(`GET /api/public/widget/config/:widget_code`), 그리고 메시지 전송 및 내역(`POST /api/public/widget/message`, `GET /api/public/widget/history`). 도메인 허용은 위젯 생성 시 Zentor에서 관리하며, 테넌트 대시보드에는 해당 설정 인터페이스가 없습니다. 출처(origin)가 허용되지 않은 경우 오류 코드 `WIDGET_ORIGIN_DENIED`가 발생할 수 있습니다. 위젯 생성 자체는 마스터 관리자에게만 허용되며, 테넌트는 완성된 임베딩 코드를 받습니다.

일반적인 개발자 API 키 시스템은 존재하지 않습니다. `health`와 `config`는 브라우저에서 위젯을 초기화하는 데 필요하므로 인증 없이 접근할 수 있습니다. 반면 `message`와 `history`는 `X-Widget-Token` 헤더가 필요하며, 추가로 서버 측 origin 허용 목록에 대해 검증됩니다. 임베딩 토큰은 위젯 생성 시 한 번만 평문으로 표시되며, 공개 저장소, 지원 스크린샷 또는 브라우저 로그에 나타나서는 안 됩니다.

이 그룹의 각 상세 페이지는 해당 엔드포인트의 메서드, 경로, 인증, 멱등성 및 문서화된 오류 코드를 개별적으로 설명합니다. 엔드포인트 호출이 성공했다고 해서 동일한 그룹의 다른 엔드포인트도 성공할 것이라고 자동 가정할 수 없습니다. 특히 녹색 `health` 체크는 유효한 위젯, 허용된 origin 또는 AI 제공업체의 접근 가능성을 모두 확인하지 않습니다.

플랫폼 전체의 확인된 API 제한은 15분 이내에 2,000건의 요청입니다. 개별 위젯 엔드포인트에 대해 다른 제한이 적용되는 경우, 해당 엔드포인트에 대해 명시적으로 입증된 경우에만 언급됩니다. `message`는 멱등성이 아닙니다. 클라이언트는 첫 번째 메시지가 이미 처리되었는지 확인하기 전에 불분명하게 중단된 전송 작업을 자동으로 재시도해서는 안 됩니다.

이 그룹에 대한 기술적 검증은 `app/frontend/src/content/api-reference/groups/widget.ts`의 레지스트리와 관련 백엔드 라우트에 기반합니다. 각 상세 페이지는 성공 경로가 실제로 테스트되었는지, 실패 경로가 테스트되었는지, 아니면 코드 유사성만 확인되었는지 표시합니다. 이러한 구분은 전체 그룹에 적용되며, 포괄적인 성공 주장으로 대체되어서는 안 됩니다.