팀, 워크스페이스 & 결제

API 및 웹훅

자체 소프트웨어를 NextCRM과 연결하세요. 필요한 권한만 가진 API 키를 만들고, REST API를 호출하고, 리드·작업·양식·연락처·캠페인·통화가 바뀌면 서명된 웹훅을 받을 수 있습니다.

읽는 데 9분 2026년 10월 24일 업데이트

이 페이지의 내용

각 값을 얻는 곳
API 키 만들기
키로 할 수 있는 일
첫 번째 호출
모든 연동에 적용되는 규칙
웹훅
Lora와 API
문제 해결

API 및 웹훅을 사용하면 자체 시스템(ERP, 데이터 웨어하우스, 웹사이트 백엔드, 자동화 도구)이 NextCRM 워크스페이스와 함께 작동합니다.

REST API는 리드, 연락처, 작업, 메모를 읽고 변경하며, 퍼널, 양식 제출, 캠페인, 팀원을 읽습니다.
웹훅은 새 리드나 단계 변경처럼 무언가가 일어나는 즉시 서버에 알려 줍니다.

참고: 설정 > API 및 웹훅은 워크스페이스 관리자만 열 수 있습니다. API 액세스는 Business, Agency 및 Enterprise 플랜에 포함됩니다. 다른 플랜에서는 기존 키와 엔드포인트가 계속 보이지만 새로 만들 수 없고 API 호출은 거부됩니다.

각 값을 얻는 곳

모든 값은 NextCRM 자체에서 얻습니다. 타사 계정은 필요하지 않습니다.

값	얻는 곳
API 키	설정 > API 및 웹훅 > API 키 만들기. 전체 키는 한 번만 표시됩니다. 연동(예: n8n, Zapier, Make 또는 자체 코드)에 Bearer 토큰으로 복사합니다.
서명 시크릿	웹훅 엔드포인트를 추가할 때 한 번 표시되며, 시크릿 교체 후에 다시 표시됩니다. 웹훅을 받는 서버에 저장합니다.
엔드포인트 URL	자체 시스템이나 자동화 도구에서 얻습니다. 예: n8n Webhook 노드의 프로덕션 URL. https를 사용해야 합니다.

설정 순서: 필요한 권한으로 API 키 만들기 > 첫 번째 호출 > 이벤트를 선택해 웹훅 엔드포인트 추가 > 서버에서 서명 검증 > 테스트 이벤트 보내기.

API 키 만들기

사이드바 하단의 프로필 카드를 클릭하고 설정을 선택한 다음 API 및 웹훅 카드를 엽니다(API 및 웹훅 열기). API 키 탭에 머무릅니다.
API 키 만들기를 클릭합니다.
키를 어디에 쓰는지 알 수 있는 이름을 입력합니다(예: "ERP 동기화").
권한에서 영역별로 읽기 및/또는 쓰기를 선택합니다. 연동에 꼭 필요한 것만 선택하세요.
필요하면 만료에서 만료일을 정합니다(30일, 90일, 365일 또는 날짜 지정).
키 만들기를 클릭하고 복사로 키를 바로 복사합니다.

경고: 키는 한 번만 표시됩니다. NextCRM은 키의 지문(해시)만 저장하므로 지원팀을 포함해 누구도 다시 보여 줄 수 없습니다. 잃어버렸다면 키를 취소하고 새로 만드세요.

목록에는 각 키의 접두사(예: ncrm_live_1a2b3c4d), 권한, 만든 사람, 마지막 사용 시각, 만료일이 표시됩니다. 취소를 누르면 키가 즉시 차단됩니다.

키로 할 수 있는 일

키는 워크스페이스 관리자의 권한으로 워크스페이스를 대신해 동작하되, 선택한 권한으로 제한됩니다.

