개발자 문서 · API 레퍼런스 · 최종 수정 2026-08-16

🔑 인증과 리드 인입 API

외부 폼·챗봇·웹사이트의 리드/문의를 sufly® CRM으로 밀어 넣는 공개 API 레퍼런스입니다.

1️⃣ 인증

모든 요청은 조직이 발급한 API 키로 인증합니다.

API 키 발급 (앱에서) - 조직 관리자가 테넌트 관리 > 연동 > API 키에서 발급합니다.

scope: inbound:write(기본)
발급 시 원문 키는 그 한 번만 표시됩니다(저장은 SHA-256 해시). 안전한 곳에 보관하세요.
폐기하면 즉시 무효화됩니다.

인증 헤더 - 아래 둘 중 하나를 씁니다(동일 효과):

X-API-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

키가 어느 조직 것인지로 인입 대상 조직이 결정됩니다. 키 없음·오류 시 401.

레이트리밋 - 발신 IP 기준으로 제한이 걸립니다. 초과 시 429(잠시 후 재시도). 대량 전송은 지수 백오프를 권장합니다.

2️⃣ 리드 인입 - POST /api/webhooks/inbound

외부에서 받은 문의를 CRM 리드(또는 사전 리드 수신함)로 넣습니다.

Base URL: https://pp.sufly.net
Content-Type: application/json

요청 필드

필드	타입	필수	설명
`externalId`	string(1-200)	✅	보낸 쪽의 고유 ID. 멱등 키 - 같은 `externalId` 재전송은 중복 생성되지 않습니다
`source`	string(1-50)	✅	유입 출처 식별(예: `homepage-form`, `chatbot`)
`category`	string	-	문의 분류(예: `sales`, `tech_support`). `tech_support`는 리드가 아니라 지원 경로로 갑니다
`completeness`	`full` 또는 `partial`	- (기본 `partial`)	`full`=바로 리드 생성, `partial`=사전 리드 수신함(보강 후 승격)
`contact.company`	string(≤200)	-	회사명
`contact.name`	string(≤100)	-	담당자명
`contact.phone`	string(≤30)	-	연락처
`contact.email`	string(email, ≤200)	-	이메일(형식 검증)
`detail.message`	string(≤10000)	-	문의 본문
`detail.answers`	array of `{label, value}`	-	폼 항목별 질문/답변 쌍
`consent`	object	-	수집·마케팅 동의 정보
`meta`	object	-	임의 부가 정보(그대로 보관)

라우팅 규칙 - completeness="full"이고 category가 tech_support가 아니면 리드 직접 생성. 그 밖(부분·지원 성격)은 사전 리드 수신함에 쌓였다가 사람이 보강·승격합니다. 회사는 이름으로 자동 match-or-create 됩니다.

요청 예제

curl -X POST https://pp.sufly.net/api/webhooks/inbound \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "web-2026-000123",
    "source": "homepage-form",
    "category": "sales",
    "completeness": "full",
    "contact": {
      "company": "샘플컴퍼니",
      "name": "홍길동",
      "phone": "010-1234-5678",
      "email": "hong@example.com"
    },
    "detail": {
      "message": "도입 견적 문의드립니다.",
      "answers": [
        { "label": "관심 제품", "value": "CRM" },
        { "label": "팀 규모", "value": "20명" }
      ]
    },
    "consent": { "marketing": true }
  }'

응답

201 Created - 인입 성공

{ "success": true, "id": 12345, "type": "lead", "deduped": false }

type: lead(직접 생성) 또는 사전 리드 수신함 적재. deduped: 같은 externalId로 이미 있던 건이면 true.

400 Bad Request - 검증 실패

{ "success": false, "error": "입력 데이터가 올바르지 않습니다",
  "details": [ { "field": "contact.email", "message": "유효한 이메일이 아닙니다" } ] }

코드	의미	대응
`401`	키 없음/오류	키·헤더 확인
`429`	레이트리밋 초과	잠시 후 재시도(지수 백오프)
`500`	서버 처리 오류	재시도 가능

3️⃣ 멱등성 · 재시도

멱등 키는 `externalId`(조직 범위)입니다. 네트워크 오류로 같은 요청을 다시 보내도 리드가 두 번 만들어지지 않습니다 - 보낸 쪽에서 각 문의에 고유한 externalId를 반드시 부여하세요.
5xx·429는 지수 백오프로 재시도합니다. 4xx(검증)는 재시도해도 같은 실패입니다 - 요청을 고치세요.

🚀 다음 단계

👉 고객지원 위젯 문의를 티켓으로 접수하려면 웹훅과 연동을 확인하세요.