5분영업이 발굴한 리드를 손으로 옮겨 적고 있다면, API로 자동화할 차례입니다. 이 가이드는 발굴된 리드를 HubSpot이나 자체 CRM으로 동기화하는 일반적인 연동 패턴을 다룹니다. 엔드포인트의 정확한 스펙은 API 문서를 기준으로 하고, 여기서는 어떤 구조로 연결하는지에 집중합니다.
연동 코드는 받은 데이터를 외부 시스템에 쓰는 작업입니다. 운영에 붙이기 전 반드시 테스트 환경에서 충분히 검증하세요.
인증 — API 키로 토큰 발급
연동의 시작은 인증입니다. 발급받은 API 키·시크릿으로 단기 액세스 토큰을 받고, 이후 요청 헤더에 그 토큰을 실어 보냅니다.
POST /v1/auth/token { api_key, api_secret } → { token_type: "Bearer", access_token, ... }
- 토큰은 유효기간이 짧으므로(문서 기준 1시간), 만료되면 자동 재발급하는 로직을 넣으세요
- API 키·시크릿은 코드에 하드코딩하지 말고 환경변수·시크릿 저장소에 두세요. 유출되면 즉시 폐기·재발급해야 합니다
- 먼저 샌드박스 베이스 URL로 붙여 본 뒤, 검증이 끝나면 운영으로 전환하는 것을 권합니다
리드 가져오기 — 폴링 패턴
가장 단순하고 안정적인 연동은 주기적으로 새 리드를 조회(폴링)하는 방식입니다.
GET /v1/leads?status=new&limit=50 (Authorization: Bearer …)
- 일정 주기(예: 15분)마다 호출해, 마지막으로 가져온 시점 이후의 새 리드만 받아옵니다
- 한 번에 다 받으려 하지 말고
limit으로 페이지를 나눠, 끝까지 페이징하세요 - 특정 조건의 업체만 필요하면
/v1/leads/search로 좁혀 조회하고, 결과는 폴링으로 받습니다(문서 참조)
폴링은 웹훅보다 단순하고, 받는 쪽 장애에 강합니다. 실패하면 다음 주기에 다시 시도하면 되므로 유실 위험이 낮습니다.
CRM에 쓰기 — 매핑과 중복 방지
가져온 리드를 CRM에 넣을 때 두 가지를 설계해야 합니다.
| 설계 항목 | 내용 |
|---|---|
| 필드 매핑 | 상호→회사명, 이메일·전화→연락처, 지역·업종→속성 등 |
| 중복 키 | 같은 업체를 두 번 만들지 않도록 유니크 키를 정함 |
중복 방지가 핵심입니다. 이메일이나 전화번호처럼 변하지 않는 값을 유니크 키로 잡고, CRM에 이미 있으면 새로 만들지 말고 갱신(upsert)하세요. 이걸 빼먹으면 폴링이 돌 때마다 같은 업체가 쌓입니다.
- HubSpot 등은 보통 "이메일 기준 upsert"를 지원하므로 그 기능을 활용하세요
- 5분영업 쪽 리드 ID도 CRM 속성으로 함께 저장하면, 이후 양방향 대조가 쉬워집니다
안정적으로 운영하기
연동을 붙였다면, 깨졌을 때 조용히 멈추지 않도록 운영 장치를 마련하세요.
- 레이트 리밋·오류 처리: 429·5xx 응답에는 지수 백오프로 재시도하고, 반복 실패는 알림으로 띄웁니다
- 재시도 안전성(멱등성): 같은 리드를 두 번 처리해도 결과가 같도록 — 중복 키 upsert가 이를 보장합니다
- 동기화 로그: 마지막 성공 시각·건수를 기록해, 멈춤을 빨리 알아챕니다
- 토큰 만료 대응: 401이 오면 토큰을 재발급하고 한 번 재시도
연동을 어디까지 자동화할까
모든 것을 자동화할 필요는 없습니다. 보통은 발굴된 리드를 CRM으로 가져오는 단방향만으로도 손작업의 대부분이 사라집니다. 발송·상담 같은 행위는 사람의 판단이 필요한 영역이므로, 데이터는 자동으로 동기화하되 연락 여부는 사람이 결정하는 구조가 안전하고 실용적입니다.
정확한 엔드포인트·파라미터·응답 형식은 항상 API 문서의 최신 내용을 기준으로 구현하세요. 이 가이드의 패턴은 그 위에 얹는 설계 골격입니다.