권한	허용 범위
리드(읽기 / 쓰기)	리드 목록 조회와 읽기, 생성, 수정, 단계 이동, 배정, 휴지통 이동과 복원
연락처(읽기 / 쓰기)	연락처 목록 조회, 읽기, 생성, 수정, 삭제
작업(읽기 / 쓰기)	작업 목록 조회와 읽기, 생성, 수정, 완료, 보관
퍼널 및 단계(읽기)	퍼널과 그 단계 읽기
양식 제출(읽기)	양식과 제출 내용 읽기
캠페인(읽기)	캠페인과 결과 읽기
메모 및 활동(읽기 / 쓰기)	리드의 메모와 타임라인 읽기, 메모 추가와 통화 기록
팀원(읽기)	팀원의 이름, 이메일, 역할 읽기(리드와 작업 배정용)
웹훅(읽기 / 쓰기)	웹훅 엔드포인트 읽기, 등록, 삭제

앱과 같은 규칙이 적용됩니다. 플랜 한도(활성 리드 한도를 넘는 새 리드는 리드 인박스로 들어감), 휴지통(휴지통의 리드는 복원해야 수정할 수 있고, API로 삭제하면 항상 휴지통으로 이동), 그리고 데이터는 절대 다른 워크스페이스로 넘어가지 않습니다. 팀, 역할, 결제, API 키 관리나 영구 삭제처럼 사람만 할 수 있는 작업은 키로 할 수 없습니다. 또한 키를 만든 사람이 더 이상 워크스페이스 관리자가 아니면 키는 작동하지 않습니다.

키로 변경한 내용은 리드 타임라인에 **API key <이름>**으로 표시됩니다.

첫 번째 호출

키를 Authorization 헤더로 보냅니다. 기본 URL은 https://…/api/v1입니다.

curl https://…/api/v1/leads?limit=10 \
  -H "Authorization: Bearer ncrm_live_..."

리드 만들기:

curl -X POST https://…/api/v1/leads \
  -H "Authorization: Bearer ncrm_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2a10-order-4711" \
  -d '{"first_name":"Ada","last_name":"Lovelace","email":"ada@example.com","value":12000}'

모든 엔드포인트, 필드, curl 예제가 담긴 전체 레퍼런스는 API 문서 탭에 있으며, https://…/api/v1/docs 에 공개되어 있고 OpenAPI 3.1 파일은 https://…/api/v1/openapi.json 입니다.

모든 연동에 적용되는 규칙

응답은 { "data": ..., "meta": { ... } }, 오류는 { "error": { "code", "message", "details" } } 형식이며 검증 오류에는 필드 목록이 포함됩니다. 날짜는 ISO 8601(UTC)입니다.
페이지 나누기: 목록은 meta.next_cursor를 반환합니다. 다음 페이지는 이를 cursor로 보내서 가져옵니다(limit 최대 100).
멱등성: POST 요청에 Idempotency-Key 헤더를 보내세요. 같은 키로 다시 시도하면 중복을 만들지 않고 첫 결과를 돌려줍니다(24시간 동안).
요청 제한: 키당 분당 120건, 워크스페이스당 분당 600건입니다. 초과하면 API가 Retry-After 헤더와 함께 429를 반환하므로 그 초만큼 기다리세요.
유지보수: NextCRM 업데이트 중에는 API가 Retry-After와 함께 503 MAINTENANCE를 반환합니다. 웹훅은 보류되었다가 이후에 전송됩니다.
서버에서만: API는 서버에서 호출하세요. 브라우저에서는 호출할 수 없으며(CORS 없음) API 키를 웹사이트나 앱에 넣으면 안 됩니다.

웹훅

웹훅 탭을 열고 엔드포인트 추가를 클릭합니다.
서버의 엔드포인트 URL을 입력합니다. https://로 시작하고 인터넷에서 접근할 수 있어야 하며, 내부·사설·클라우드 메타데이터 주소는 거부됩니다.
원하는 이벤트를 선택하고 엔드포인트 저장을 클릭합니다.
서명 시크릿(한 번만 표시)을 복사해 서버에 저장합니다.
테스트 이벤트 보내기를 클릭해 서버가 응답하는지 확인합니다.

