API
비공개 엔드포인트는 없습니다. 인터페이스를 위해서도 없어요.
대부분의 제품에는 두 개의 API가 있습니다. 공개적으로 제공되는 문서화된 API와, 자체 화면이 사용하는 숨은 API죠. 두 번째가 항상 더 낫고, 고객님은 결코 그것에 접근할 수 없습니다. 여기에는 하나만 있고, 인터페이스는 다른 것들과 마찬가지로 그 API의 클라이언트입니다 — 이것은 우리에 대한 제약이자, 고객님이 만들고 싶은 모든 것이 가능한 이유입니다.
이 규칙이 실제로 요구하는 것
화면이 편리한 필드 하나를 얻으려고 API를 우회하지 않고, API가 올바르기를 기다려야 할 때가 있다는 뜻입니다. 화면에 퍼블릭 API가 줄 수 없는 것이 필요해지는 날이 바로 API가 틀린 날이고, 해결책은 API를 고치는 것입니다.
그 대가로 얻는 것은, 매우 다른 세 가지 클라이언트가 거의 추가 비용 없이 동작한다는 점입니다. MCP 서버는 클라이언트입니다. dash-b 타일도 클라이언트예요. 고객님의 스크립트도 클라이언트입니다. 그중 어느 것도 남을 위해 설계된 표면을 우회하는 이등 시민이 아닙니다. 이등이 될 다른 표면이 존재하지 않으니까요.
문서화되고, 검증됨
OpenAPI가 /docs에서 생성되고, 모든 라우트에는 문서의 예시인 테스트가 있습니다. 코드와 별도로 작성된 문서는 한 달 안에 어긋나지만, 틀리면 빌드가 실패하는 문서는 그러지 않아요.
로그인
PKCE가 적용된 인가 코드 플로우를 통하는 고객님의 castomo 계정 — dash-b와 그 외 제품에서 쓰는 것과 동일한 계정입니다. 자체 서버가 없는 페이지도 이 플로우를 완벽하게 실행할 수 있어요. 이 플로우가 설계된 목적이 바로 그것이니까요. 머신 간 통신에는 프로젝트 범위의 API 키를 사용합니다.
- 1사람
/v1/contacts·/lists·/segments·/tags·/imports - 2본문
/v1/creatives— 타깃별 검증, 미리보기, 렌더링 포함 - 3자동화
/v1/funnels·/funnels/:id/versions·/runs·/simulate - 4브로드캐스트
/v1/campaigns— 오디언스, 구체화, 예약, 전송이 별개의 단계로 - 5이벤트 수신
/v1/events— 고객님 애플리케이션의 이벤트를 트리거로 - 6전달
/sender-identities·/domains·/apps·/webhooks - 7숫자
/v1/reports/*, 그리고 추적 호스트의/track/*
/docs의 OpenAPI동일 프로세스의 /mcp
규약
다른 모든 castomo 서비스와 동일한 형태
들리는 것보다 더 중요합니다. 이 중 하나를 이미 호출하고 있다면, 이 API가 어떻게 응답하고, 실패하고, 페이지네이션하는지 이미 알고 계신 거예요.
하나의 오류 엔벨로프
모든 실패는 동일한 형태, 안정적인 코드, 사람을 위한 메시지를 가집니다. 어떤 라우트도 자기만의 불평 방식을 만들지 않아요.
커서 페이지네이션
오프셋이 아닙니다. 순회하는 동안 변경되는 목록이 조용히 행을 건너뛰거나 반복하지 않아요. 오프셋 페이지네이션은 조용히, 그리고 끊임없이 그렇게 합니다.
멱등성 키
모든 변경 라우트에 적용됩니다. 도착했는지 확신할 수 없는 요청을 재시도하면, 두 번째 연락처나 두 번째 캠페인, 두 번째 전송이 아니라 동일한 답을 받습니다.
프로젝트 범위
토큰은 하나의 테넌트와 하나의 프로젝트, 둘 다를 지정합니다. 행 수준 보안은 절을 추가하는 것을 기억하는 게 아니라 데이터베이스 자체에서 강제됩니다.
웹훅 발신
서명되고, 백오프를 두고 재시도되며, 최소 한 번은 전달돼요 — 그러니 엔드포인트도 멱등(idempotent)해야 해요. 이벤트는 리포트에서 쓰는 것과 같은 어휘를 사용해요.
삭제 및 내보내기
연락처는 API를 통해 내보내거나 삭제할 수 있고, 삭제는 패밀리의 자체 내부 전용 경로를 통해 사본을 보유한 모든 형제 서비스에 전달돼요.
인터페이스가 할 수 있는 모든 것은 POST로도 할 수 있어요.
이벤트가 핵심이에요
이 페이지의 나머지는 예상할 수 있는 배관 작업이에요. POST /v1/events는 이 제품의 존재 이유를 바꾸는 경로예요.
여러분의 애플리케이션은 어떤 마케팅 도구도 관찰할 수 없는 것들을 이미 알고 있어요: 온보딩을 끝낸 사람, 동료를 초대한 사람, 한도에 도달한 사람, 일요일 오후에 데이터를 내보낸 사람. 자신만의 토큰으로 이것들을 이벤트로 게시하면, 각각이 트리거이자 조건이자 세그먼트가 돼요.
나머지는 연락처 모델에서 자연스럽게 따라 나와요. 이벤트는 추가만 되고 편집은 절대 되지 않아요; 제품 전체가 매달려 있는 로그예요. 여러분이 정의한 이벤트로 발동하는 퍼널은 통합이 아니에요 — message_opened가 쓰는 것과 동일한 메커니즘에 이름만 다른 것이에요.
- 1게시하면
POST /v1/events— 이름, 연락처, 페이로드, 멱등성 키. - 2도착하면연락처의 로그에 추가돼요. 다른 무엇도 그 존재를 알 필요가 없어요.
- 3퍼널이 시작돼요진입 조건에 그 이벤트를 명시한 모든 퍼널이, 진입 사양에 해당하는 모든 연락처에 대해 시작돼요.
- 4다른 퍼널도 분기해요"이 이벤트가 지난 14일 내에 발생했는가"는 평범한 세그먼트 조건이에요.
- i그리고 실행을 끝내기도 해요같은 이벤트를 목표로 지정한 목표 노드는 그 사람이 행동하는 순간 시퀀스를 멈춰요.
여러분의 어휘여러분의 토큰
구축 전에 알아둘 경계
ClickSomo는 여러분에 대해 세 가지 식별자 — 테넌트, 프로젝트, 사용자, 즉 불투명한 id — 만 저장하고 그 외에는 아무것도 저장하지 않아요. 비밀번호도, 프로필도, 카드도, 인보이스도 없어요. 플랜 한도는 숫자로 전달돼요: 연락처 수, 발송 수, 생성 수. 결제 어휘는 어느 방향으로도 그 선을 넘지 않아요.
여러분의 연락처는 여러분의 것이에요. 여러분이 데이터 컨트롤러이고, 우리는 처리자예요. 패밀리의 다른 제품이 여러분의 연락처 목록을 읽거나 쓸 수 있는 경로는 없고, 그렇게 쓸 수 있는 수집 경로도 없어요.
진지하게 검토 중이라면: 이 웹사이트를 더 읽기 전에 /docs를 먼저 읽어 주세요. API가 이 제품이 하는 일에 대한 정직한 설명이고, 이 페이지들의 모든 주장은 거기서 찾을 수 있는 경로나 노드 종류에 대응해요. 스키마가 바뀌면 이 페이지들도 바뀌어요.