# 외부 원장 원고 연결 예제

동기화 작업은 서버의 관리 API 키로 실행한다. 공개 사이트나 브라우저에 쓰기 키를
전달하지 않는다. 아래 예제의 ID·key는 해당 사이트의 기존 값으로 바꾼다.

`POST https://api.roottale.com/v1/cms/posts`

```json
{
  "site_id": "site-id",
  "model_key": "article",
  "author_profile_id": "site-author-id",
  "source_key": "notion:stable-page-id",
  "title": "검수한 제목",
  "slug": "stable-article-slug",
  "body_json": { "type": "doc", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "검수한 본문" }] }] },
  "category_ids": ["existing-category-id"],
  "publish": false
}
```

201은 생성, 200은 같은 키로 먼저 생성된 글이다. 후자의 본문을 생성 요청으로
덮어쓰지 않는다. 응답을 잃어버렸을 때도 같은 키로 재요청한다.

기존 글을 수정할 때는 `PATCH /v1/cms/posts/{id}`에 조회한 버전을 함께 보낸다.

```json
{
  "site_id": "site-id",
  "expected_updated_at": "2026-10-16T01:00:00.000Z",
  "title": "검수한 수정 제목"
}
```

409이면 사용자의 변경을 먼저 확인한다. SEO는 `GET/PATCH /v1/cms/metadata/post/{id}`와
`expected_version`을 사용하고, 발행은 `POST /v1/cms/posts/{id}/publish`에 최신
`expected_updated_at`을 보낸다. 공개 주소는 CMS의 `path`를 기준으로 계산한다.
응답을 받았다는 사실과 실제 사이트 반영 완료는 다르므로 등록된 revalidation도 확인한다.

원장에서 선택한 관련 글만 노출하려면 이 예제의 블로그 상세와 미리보기 페이지의
`RootTaleBlogPost` 옵션을 함께 바꾼다. 명시적 `related_posts`는 계속 표시되고
카테고리 기반 자동 추천만 꺼진다.

```tsx
<RootTaleBlogPost
  apiKey={process.env.ROOTTALE_API_KEY!}
  slugOrId={post.id}
  relatedPostsCount={0}
/>
```

전문: [관리 API](../../docs/api-reference.md), [SEO 계약](../../docs/seo.md),
[웹훅 연결](../../docs/revalidation-webhooks.md).
