@roottale/cms-mcp
Version:
RootTale CMS MCP server and CLI for models, entries, exposures, media, integration docs, and public API access.
940 lines (761 loc) • 50.4 kB
Markdown
---
title: HTTP API 레퍼런스
description: 공개 API raw 엔드포인트 — JS 외 스택이나 저수준 연동용
---
# HTTP API 레퍼런스
팝업·배너의 v2 결정 조회와 수정안·예약·일시 중지 API는
[팝업·배너와 예약 표시](popups-and-banners.md)를 참고하세요.
베이스 URL: `https://api.roottale.com`
인증: 모든 요청에 `Authorization: Bearer rtlk_cust_...` 헤더.
공개 콘텐츠 조회를 JS/TS로 연동할 때는 raw 호출 대신
`/cms-client`를 사용하세요. 전체 CMS 관리는 아래 HTTP API,
MCP tool 또는 공개 CLI를 사용합니다.
tenant-api의 `GET /v1/cms/public/*` 응답에는 진단용 `Server-Timing` 헤더가 있습니다.
`total`, `auth`, `site`는 밀리초이며, `/metadata`와 `/metadata/routes`는 `context_read`, `context_parse`,
`tx`, `policy`, `projection`도 제공합니다. 같은 구간은 시간 합계와 `desc="count=N"`으로
표시하고, 실행하지 않은 구간은 count=0입니다. `contract`는 조회한 계약의 DB 저장 크기(압축 포함)
합계와 횟수입니다. 중첩 구간의 시간을 모두 더하지 마세요. Workers의 타이머 제약으로
CPU 구간은 0에 가까울 수 있습니다. 응답 본문·상태·캐시 규칙은 그대로이며, 이 헤더를
애플리케이션의 성공 판정이나 캐시 키로 사용하지 마세요.
글쓰기·미디어 자동화는 `read_write` API 키가 필요합니다. 모델·필드·노출까지
관리하려면 `full_management` 키를 권장합니다. `read` 키는 공개
콘텐츠뿐 아니라 관리 API의 초안·예약·비공개 글과 미디어 목록도 조회할 수
있습니다. 다만 **완전한 읽기 전용은 아닙니다** — 상담 게시판 글 작성
(`POST /v1/cms/public/inquiries`)과 폼별 문의 접수
(`POST /v1/public/inquiry-forms/:formId/submissions`)가 `cms:read`로 허용됩니다. 기존 글·미디어·
설정을 고치거나 지우려면 `read_write` 이상이 필요합니다.
사업장 정보·상단 메뉴를 바꾸는 일(아래 "설정 쓰기 API")은 한 단계 위인
`read_write_settings` 키가 따로 필요합니다 — 글쓰기 키로는 열리지 않습니다.
## 관리 API 빠른 흐름
공통 메타데이터는 `GET /v1/cms/metadata`로 검색·cursor 조회하고,
`GET /v1/cms/metadata/{kind}/{key}`로 현재 버전과 지원 필드를 확인합니다.
`kind`는 `route | post | term`입니다. `PATCH`는
`{ "expected_version": "조회한 version", "patch": { "title": null, "noindex": false } }`
형식이며 수정은 Pro/Premium(또는 루트테일의 사이트별 허용)과 대상별 쓰기 scope가 모두 필요합니다.
편집이 닫혀 있으면 403 `upgrade_required`(요금제)·`site_denied`(사이트별 제한)·`billing_locked`(구독 중단)를 반환합니다.
`site_id`·`locale`은 선택입니다. 본문만 수정하면 저장된 SEO를 보존합니다.
고정 경로 공개 조회는 `GET /v1/cms/public/metadata?route_key=home&locale=ko`이며
`{ "site_id": "…", "metadata": null }` 또는 camelCase `PublicRouteMetadata`를 반환합니다.
공개 응답의 `metadata`에는 `routeKey`, `locale`, `path`, `version`, `overrides`,
`defaults`, `effective`, `supportedFields`, 선택적 `fallback`과 `robots` 강제 정책이 있습니다.
공개 읽기는 등급과 관계없이 기존 설정을 사용합니다. 자세한 연동은 [공통 메타데이터](seo.md#공통-메타데이터)를 참고하세요.
관리 API는 초안 작성 → 미디어 연결 → 발행을 분리합니다. 자동화가 실수로
미완성 글을 공개하지 않도록 글 생성의 기본 상태는 `draft`입니다.
전체 리소스 경로와 권한은
[콘텐츠 모델과 노출 관리](./content-models-and-exposures.md)에 정리되어 있습니다.
### POST /v1/cms/posts
Tiptap JSON 본문으로 글 또는 페이지를 만듭니다.
```bash
curl https://api.roottale.com/v1/cms/posts \
-H "Authorization: Bearer $ROOTTALE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: post-2026-07-17-001" \
-d '{
"type": "post",
"title": "자동화로 작성한 글",
"slug": "automated-post",
"body_json": {"type":"doc","content":[]},
"author_profile_id": "site-author-id",
"featured_media_id": null,
"category_ids": [],
"tag_ids": []
}'
```
주요 필드:
| 필드 | 설명 |
|---|---|
| `body_json` | Tiptap 문서 JSON 객체 |
| `author_profile_id` | 사이트 공통 공개 작성자 ID. 생략한 사용자 키는 계정별 기본값, `null`은 미지정 |
| `featured_media_id` | 미디어 업로드 완료 응답의 `id`; `null`이면 썸네일 없음 |
| `publish` | `true`면 즉시 발행. 생략하면 초안 |
| `scheduled_at` | 미래 ISO 8601 시각. `publish`와 동시 사용 불가 |
| `category_ids`, `tag_ids` | 생성과 동시에 연결할 term ID 배열 |
| `model_key` | 페이지·글·정보 모델의 안정 key. 모델이 여러 개면 필수 |
| `field_values` | 모델 필드 정의로 검증할 편집 원문 객체 |
| `source_key` | 외부 원고의 안정 식별키(1–255자). 같은 tenant/site/key는 기존 글을 반환 |
외부 원장 연동은 제목·슬러그 대신 `source_key`를 사용합니다(예: `notion:<Page ID>`).
키는 기존 글과 같은 DB 트랜잭션에 보관하며 동시 생성도 한 글로 합칩니다.
최초 생성은 201, 같은 키의 재시도는 200으로 기존 글을 반환하고 내용을 덮어쓰지
않습니다. 휴지통에 있으면 409 `source_post_removed`이며 자동으로 복원하지 않습니다.
이는 Worker 메모리의 `Idempotency-Key` 재시도 캐시와 별개입니다. 생성은 초안으로
진행하고 응답의 ID/상태를 확인한 뒤 수정·SEO·발행을 각각 처리하세요.
`meta_json._sync`는 외부 동기화 체크포인트용으로 사용할 수 있으며 관리 응답에서만
반환하고 공개 글 목록·상세·미리보기 응답에서는 제외합니다. 인증 정보는 넣지 마세요.
### PATCH /v1/cms/posts/{post_id}
보낸 필드만 수정합니다. `featured_media_id: null`이면 썸네일을 해제하고,
`scheduled_at: null`이면 예약을 해제합니다. `author_profile_id`를 생략하면 기존
공개 작성자를 유지하고, `null`이면 초안의 공개 작성자를 비웁니다.
`expected_updated_at`에 마지막 조회의 `updated_at`을 보내면 다른 저장이 먼저
일어났을 때 409 `post_update_conflict`로 중단합니다. 충돌 후 새 버전을 읽어
수정 내용을 확인하세요. 새 버전만 바꿔 맹목적으로 재전송하면 사람이 한 수정을 덮을 수 있습니다.
### POST /v1/cms/posts/{post_id}/publish
초안 또는 예약 글을 즉시 발행하고 등록된 revalidate 웹훅을 전송합니다.
본문은 `{}` 또는 `{"site_id":"..."}`입니다. 글(`type: "post"`)은 현재
사이트의 활성 공통 작성자가 지정돼 있어야 발행·예약할 수 있습니다.
선택적 `expected_updated_at`은 본문 검사 이후 다른 저장이 발생했을 때 발행을
409 `post_update_conflict`로 중단합니다. 글 수정과 같은 조회 버전 형식입니다.
모델의 `editor.topic.required`가 `"first-publish"`이면 최초 발행·예약 전에
`meta_json.contentEditor.primaryTermId`가 같은 사이트의 `custom / content_topic`
분류여야 합니다(컬렉션 범위 없음). 누락·다른 분류이면 HTTP 400
`model_topic_required`를 반환합니다. 생성 시 `publish: true`, 예약 생성·수정에도
같이 적용됩니다. 발행 기록이 있는 글의 저장·재발행과 설정 없는 모델에는 적용하지 않습니다.
### POST /v1/cms/posts/{post_id}/unpublish
발행 글을 초안으로 되돌립니다.
### PATCH /v1/cms/posts/{post_id}/terms
특정 taxonomy의 연결을 전체 교체합니다.
```json
{"taxonomy":"category","term_ids":["term-id-1","term-id-2"]}
```
### PATCH /v1/cms/posts/{post_id}/related
글의 **관련 콘텐츠**(어드민 편집기 "관련 콘텐츠" 패널과 같은 원장)를 전체 교체합니다.
유형(모델)과 상관없이 같은 사이트의 글을 순서대로 최대 10개. 자기 자신·중복은 무시되고,
다른 사이트 글은 400. 발행 글이면 `post.updated` 웹훅이 나갑니다.
```json
{"related_post_ids":["post-id-1","post-id-2"],
"reserved_keys":["faq.headache.migraine.aura-symptoms"]}
```
`reserved_keys` = **아직 없는 콘텐츠 예약**(선택). 공개 주소 조각을 `.` 로 이은 키를 적어 두면
대상이 그 주소로 발행되는 순간 공개 `related_posts` 뒤쪽에 자동 합류합니다. 미전달이면 예약을
손대지 않고, 빈 배열이면 전부 해제합니다(최대 10개).
응답은 `related_posts`(발행 여부 무관, 순서대로, `status` 포함)입니다. 공개 응답에는 그중
**발행 글만** `related_posts` 로 나갑니다(아래 글 목록·상세 참고).
### GET /v1/cms/posts
초안·예약·비공개·발행 글을 조회합니다. 쿼리는 `limit`, `cursor`, `type`,
`status`, `site_id`, `model_key`를 지원합니다.
관리 응답은 `owner_user_id`(편집 소유 계정)와
`author_profile_id`(사이트 공통 공개 작성자)를 별도로 반환합니다. 기존
`author_id`는 하위 호환용이며 새 연동에서는 두 분리 필드를 사용하세요.
## 미디어 업로드 API
API가 발급한 5분 유효 업로드 URL로 파일을 전송한 뒤 CMS에 등록합니다. 허용 형식은 JPEG, PNG, WebP, GIF, PDF이며
최대 10MB입니다.
### 1. POST /v1/cms/media/uploads
```json
{
"original_name": "hero.webp",
"content_type": "image/webp",
"size_bytes": 482031
}
```
응답의 `upload_url`, `r2_key`, `expires_in`을 보관합니다.
### 2. 서명 URL에 PUT
```bash
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: image/webp" \
--data-binary .webp
```
1단계에서 선언한 `Content-Type`과 바이트 크기가 정확히 같아야 합니다.
### 3. POST /v1/cms/media/uploads/complete
```json
{
"r2_key": "tenants/<tenant-id>/sites/<site-id>/media/...",
"original_name": "hero.webp",
"content_type": "image/webp",
"size_bytes": 482031,
"alt": "서비스 소개 대표 이미지",
"caption": null
}
```
`r2_key`는 1단계 응답값을 바꾸지 말고 그대로 보냅니다. 서버가 R2 객체의
tenant/site 경로, 크기, 형식을 검증한 뒤 미디어를 등록합니다.
파일 보존이 활성화된 환경에서는 원본의 별도 보존까지 확인한 뒤 등록합니다.
1단계의 `r2_key`는 업로드용 임시 경로이며, 완료 응답의 `r2_key`가 최종 원본
경로입니다. 공개 주소를 임시 경로로 직접 만들지 마세요.
완료 응답을 받지 못했거나 `503`을 받으면 같은 `r2_key`와 요청 본문으로 완료
요청을 재시도하세요. 새 등록은 `201`, 이미 완료된 업로드의 재시도는 같은
미디어 ID와 `200`을 반환합니다. 삭제된 업로드는 다시 완료할 수 없습니다.
서버의 보존 조회는 일시적인 timeout·429·5xx를 제한 재시도하지만, 원본 대조에
성공하기 전에는 완료로 응답하지 않습니다. 자동 조회 재시도 후에도 `503`이면
위와 같이 같은 업로드의 완료 요청을 재시도합니다.
응답의 `id`는 글의 `featured_media_id`에, `url`은 Tiptap image 노드의
`attrs.src`에 사용합니다.
### 미디어 관리
| 메서드·경로 | 설명 |
|---|---|
| `GET /v1/cms/media` | 최신순 목록. `limit`, `offset`, `site_id` 지원 |
| `PATCH /v1/cms/media/{media_id}` | `alt`, `caption` 수정 |
| `DELETE /v1/cms/media/{media_id}` | 미디어 행·R2 원본·변형 이미지·CDN 캐시 삭제 |
미디어 삭제 전 해당 URL을 쓰는 본문과 `featured_media_id` 연결을 먼저
교체하세요. 삭제 후 기존 공개 URL은 더 이상 유효하지 않습니다.
파일 보존이 활성화된 환경에서 원본 보존 또는 삭제 기록 저장에 실패하면
`503`을 반환하며 삭제를 완료하지 않습니다.
외부 파일이나 CDN 정리가 지연되면 목록에서 삭제된 뒤에도 `503`을 받을 수 있습니다.
이때 오류 메시지에 정리 대기와 자동 재시도를 알리며, 서버가 남은 작업을 계속 처리합니다.
`200 { deleted: true }`는 공개 파일 정리까지 완료된 경우입니다. 미디어 목록의 `404`만으로
CDN 정리 완료를 판단하지 마세요. 이미 방문자의 브라우저에 저장된 파일은 원격으로 지울 수 없습니다.
## 설정 쓰기 API
사업장 정보와 상단 메뉴를 어드민 화면 대신 API로 바꿉니다. **`read_write_settings`
권한으로 발급한 키가 필요합니다** (`settings:write`). 글쓰기 키(`read_write`)로
호출하면 `403 insufficient_scope` 입니다.
페이지·글·정보 모델과 배너·팝업 슬롯 연동은
[콘텐츠 모델과 노출 슬롯](./content-models-and-exposures.md)을 참고하세요.
세 가지를 먼저 알아 두세요.
1. **두 엔드포인트 모두 "그 설정 블록 전체 교체"입니다.** 메서드는 `PATCH`
지만 부분 병합이 아닙니다 — 보낸 값이 그 설정의 전부가 되고, 빠뜨린
필드는 지워집니다. 한 칸만 고치고 싶으면 공개 조회로 현재 값을 받아
그 값을 고쳐서 통째로 보내세요.
2. **대상 사이트는 `settings` 바깥(envelope)에 적습니다.** 사이트가 둘
이상인 테넌트가 `site_id` 를 생략하면 `400 site_id_required` 입니다 —
임의의 사이트를 고르지 않습니다. 사이트에 묶인 키(site-scoped)는 생략하고,
다른 사이트를 지목하면 `404` 입니다.
3. **저장 뒤 연결된 사이트에 `theme.updated` 알림을 보냅니다.** 알림이
실패해도 저장은 되돌아가지 않습니다 — 결과는 응답의 `revalidate` 로
확인합니다.
### PATCH /v1/cms/settings/business-profile
```json
{
"site_id": "019eb70c-…",
"settings": {
"name": "길동세무회계",
"business_type": "AccountingService",
"telephone": "02-1234-5678",
"address": { "street_address": "테헤란로 123", "address_locality": "강남구" },
"opening_hours": [ { "days": ["Mo","Tu","We","Th","Fr"], "opens": "09:00", "closes": "18:00" } ],
"area_served": ["서울 강남구"],
"services": ["기장·신고대리", "세무고문"],
"profiles": { "naver_place": "https://map.naver.com/p/entry/place/1" }
}
}
```
`settings` 안쪽 필드는 `GET /v1/cms/public/business-profile` 응답과 같은
이름입니다. 서버가 정하는 값(`tenant_id`·`site_id`·`configured`·`updated_at`)은
넣을 수 없습니다 — 넣으면 `400` 입니다.
저장 규칙:
| 항목 | 규칙 |
|---|---|
| `profiles.*` | **https 절대 주소만.** `http://` 와 로컬 주소는 거부 |
| `opening_hours` | 최대 7행. 시각은 `HH:MM` 24시간 표기(`09:00`). 선택 `reception_closes`는 시작 뒤·종료 이하 시각 또는 `null` |
| `area_served` | 10개 / 각 40자 |
| `services` | 12개 / 각 80자 (중복은 자동 제거) |
| `alternate_name`·`fax_number` | 각 120자 / 40자 |
| 모르는 필드 | 거부 (`400`) |
### PATCH /v1/cms/settings/site-nav
```json
{
"settings": {
"navGroups": [
{ "label": "사무소 소개", "href": "/about" },
{ "label": "소식",
"columns": [ { "title": "알림",
"links": [ { "label": "공지", "href": "/notice" } ] } ] }
],
"cta": { "label": "상담 문의", "href": "/contact" }
}
}
```
`settings` 는 `GET /v1/cms/public/theme` 의 `siteNav` 와 같은 모양입니다.
저장 규칙: 메뉴 그룹 7개 / 그룹당 열 3개 / 열당 링크 6개 / 보조 링크
(`utilityLinks`) 4개. 주소는 `#앵커`·`/경로`·`http(s)://` 만 허용합니다.
그룹에는 `href` 나 `columns` 중 하나가 반드시 있어야 합니다.
> 상단 메뉴는 한 번 만들면 빈 값으로 되돌릴 수 없습니다(`navGroups` 는 최소
> 1개). 메뉴를 없애려면 어드민 화면에서 지우세요.
### 응답
두 엔드포인트가 같은 모양으로 답합니다.
```json
{
"tenant_id": "…", "site_id": "…",
"updated_at": "2026-07-28T04:20:00.000Z",
"settings": { "…": "저장된 값 그대로" },
"revalidate": { "configured": 1, "delivered": 1, "failed": 0, "degraded": false }
}
```
`settings` 는 **저장된 값**입니다 — 보낸 값과 다를 수 있습니다(요일 순서 정렬,
목록 중복 제거, `business_type` 기본값 `LocalBusiness` 등). 다음 조회에서 무엇을
보게 될지는 이 값이 정답이고, 공개 조회로 확인하려 하지 마세요(공개 응답에는
최대 10초 캐시가 걸립니다).
`revalidate` 는 저장 뒤 보낸 갱신 알림의 결과입니다.
| 필드 | 뜻 |
|---|---|
| `configured` | 등록되어 있고 켜져 있는 알림 목적지 수 |
| `delivered` | 성공 |
| `failed` | 목적지가 오류를 돌려줌 |
| `degraded` | **보내지도 못한** 목적지가 있음 — 설정을 점검해야 합니다 |
`configured: 0, degraded: false` 는 정상입니다(알림을 등록하지 않은 사이트).
`degraded: true` 면 사이트에 반영되지 않았을 수 있으니 어드민의 발행 알림
설정을 확인하세요.
## GET /v1/cms/public/posts
발행된 글 목록 (커서 페이지네이션).
| 쿼리 | 설명 |
|---|---|
| `limit` | 페이지 크기 (서버에서 상한 clamp) |
| `cursor` | 이전 응답의 `next_cursor` |
| `type` | `post` \| `page` |
| `site_id` | 멀티 사이트 키일 때만 — site-scoped 키면 생략 |
```json
{
"items": [ { "id": "…", "slug": "…", "title": "…", "body_json": {…},
"collection_key": "blog",
"author_profile_id": "site-author-id",
"author_name": "공통 작성자", "author_slug": "writer",
"author_image_position_x": 50, "author_image_position_y": 50,
"terms": [{ "taxonomy": "category", "name": "…", "slug": "…" }],
"pattern_slots": { "post_footer": "clinic-guide" },
"published_at": "…" } ],
"has_more": false,
"next_cursor": null
}
```
> `collection_key` = 글이 속한 섹션(콘텐츠 유형). 섹션 라우팅(`/notice`·`/blog`)의 근거이며,
> 미설정이면 `null`. 카테고리(`terms`)는 섹션 안의 주제로 아카이브에만 쓰입니다 →
> [콘텐츠 유형 (Collections)](./collections.md).
`pattern_slots` = 공통 블록 자리별 블록 key(자리 key → `GET /patterns` 의 `key` 또는
`null`). 어드민 배치 규칙을 서버가 이 글의 `model_key`(콘텐츠 모델)에 맞춰 계산한 결과이며,
선언된 자리(현재 `post_footer` = 글 하단)는 항상 키로 존재합니다. 글 상세·미리보기
응답에도 같은 필드가 붙습니다 → 아래 `GET /v1/cms/public/patterns` 참고.
`related_posts` = 편집자가 어드민 "관련 콘텐츠"에서 고른 글(유형 무관, 고른 순서) + **발행된
예약 키 대상**(그 뒤, 적은 순서), **발행 글만**·중복 제거.
각 항목은 `{ id, title, slug, path, type, model_key, collection_key, excerpt, featured_media_url,
published_at }` 로 카드 하나를 그릴 만큼만 담습니다. 목록·상세·미리보기 응답에 모두 붙습니다
(구 서버는 미포함 → 빈 배열로 취급). 비어 있으면 사이트가 "같은 카테고리 최신 글" 같은
자동 추천을 채우면 됩니다 — `/cms-renderer-next` 의 `RootTaleBlogPost` 는 편집자 선택이
있으면 그것을, 없으면 `relatedPostsCount` 만큼 자동 추천을 그립니다.
```json
{ "related_posts": [ { "id": "…", "title": "…", "slug": "…", "path": "/faq/headache/migraine/…",
"type": "post", "model_key": "faq", "collection_key": "faq",
"excerpt": "…", "featured_media_url": null, "published_at": "…" } ] }
```
`author_profile_id`는 사이트 공통 공개 작성자 ID입니다. 이름·사진·소개·작가 주소는
같은 원장의 `author_name`·`author_image_url`·`author_bio`·`author_slug`로
제공됩니다. 사진 초점은 `author_image_position_x/y`(0~100, 구 서버는 `null`)이며
이미지 모양은 사이트의 시멘틱 토큰/CSS가 정합니다. 기존 `author_id`는 하위
호환용이므로 새 연동에서는 공개 작성자 식별자로 사용하지 마세요.
`content_version`은 반영된 콘텐츠 버전(1부터 시작), `contract_page_key`는 사이트
콘텐츠 계약에 연결한 페이지 key입니다. 사이트 계약에 `visualEditing`이 있을 때만
이 두 필드와 `content_editor`를 제공합니다. 미선언 사이트와 구 서버는 생략합니다.
`content_editor`는 공개 렌더링에 필요한 허용 필드만 제공합니다:
```json
{ "sectionStates": { "hero": "visible", "faq": "hidden", "old-section": "deleted" },
"primaryTermId": null, "cta": { "mode": "auto", "targetPostId": null } }
```
섹션 상태는 `visible`·`hidden`·`deleted`, CTA 모드는 `auto`·`manual`·`off`입니다.
`manual`은 `targetPostId`가 필요합니다. 사이트 템플릿은 `hidden`·`deleted`인 섹션을
출력하지 않으며, 내부 검수 정보는 이 응답에 포함되지 않습니다. SDK에서는
`contentVersion`·`contractPageKey`·`contentEditor`로 읽습니다.
선언 사이트의 목록·상세·미리보기에서 저장된 편집 상태가 없으면 `content_editor`를
생략하고, 저장값 해석에 실패하면 `null`을 보냅니다. 실패한 원문은 `meta_json`에서도
제거합니다. SDK는 `null`을 `contentEditorResult: { success: false, error }`로 전달하며
기존 `contentEditor`는 `undefined`입니다. 사이트는 실패를 기본 상태로 바꾸지 않습니다.
`fields`는 글의 모델과 템플릿에 맞는 필드 그룹의 최상위 key만 포함합니다.
템플릿은 고정 페이지의 `contract_page_key` 또는 모델 선언에서 찾습니다.
그 템플릿·모델이 사이트 계약의 `visualEditing.templates`에 등록되어 있으면
필드 값을 저장 구조 그대로 전달합니다. 그룹 내부의 코드 소유 경로·배치 값과
반복 항목 `_id`를 보존하며, 없는 선택 그룹은 `null`입니다. 이 경우 이미지·관계
필드도 저장된 ID이므로 사이트가 필요한 공개 대상을 조회합니다. 그 밖의 필드는
기존 포맷과 공개 참조 해석을 유지합니다. 반복행의 유효한 UUID `_id` 보존도
`visualEditing` 선언 사이트에만 적용하며 미선언 사이트는 기존 응답을 유지합니다.
## GET /v1/cms/public/posts/{identifier}
글 1개 — `identifier`는 slug 또는 UUID. 미발행/없는 글은 `404`.
## GET /v1/cms/public/posts/preview
관리자 편집기가 발급한 **미리보기 토큰**으로 초안(미발행 포함)을 **발행 글과
같은 모양**으로 받습니다. 사이트가 자기 글 템플릿으로 미리보기를 그리게 하는
용도입니다 — 관리자 미리보기와 발행 결과가 다르던 문제의 해법(`blog.md`
"미리보기 페이지" 참고).
| 쿼리 | 설명 |
|---|---|
| `token` | 편집기 '사이트에서 미리보기'가 URL `?token=`으로 넘긴 값 (글 1건 전용, 1시간) |
| `site_id` | 멀티 사이트 키일 때만 |
- 응답은 `GET /posts/{identifier}`와 같은 형식이며 `preview` 블록이 추가됩니다:
`{ "expires_at": "…", "source_status": "draft" }`. `status`는 템플릿 재사용을
위해 항상 `published`, `title`·`slug`·`excerpt`·`body_json`은 토큰 발급
시점의 편집기 내용입니다. 전체 작업본 토큰은 커스텀 필드·SEO·분류·관련 콘텐츠·
대표 이미지·작성자·`content_editor`·`contract_page_key`도 같은 작업본에서 읽습니다.
HTML이 정본인 작업본은 `body_html`을 보존하며, 구 편집기 토큰은 `null`입니다.
발행 전이면 `published_at`은 토큰 발급 시각입니다.
- 새 토큰은 작업본 ID와 버전을 참조하며, `preview.visual_target`에
`{ entityId, draftId, draftVersion, contractVersion, templateVersion }`를 반환합니다.
`content_version`은 그 작업본의 기준 콘텐츠 버전이고 `draftVersion`과 구분됩니다.
사이트는 실제로 읽은 의존 버전과 이 표식을 사용해 렌더 완료를 확인합니다.
- 토큰이 없거나 다른 사이트의 것이면 `404`, 만료면 `410 preview_expired`.
- 작업본이 교체됐거나 표식과 내용이 맞지 않으면 `409 preview_superseded`입니다.
등록된 사이트 계약의 checksum이 토큰의 `contractVersion`과 달라도 같은 오류입니다.
최신 작업본이나 발행 글로 자동 대체하지 말고 편집기에서 미리보기를 다시 열도록 안내합니다.
- 기존 글 편집기의 `contentTopicIds` 스냅샷은 `content_topic` 분류만 바꾸고
카테고리·태그·다른 사용자 분류는 유지합니다. 전체 작업본의 `termIds`가 있으면
그 전체 목록을 우선합니다. 모든 분류와 관련 글은 같은 사이트 범위에서 확인합니다.
- 응답 헤더 `cache-control: no-store` — 사이트도 절대 캐시하지 마세요.
JS/TS 는 `@roottale/cms-client/server` 의 `fetchPostPreview({ apiKey, token })`
와 `isPreviewExpiredError(error)`·`isPreviewSupersededError(error)`를 사용하세요.
SDK의 작업본 표식은 `post.preview.visualTarget`입니다.
## GET /v1/cms/public/search
발행된 콘텐츠 키워드 검색입니다. 제목 완전일치, 제목 부분일치, 요약, 본문
순으로 관련도를 계산하고 같은 점수에서는 최신 발행순으로 정렬합니다. 응답은
카드 렌더용 슬림 hit이며 본문(`body_json`)은 포함하지 않습니다.
| 쿼리 | 설명 |
|---|---|
| `q` | 검색 키워드 (필수, 1~100자) |
| `limit` | 결과 수 1~50, 기본 10 |
| `type` | `post`(기본, 하위 호환) \| `page` \| `all`(글+페이지 통합) |
| `locale` | BCP-47 언어 코드. 생략하면 사이트 기본 언어 |
| `site_id` | 멀티 사이트 키일 때만 |
```json
{ "tenant_id": "…", "site_id": "…", "query": "세무",
"items": [ { "id": "…", "type": "post", "collection_key": "notice",
"locale": "ko", "title": "…", "slug": "…",
"excerpt": "…", "featured_media_url": "…",
"published_at": "…" } ] }
```
JS/TS 는 `@roottale/cms-client/server` 의 `searchPosts({ apiKey, query })` 를
사용하세요. 사이트 전체 검색은 `type: "all"`을 지정합니다. 결과 링크는
`resolveSearchHitPath(hit, collections, locale?)`로 계산해야 콘텐츠 유형의
`basePath`와 다국어 경로를 그대로 따릅니다. `ROOTTALE_API_KEY`는 브라우저에
노출하지 말고 Server Component·Route Handler에서만 사용하세요.
## GET /v1/cms/public/menus
네비게이션 메뉴 전체 — 어드민 "디자인 > 메뉴" 저장값. 항목은 깊이 2 트리.
```json
{ "tenant_id": "…", "site_id": "…",
"items": [ { "id": "…", "name": "헤더 메뉴", "slug": "primary",
"items": [ { "id": "…", "label": "회사 소개", "url": "/about",
"children": [ { "id": "…", "label": "오시는 길",
"url": "/about/location" } ] },
{ "id": "…", "label": "블로그", "url": "/blog" } ],
"updated_at": "…" } ] }
```
## GET /v1/cms/public/menus/{slug}
위치 핸들(`primary`, `footer` 등)로 메뉴 1개. 없으면 `404` — 사이트는 자체
fallback 네비를 렌더하세요 (`menus.md` 참고).
## GET /v1/cms/public/redirects
어드민 "설정 > 주소 이동"에서 정의한 **활성** 커스텀 리다이렉트 규칙 전체.
사이트 Proxy가 요청 경로를 매칭해 301/302 처리합니다. 비활성 규칙과 운영자
메모는 응답에 포함되지 않습니다. 라우트 미배포(구 서버)는 `404` — 빈 목록으로
처리하세요. 연동은 `custom-redirects.md` 참고.
```json
{ "tenant_id": "…", "site_id": "…",
"items": [ { "id": "…", "from_path": "/old-event",
"to_target": "/promo", "status_code": 301 } ] }
```
| 필드 | 설명 |
|---|---|
| `from_path` | 출발 경로 — 정규화된 사이트 내부 절대 경로(앞 슬래시, 쿼리 제외). |
| `to_target` | 도착지 — 내부 경로(`/promo`) 또는 절대 URL(`https://…`). |
| `status_code` | `301`(영구) 또는 `302`(임시). |
## GET /v1/cms/public/theme
어드민에서 설정한 디자인 토큰. 설정된 그룹만 포함됩니다.
```json
{ "tenant_id": "…", "site_id": "…",
"colors": {…}, "fonts": {…}, "radius": {…}, "updated_at": "…" }
```
## GET /v1/cms/public/blog-settings
블로그 표시 설정 (TOC·작성자·발행일·작성자 카드 표시 정책).
`post_cta`는 공통 글 하단 블록이 없는 기존 글에서 `RootTaleBlogPost`가 적용하고,
공통 블록이 있으면 중복을 막기 위해 생략한다. 작성자 이미지 모양과 과거 전역 초점
필드는 호환용이며, 모양은 사이트 시멘틱 토큰/CSS, 초점은 글 응답의 작성자별 값이
소유한다. `toc_position`은 목차 배치(`"inline"`=본문 위 접이식,
`"sidebar"`=넓은 화면에서 본문 오른쪽 sticky, 좁은 화면은 자동 인라인)로,
렌더러가 알아서 반영하므로 연동 코드 변경은 불필요하다.
```json
{ "show_table_of_contents": false, "show_author": true, "show_date": true,
"show_author_card": true, "toc_title": null, "toc_position": "inline",
"author_profile_name": null, "author_profile_bio": null,
"author_profile_image_url": null, "author_profile_image_radius": "circle",
"site_profile": { "site_description": null, "home_title": null,
"home_description": null, "logo_url": null, "favicon_url": null,
"default_og_image_url": null },
"post_cta": { "title": "상담이 필요하신가요?", "description": "첫 상담은 무료입니다.",
"button_label": "상담 문의하기", "button_href": "/contact" },
"updated_at": null }
```
`author_profile_name`·`author_profile_bio`·`author_profile_image_url`·
`author_card_description`은 이전 연동을 깨지 않기 위해 응답 모양에만 남아 있고
항상 `null`입니다. 작성자 이름·사진·소개는 글 응답의 `author_name`·
`author_image_url`·`author_bio`를 사용하세요. 이 값은 글에 지정된 사이트별
작성자 프로필에서 옵니다. 글에 작성자가 없으면 작성자 메타와 카드를 표시하지
않습니다.
`site_profile` 은 사이트 공통 SEO 값. `default_og_image_url`(1200×630 권장)은
글에 대표/OG 이미지가 없을 때 SNS 공유 썸네일 폴백으로 쓰세요 —
`generateMetadata` 에서 `post.seo?.ogImage ?? post.featured_media_url ??
settings.siteProfile.defaultOgImageUrl` 순으로 우선합니다. `logo_url`·
`favicon_url`·`site_description` 은 사이트 `<head>` 에 적용합니다.
`home_title`·`home_description`은 **메인 홈(`/`) 전용** 호환 필드입니다.
계약 등록만으로 기존 홈 설정을 바꾸지 않습니다. 초기값 보존 또는 실제 설치 확인에서
홈 전환을 완료한 뒤 해당 경로의 `effective.title`·`effective.description`을 투영합니다.
전환 뒤에는 초기화·연결 해제·계약 제거로 예전 홈 설정을 되살리지 않습니다.
연결된 CMS 홈이 초안이거나 소유 경로가 제거되면 `null`을 반환합니다.
새 연동은 `fetchRouteMetadata`와 공통 빌더를 사용하세요(`seo.md` 참고).
## GET /v1/cms/public/metadata/routes
계약에 등록된 공개 경로의 검색·공유 메타데이터를 한 스냅샷에서 조회합니다.
인증과 `cms:read` scope는 단건 `/metadata?route_key=`와 같습니다.
선택 쿼리는 `locale`(생략 시 사이트 기본 언어), `site_id`입니다.
사이트 범위 키는 다른 사이트를 지정할 수 없고 tenant 범위도 유지됩니다.
```json
{
"site_id": "site-id",
"routes": [{
"routeKey": "home", "locale": "ko", "path": "/", "version": "0",
"overrides": {}, "defaults": { "title": "홈" },
"effective": { "title": "홈" }, "supportedFields": ["title"]
}]
}
```
각 항목은 단건 응답의 `metadata`와 같은 형식이며 `fallback`·`robots`도 보존합니다.
등록 순서로 반환하고 단건이 `null`인 경로는 제외합니다. 공개 대상이 없으면 `routes: []`이며
조회 장애는 오류 응답입니다. 구독 하향·미납에도 공개 읽기를 유지하고
`Cache-Control: private, no-store`를 반환합니다. SDK의 서버 측 Next fetch cache와는 별도입니다.
SDK는 `fetchSiteRouteMetadata(options)`이며 배포 순서는 API → SDK 발행 → 사이트입니다.
## GET /v1/cms/public/patterns
공통 블록(여러 글의 같은 자리에 붙는 재사용 본문) 중 **발행 상태** 목록. 어느 글의
어느 자리에 놓을지는 글 응답의 `pattern_slots`가 이미 말해 주므로, 사이트는
`pattern_slots[slot]` 값으로 이 목록에서 `key`를 찾아 `body_json`(Tiptap 문서)을 글
본문과 같은 렌더러·정화 경로로 그리면 됩니다. 목록이 비었거나 요청이 실패해도 글은
정상 열려야 합니다(블록만 생략).
```json
{ "tenant_id": "…", "site_id": "…",
"patterns": [ { "id": "…", "key": "clinic-guide", "name": "병원 안내",
"description": "글 하단 공통 안내", "body_json": { "type": "doc", "content": [ … ] },
"presentation": { "layout": "card", "background": "#f8f9fa",
"link_style": "buttons", "button_colors": ["#03c75a", "#1a1a1a", "#666666"] },
"status": "published", "updated_at": "…" } ] }
```
- 자리 key: `post_footer`(글 하단, 본문 바로 아래). 새 자리는 문서와 함께 추가됩니다.
- `presentation` = 어드민이 정한 표시 형태(`layout` plain|card, `background` hex, `link_style`
text|buttons, `button_colors` hex 순서 — 마지막 문단의 링크에 차례로, 모자라면 마지막 색 반복).
사이트는 이 값을 래퍼의 data 속성·CSS 변수로 옮겨 그리고, 색·모양을 따로 고정하지 않습니다.
- 캐시: `Cache-Control: private, max-age=10`. 어드민에서 블록·배치 규칙을 저장하면
`theme.updated` 웹훅이 오므로 설정류 캐시와 함께 지우세요(`revalidation-webhooks.md`).
## GET /v1/cms/public/categories
분류(카테고리)와 **분류별 발행 글 수**. 글 수는 서버가 SQL로 세므로 글이 몇 건이든
정확합니다 — 분류 모음 페이지의 "글 0건이면 404" 판정과 사이트맵 포함 여부(색인
위생)를 계산하는 데 씁니다. `/cms-renderer-next` 의
`fetchBlogArchiveCategories` 가 이 API를 자동으로 씁니다(직접 부를 일은 드뭅니다).
쿼리(선택):
| 이름 | 값 | 설명 |
| --- | --- | --- |
| `exclude_collections` | `true` | 어느 콘텐츠 유형에도 속하지 않은 글만 셉니다 — `/blog` 계열 모음 페이지가 다루는 범위와 같습니다. |
| `collection_key` | 유형 key | 그 유형에 속한 글만 셉니다. `exclude_collections` 와 동시 지정 시 400. |
| `locale` | BCP-47 | 미지정이면 사이트 기본 로케일(글 목록과 같은 기본값). |
| `site_id` | 사이트 id | 보통 생략. |
```json
{ "tenant_id": "…", "site_id": "…",
"categories": [
{ "slug": "tax", "name": "세무", "published_post_count": 412,
"collection_key": "column", "hub_promoted": true,
"description": "세무 칼럼", "seo_title": "세무 칼럼 모음",
"seo_description": "세무 칼럼을 주제별로 확인하세요.",
"image_media_id": "019…", "image_url": "https://imagedelivery.net/…/md",
"image_alt": "세무 자료와 계산기",
"path": "/column/tax" },
{ "slug": "law", "name": "법률", "published_post_count": 0,
"collection_key": null, "hub_promoted": false }
] }
```
- 글이 0건인 분류도 그대로 내려옵니다(`published_post_count: 0`) — "그런 분류가
없다"와 "분류는 있는데 이 범위에 글이 없다"를 구분할 수 있게.
- `description`·`seo_title`·`seo_description`은 ROOT-ADMIN 카테고리 편집값입니다.
검색 화면에서는 `seo_title → "{name} 글 모음"`, `seo_description → description
→ 사이트별 기본 소개문` 순으로 대체값을 적용하세요.
- `image_media_id`는 대표 이미지의 안정 ID, `image_url`은 바로 표시할 수 있는 URL,
`image_alt`는 대체 텍스트입니다. 세 값은 이미지 미설정 또는 구버전 API에서
`null`이거나 생략될 수 있습니다.
`path`는 콘텐츠 유형의 `category_path` 정책까지 적용한 정규 상대 경로이며, 해당
유형에 카테고리 아카이브가 없으면 `null`입니다.
- `hub_promoted` 는 어드민의 "이 카테고리 모음 페이지를 검색에 공개" 값이지만, **검색 노출
판정에는 쓰지 마세요**. 그 판정의 단일 소스는 `/blog-settings` 의
`sitemap.promoted_category_slugs` 입니다(두 소스를 섞으면 사이트맵과 페이지가
서로 다른 시점의 값을 볼 수 있습니다). 여기 값은 진단·표시용입니다.
- `category_index_activated`는 사이트의 분류 색인 정책 전환이 끝났는지 알려 줍니다.
사이트 계약에 `terms.categoryIndexActivation: "required"`를 선언한 사이트만 사용합니다.
이 값이 `true`일 때만 `hub_promoted: false`인 분류를 `noindex`와 사이트맵 제외로
처리하고, `false`이거나 값이 없으면 기존처럼 모든 공개 분류를 색인하세요. 선언하지
않은 사이트는 이 값을 읽지 않습니다.
- 분류가 서버 상한(500개)을 넘으면 응답에 `"truncated": true` 가 붙습니다.
`/cms-client` 로 직접 부를 때:
```ts
import { fetchCategoryCounts } from "@roottale/cms-client/server";
const { categories, truncated } = await fetchCategoryCounts({
apiKey: process.env.ROOTTALE_API_KEY!,
excludeCollections: true,
});
```
## GET /v1/cms/public/site-knowledge
사이트 지식 — 브랜드 보이스(어조·톤·화자) + 용어 규칙(금지어·교정어). AI
에이전트가 이 사이트에 맞는 글을 쓸 때 참고. 운영 메모·내부 SEO 임계값·내부
출처는 노출 안 함 (theme-and-settings.md 참고).
```json
{ "tenant_id": "…", "site_id": "…",
"brand": { "voice": "", "tone": "", "persona": "" },
"lexicon": { "forbidden_words": [], "preferred_terms": [{ "from": "유저", "to": "사용자" }] },
"updated_at": null }
```
## GET /v1/cms/public/business-profile
비즈니스 프로필 (로컬 SEO) — 어드민 "운영 > 비즈니스 프로필" 저장값.
미설정이면 `configured: false` + 필드 `null`.
```json
{ "tenant_id": "…", "site_id": "…", "configured": true,
"name": "길동세무회계", "legal_name": null, "alternate_name": "길동 세무회계",
"business_type": "AccountingService",
"telephone": "02-1234-5678", "fax_number": "02-1234-5679", "email": null,
"address": { "street_address": "테헤란로 123", "address_locality": "강남구",
"address_region": "서울특별시", "postal_code": "06234" },
"geo": { "latitude": 37.5006, "longitude": 127.0364 },
"opening_hours": [ { "days": ["Mo","Tu","We","Th","Fr"],
"opens": "09:00", "closes": "18:00" } ],
"price_range": "₩₩", "area_served": ["서울 강남구"],
"services": ["기장·신고대리", "세무고문"],
"profiles": { "naver_place": "https://…", "google_business": "https://…",
"kakao_channel": null, "kakao_map": "https://…",
"instagram": null, "naver_blog": null },
"updated_at": "…" }
```
`business_type`: `LocalBusiness` | `ProfessionalService` |
`AccountingService` | `LegalService` | `MedicalClinic` | `Dentist` |
`RealEstateAgent` | `Restaurant` | `BeautySalon`.
`opening_hours[].reception_closes`는 접수 마감이다. 키 생략은 미지정(이전 데이터),
`null`은 안내 해제, `HH:MM`은 지정 시각이며 `opens < reception_closes <= closes`를
검사한다. 저장 스키마와 SDK는 `receptionCloses`로 매핑하고 세 상태를 보존한다.
사업장 정보의 일반 PATCH는 기존과 같이 전달한 설정을 저장하므로 소비자는 키 생략과
`null`을 혼용하지 않는다. 관리자에서 미지정 행을 빈칸 그대로 저장하면 생략을 유지하고,
안내 해제를 선택하거나 이미 지정한 시각을 비우면 `null`로 저장한다.
사이트 계약·SDK 소비 예시는 [Next.js 연결 예시](../examples/nextjs/connected-content.md)를 따른다.
| 필드 | JSON-LD 매핑 |
|---|---|
| `alternate_name` | `alternateName` — 띄어쓰기 변형 등 같은 사업장의 다른 표기 |
| `fax_number` | `faxNumber` |
| `services` | `hasOfferCatalog` 의 `Offer.itemOffered` 목록 (최대 12개) |
| `profiles.kakao_map` | `hasMap` — `naver_place` 가 있으면 그쪽이 우선. **`sameAs` 에는 들어가지 않는다**(프로필이 아니라 위치 링크) |
> **주의**: `name`(사업장 이름)이 비어 있으면 `configured: false` 로 내려가고
> `/cms-client` 의 `fetchBusinessProfile` 은 `null` 을 반환한다 —
> 전화·주소만 채우고 이름을 비우면 나머지 입력이 전부 무시된다.
## GET /v1/cms/public/analytics
ROOT-ANALYTICS 사이트 ID와 외부 태그 설정.
```json
{ "tags": [ { "provider": "ga4", "id": "G-XXXXXXX", "enabled": true } ] }
```
`provider`: `ga4` | `clarity` | `meta_pixel` | `naver`.
## GET /v1/cms/public/jwks
웹훅 서명 검증용 site-scoped JWKS 공개키. **site-scoped 키 필수** — 테넌트
전체 키로 호출하면 `400 site_scope_required`.
## GET /v1/public/inquiry-forms/:formId
사이트에 등록한 활성 문의 폼의 현재 발행 정의를 읽습니다. `cms:read` 고객 키를
사이트 서버에서 사용하며, **고객사 전체 키에는 `site_id` 쿼리가 필수**입니다.
사이트 한정 키는 해당 사이트에 고정됩니다. 다른 고객사·사이트의 폼은 조회하거나
접수할 수 없습니다. 비활성·미등록·범위 밖 폼은 `404 not_found`입니다.
```json
{
"form_id": "01993841-7930-7000-8000-000000000001",
"site_id": "01993841-7930-7000-8000-000000000002",
"form_key": "quote",
"version": 2,
"definition": {
"title": "견적 문의",
"kind": "sales",
"fields": [
{ "key": "phone", "label": "전화번호", "type": "tel", "role": "phone", "required": true },
{ "key": "message", "label": "문의 내용", "type": "textarea", "role": "message", "required": true }
],
"requireOneOf": [],
"privacyConsentText": "견적 상담을 위한 연락처 수집에 동의합니다.",
"successMessage": "문의가 접수되었습니다."
}
}
```
한 사이트에 견적·AS 등 폼 ID를 여러 개 등록할 수 있습니다. 각 폼의 버전과
입력 항목은 독립적입니다. 정의 계약은 공개 패키지 `/inquiry-forms`,
SDK는 `fetchInquiryForm`입니다. 응답은 `no-store`로 다룹니다.
## POST /v1/public/inquiry-forms/:formId/submissions
폼별 CRM 접수. `application/json`, `cms:read` 고객 키를 사용합니다.
사이트 범위는 위 GET과 같고 고객사 전체 키에는 body의 `site_id`가 필수입니다.
```json
{
"site_id": "01993841-7930-7000-8000-000000000002",
"version": 2,
"answers": { "phone": "010-1234-5678", "message": "옥상 방수 견적을 요청합니다." },
"privacy_consent": true,
"idempotency_key": "01993841-7930-7000-8000-000000000005",
"placement": "contact/quote"
}
```
| 필드 | 필수 | 설명 |
|---|---|---|
| `site_id` | 고객사 전체 키 사용 시 | 폼이 속한 사이트 ID |
| `version` | ✅ | 방문자가 보고 동의한 발행 버전, 양의 정수 |
| `answers` | ✅ | 정의의 항목 키에 해당하는 답변. 문자열·문자열 배열·숫자·boolean 타입 보존 |
| `privacy_consent` | ✅ | 사용자 명시 동의 `true` |
| `idempotency_key` | ✅ | 같은 제출의 재시도에 재사용. 1~200자 `[A-Za-z0-9_-]` |
| `placement` | | 폼 배치 식별자 |
| `turnstile_token` | | 사이트의 보안 확인 토큰 |
| `attribution` | | 유입 객체. 기존 multipart의 `attr_` 접두 없이 `landing_path`, `utm_source` 등 사용 |
| `journey` | | 방문 여정 배열, 최대 30개. 기존 multipart의 JSON 문자열과 구분 |
이름·이메일·사업체명을 일괄 필수로 요구하지 않습니다. 서버가 폼의 항목·선택지·
필수 조건을 검증하고 전화 또는 이메일의 연락 수단을 확인합니다. 등록되지 않은
항목·선택지는 거부합니다. 폼의 업무 유형·항목 라벨은 서버 정의를 사용합니다.
새 저장은 `201`, 저장된 동일 키·동일 내용의 재시도는 `200`과 접수증을 반환합니다.
```json
{
"id": "01993841-7930-7000-8000-000000000003",
"inquiry_no": 17,
"received_at": "2026-09-12T08:30:00.000Z",
"replayed": false
}
```
`inquiry_no`는 정수입니다. HTTP `2xx`만으로 성공을 판단하지 말고 접수증을 확인하세요.
응답 유실·서버 오류에는 **동일한 키와 제출 내용 전체**로 다시 요청합니다. 서버는
문의·접수번호·알림 예약을 함께 저장하며 재시도 시 알림을 다시 만들지 않습니다.
이미 저장된 동일 제출은 폼의 변경·중지 후에도 같은 접수증을 반환합니다.
주요 오류는 `400 validation_error`, `409 form_version_conflict`,
`409 idempotency_key_conflict`, `404 not_found`, `429 rate_limited`입니다.
필드 검증 오류는 다음 구조를 사용합니다.
```json
{
"code": "validation_error",
"message": "Request validation failed",
"hint": null,
"retry_after": null,
"details": {
"field_errors": { "phone": ["연락처를 확인해주세요."] },
"form_errors": []
}
}
```
`form_version_conflict`는 새 정의와 동의 문구를 다시 확인한 뒤 제출해야 합니다.
`idempotency_key_conflict`에서는 자동으로 새 키를 만들어 중복 접수하지 마세요.
SDK `submitFormInquiry`가 접수증 검증과 구조화 오류 반환을 제공합니다.
[문의 폼 연동](./inquiries.md)에 같은 사이트의 두 폼을 연결하는 예제가 있습니다.
## POST /v1/public/inquiries
기존 고정 필드 상담문의(리드) 접수. `multipart/form-data`.
새 사이트의 여러 폼은 위의 폼별 JSON 접수를 사용하세요.
| 필드 | 필수 | 비고 |
|---|---|---|
| `vertical` | ✅ | `consulting` \| `medical` \| `tax` \| `legal`. 입력값은 검증·동의 판단에 쓰며, CRM 저장 업종과 상태 구성은 사이트의 업종 설정을 따릅니다. |
| `contact_name` | ✅ | |
| `business_name` | ✅ | |
| `email` | ✅ | `.+@.+\..+` |
| `phone` | ✅ | |
| `privacy_consent` | ✅ | 체크박스 (`on`) |
| `overseas_transfer_consent` | medical 시 ✅ | |
| `message`, `consultation_field`, `current_site_url` | | |
| `lead_kind` | | `patient`(기본) \| `sales` |
| `_redirect_url` | | 완료 후 redirect base (allowlist 검증) |
| `cf-turnstile-response` | | Cloudflare Turnstile 토큰. tenant-api에 `LEAD_INTAKE_TURNSTILE_SECRET_KEY`가 설정된 경우 필수 |
| `attr_landing_path`, `attr_rt_src`, `attr_utm_source`, `attr_utm_medium`, `attr_utm_campaign`, `attr_utm_term`, `attr_utm_content`, `attr_ad_click`, `attr_referrer`, `attr_first_touch_at`, `attr_last_touch_at`, `attr_last_touch_channel`, `attr_last_touch_source`, `attr_last_touch_medium`, `attr_last_touch_campaign`, `attr_last_touch_referrer` | | 유입 어트리뷰션 — CRM에 유입 경로 표시 (`inquiries.md` 참고). 그 외 `attr_*` 키는 무시 |
| `attr_journey` | | 방문 여정 JSON 원문(서버 zod 검증, 최대 30항목) — CRM "방문 여정" 패널에 표시 (`inquiries.md` 참고) |
| 기타 임의 필드 | | 최대 50개, 암호화 보관, CRM 상세 노출 |
응답: `302` redirect — 성공 `?ok=1`, 실패 `?err=<code>`
(`consent_privacy`, `consent_overseas`, `invalid_vertical`, `missing_fields`,
`invalid_email`, `turnstile_failed`, `internal`). 잘못된 키는 `401`.
IP/tenant rate limit 초과 시 `429 rate_limited`를 반환합니다.
서버-서버 호출 시 redirect를 따라가지 말고(`redirect: "manual"`) `Location`
헤더를 파싱하세요 — `/cms-client`의 `submitInquiry`가 이를 대신합니다.
## POST /v1/cms/revalidate
수동 캐시 갱신 트리거 (등록된 웹훅으로 재발송).
```json
{ "event": "post.updated", "paths": ["/blog", "/blog/my-post"], "slug": "my-post" }
```
`event`는 `post.published` · `post.updated` · `post.deleted` · `theme.updated`
중 하나이고, 생략하면 `post.updated`입니다. 앞의 세 값은 `read_write` 권한
(`cms:write`)으로 보냅니다.
**`theme.updated`(설정 저장 신호)만 `read_write_settings` 권한이 필요합니다**
("읽기 + 쓰기 + 설정 변경", scope `settings:write`). 글쓰기 키로 보내면
`403 insufficient_scope`입니다. 이 신호는 경로 몇 개가 아니라 수신 측의 **설정
캐시 이름표 전체와 루트 레이아웃(그 아래 모든 페이지)** 을 다시 만들게 하므로,
글을 쓰라고 내준 키에는 열지 않습니다.
```json
{ "event": "theme.updated" }
```
위 "설정 쓰기 API"로 사업장 정보·상단 메뉴를 바꾸면 이 신호는 저장과 함께
자동으로 나갑니다 — 직접 보낼 필요는 없습니다. 자세한 동작은
[재검증 웹훅 문서](./revalidation-webhooks.md#수동-revalidation-api)에 있습니다.
## 에러 형식
비 2xx 응답은 JSON 에러 바디(`code`, `message`)를 가집니다. 주요 코드:
`invalid_key`(401), `insufficient_scope`(403), `rate_limited`(429),
`not_found`(404).
## 캐시 헤더
공개 콘텐츠 응답은 private 캐시 헤더로 내려갑니다 — CDN 공유 캐시에 의존하지
말고 사이트 측 ISR + 발행 웹훅 조합을 사용하세요.