사용할 수 있는 이벤트: lead.created, lead.updated, lead.stage_changed, lead.assigned, lead.trashed, lead.restored, task.created, task.completed, form.submitted, contact.created, contact.updated, campaign.sent, call.logged, nps.responded, customer.renewal_updated, customer.at_risk, booking.created, booking.rescheduled, booking.canceled, quote.sent, quote.accepted, quote.declined, automation.webhook.

견적서 이벤트의 금액은 통화의 최소 단위(예: 센트)의 정수입니다. subtotal_minor는 항목 할인 후 항목의 합계, discount_minor는 견적서 전체 할인, tax_minor는 세금, total_minor는 결제할 금액입니다. 각 항목의 total_minor는 항목 할인 후, 견적서 할인과 세금 전의 금액입니다.

파일 가져오기로 생성된 리드는 가져오기가 끝난 뒤 가져온 리드마다 lead.created를 하나씩 보내며, data 옆에 "context": { "source": "import", "import_batch_id": "..." }가 포함됩니다.

각 전송은 이벤트를 JSON(id, type, created_at, actor, data)으로 담은 POST이며, X-NextCRM-Event, X-NextCRM-Delivery, X-NextCRM-Timestamp, X-NextCRM-Signature 헤더가 포함됩니다.

서명 검증

X-NextCRM-Signature는 t=1760860800,v1=5f2b... 형식입니다. 서명 시크릿으로 <t>.<원본 요청 본문>의 HMAC-SHA256을 계산해 v1과 비교하세요. 타임스탬프가 5분보다 오래된 요청은 거부하세요.

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const t = Number(/(?:^|,)t=(\d+)/.exec(header)?.[1]);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return header.split(",").some((part) => part === `v1=${expected}`);
}

재시도, 전송 기록, 시크릿 교체

10초 안에 아무 2xx 상태로 응답하세요. 그렇지 않으면 NextCRM이 점점 긴 간격(1, 2, 4, ... 분)으로 최대 8번까지 다시 시도합니다.
전송 기록에는 각 전송의 상태, 시도 횟수, 응답 코드가 표시됩니다. 다시 보내기로 전송을 다시 대기열에 넣을 수 있습니다.
연속 실패가 많으면 엔드포인트가 자동으로 비활성화되고 모든 워크스페이스 관리자에게 알림이 갑니다. 엔드포인트를 고친 뒤 활성화를 클릭하세요.
시크릿 교체는 새 서명 시크릿을 만듭니다. 이전 시크릿도 24시간 동안 계속 서명하므로 이벤트를 잃지 않고 전환할 수 있습니다.

Lora와 API

Lora는 API를 설명하고, 이 페이지를 열고, 웹훅 엔드포인트 목록을 보여 줄 수 있습니다. API 키를 만들거나 보여 주거나 취소하지 않으며 서명 시크릿도 보지 않습니다. 이런 작업은 이 페이지에서 직접 하세요.

문제 해결

응답	의미
`401 INVALID_API_KEY`, `API_KEY_REVOKED`, `API_KEY_EXPIRED`	키가 잘못되었거나 취소되었거나 만료되었습니다. 새 키를 만드세요.
`403 INSUFFICIENT_SCOPE`	키에 이 호출에 필요한 권한이 없습니다. 필요한 권한이 있는 키를 만드세요.
`403 API_KEY_OWNER_NOT_ADMIN`	키를 만든 사람이 더 이상 워크스페이스 관리자가 아닙니다. 현재 관리자가 새 키를 만들어야 합니다.
`402 FEATURE_NOT_IN_PLAN`	플랜에 API 액세스가 포함되어 있지 않습니다.
`409 LEAD_IN_TRASH`	먼저 리드를 복원하세요(`POST /leads/{id}/restore`).
`422 VALIDATION_FAILED`	필드와 이유는 `error.details`에 있습니다.
`429 RATE_LIMITED`	`Retry-After` 초만큼 기다린 뒤 계속하세요.

전체 가이드