💻 sufly® 개발자 문서
sufly®를 외부 시스템과 연동하려는 고객사 개발자를 위한 기술 문서입니다. 자사 웹사이트 폼·챗봇·고객지원 위젯에서 발생한 리드와 문의를 sufly® CRM/Support로 밀어 넣는 인입 API와 웹훅의 공개 계약(레퍼런스)을 다룹니다.
🔌 무엇을 연동할 수 있나요?
| 연동 표면 | 용도 | 문서 |
|---|---|---|
| 리드 인입 API | 외부 폼·챗봇·사이트에서 리드/문의를 CRM으로 전송 | 인증과 리드 인입 API |
| CS 문의 웹훅 | 외부 고객지원 위젯 문의를 Support 티켓으로 접수 | 웹훅과 연동 |
| 협업 도구 연동 (Asana 등) | 협업 도구의 태스크를 티켓으로 인입 - 코드 없이 앱에서 설정 | 웹훅과 연동 |
🔑 연동 준비 - 역할 분담
연동은 두 사람의 협업으로 완성됩니다. 설정은 앱 안에서, 계약은 이 문서로 나뉩니다.
- 조직 관리자 - sufly® 앱의 테넌트 관리 > 연동 > API 키에서 API 키를 발급합니다. 키는 발급 순간 한 번만 표시되므로 안전한 곳에 보관하세요.
- 개발자 - 이 문서의 레퍼런스를 읽고, 발급받은 키로 요청을 구현합니다.
⚠️ API 키는 서버 측에만 두세요. 브라우저 코드나 앱 번들에 키를 넣으면 누구나 볼 수 있습니다. 프런트엔드에서 직접 호출하지 말고, 자사 백엔드를 거쳐 전송하세요.
📐 계약의 공통 원칙
- 인증 - 모든 요청은 API 키 헤더(
X-API-Key또는Authorization: Bearer)로 인증합니다. - 멱등성 - 요청마다 고유한
externalId를 부여하면, 같은 요청을 재전송해도 중복 생성되지 않습니다. - 재시도 -
5xx·429응답은 지수 백오프로 재시도하고,4xx(검증 실패)는 요청을 고쳐서 보냅니다.
🚫 범위 밖 (아직 제공하지 않는 것)
- 이 API는 인입(쓰기) 전용입니다. CRM 데이터를 조회하는 아웃바운드 API는 현재 제공하지 않습니다.
- 리드 상태·기회·견적을 외부에서 읽거나 바꾸는 공개 API는 제공하지 않습니다(향후 별도 고지).
🚀 다음 단계
👉 인증과 리드 인입 API에서 첫 요청을 만들어보세요.