개발자 가이드

커넥터 API 레퍼런스

커넥터 ↔ 플랫폼 HTTP 계약이에요. 보통은 @crmforall/connect CLI와 커넥터가 알아서 호출하므로 직접 쓸 일은 드뭅니다 — 디버깅·자체 구현용 참고.

인증

설치 시 교환된 자격증명을 모든 요청에 실어요:

실제 화면 컴포넌트 — 콘솔과 항상 동일
X-Connector-Id: cfc_<uuid> Authorization: Bearer cfcs_<secret>
커넥터 인증 헤더 — 시크릿은 서버에 해시로만 저장되고, 비교는 타이밍 안전.

엔드포인트

메서드 · 경로용도인증
POST /api/auth/device/start디바이스 로그인 시작 — 기기 코드·승인 URL 발급공개
POST /api/auth/device/token승인 폴링 — 승인되면 자격증명/설치 토큰 반환공개(기기 코드)
POST /api/auth/device/approve운영자 승인 (콘솔 /device 화면)콘솔 로그인
POST /api/connections/register설치 코드/디바이스 로그인 → 자격증명 교환 (1회용)설치 코드
GET /api/projects/:id/definition고객 그룹 조건 정의 조회 (대상 산출 입력)커넥터
POST /api/sends발송 작업 보고 (대상 스냅샷 해시 포함)커넥터
PATCH /api/sends/:jobId수신자별 결과 갱신커넥터
POST /api/engagements반응 보고 (클릭·예약·픽업 — 전환 귀속)커넥터
POST /api/links단축링크 발급 (URL에 개인정보 비노출)커넥터
POST /api/approvals/consume승인 토큰 검증·소모 (쓰기 작업 직전)커넥터 + 승인 토큰
GET /api/guide/connect-status?token=…설치 완료 폴링 (담당자 안내 페이지)설치 코드 (공개)

승인 토큰 흐름 (쓰기 보호)

  1. 커넥터가 쓰기 작업(대상 확정·예약 기록)을 하려면 승인 토큰이 필요해요
  2. 운영자가 콘솔에서 승인하면 단회용 토큰이 발급돼요 (기본 15분 유효)
  3. 커넥터는 작업 직전 /api/approvals/consume으로 토큰을 소모 — 같은 토큰 재사용은 E_TOKEN_REUSED로 거부
  4. 토큰에는 범위(scope)·대상 스냅샷 해시가 들어 있어 승인된 그 작업 그대로만 실행돼요

에러 응답 형식

실제 화면 컴포넌트 — 콘솔과 항상 동일
{ "error": { "code": "E_TOKEN_EXPIRED", "message": "설치 토큰이 만료되었습니다…", "remedy": { "label": "…", "href": "/…" } // 선택 } }
모든 에러는 동일 구조 — remedy가 있으면 콘솔이 해결 버튼을 그려요.