# Citely Docs (/docs)



Chào mừng đến với tài liệu **Citely** — nền tảng SaaS viết & xuất bản nội dung SEO/GEO.

Tài liệu chia làm hai mảng:

<Cards>
  <Card title="Hướng dẫn sử dụng" href="/docs/guides" description="Dành cho người dùng: kết nối website, tạo bài, xuất bản, kết nối Google Search Console." />

  <Card title="Nhà phát triển (API)" href="/docs/developer" description="Citely Connect / CPP v1: giao thức đẩy bài ra website của bạn, ký webhook, mã lỗi, read-API." />
</Cards>

## Bắt đầu nhanh [#bắt-đầu-nhanh]

* **Bạn là người dùng Citely?** → [Hướng dẫn sử dụng](/docs/guides)
* **Bạn là dev cần nhận bài từ Citely vào website?** → [Tổng quan Citely Connect](/docs/developer)

> Tài liệu này là *docs-as-code* (mã nguồn mở, viết bằng MDX). Nội dung máy-đọc-được tại
> [`/llms.txt`](/llms.txt) và [`/llms-full.txt`](/llms-full.txt) để trợ lý AI tra cứu nhanh.


# Trạng thái bất đồng bộ (building → live) (/docs/developer/async-publish)





Site động (`db`) publish xong là **live ngay**. Site tĩnh (`fs-build`) thì **bản chất bất
đồng bộ**: nhận bài → ghi file → CI/build (30–90s) → mới hiển thị. CPP mô hình hoá điều này
bằng &#x2A;*một field `status` + một flag `async`**, không phân mảnh.

## Ba trạng thái, một mô hình [#ba-trạng-thái-một-mô-hình]

```text
db adapter    POST → 200 { status: "live" }        (xong, hiển thị ngay)
fs-build      POST → 202 { status: "building" }     (đã nhận, đang build)
                 │
                 └─ Citely POLL `url` (HEAD) tới khi 200 → tự chuyển "live".
                    Site KHÔNG cần làm gì thêm.
```

## Mặc định — Citely poll (site không làm gì) [#mặc-định--citely-poll-site-không-làm-gì]

1. Receiver ghi bài → trả `202 { id, url, status: "building" }`.
2. Citely lưu một *delivery record* (permalink + trạng thái `building`).
3. Citely định kỳ `GET url` (HEAD/GET). Khi trả `200` → chuyển record sang `live`.
4. UI Citely hiện "Đang build → Đã xuất bản".

Đây là đường khuyến nghị: site tĩnh tối thiểu chỉ cần trả `202` rồi mặc kệ. Poll là cách
DUY NHẤT đang khả dụng hôm nay — receiver không cần expose thêm endpoint nào.

## Vì sao không dùng trạng thái đồng bộ "giả" [#vì-sao-không-dùng-trạng-thái-đồng-bộ-giả]

Có thể trả `200 {url}` ngay và coi như xong. Nhưng URL đó có thể `404` vài chục giây tới khi
build xong → user bấm vào thấy lỗi, và Citely index sớm một URL chưa tồn tại. `202 building`

* theo dõi là trung thực hơn: Citely chỉ báo "đã xuất bản" khi bài thật sự sống, và chỉ ping
  Google index khi `live`.

<Callout type="warn">
  Callback tức thì (site gọi Citely khi build xong) là **kế hoạch tương lai, chưa triển khai** — endpoint `POST /api/connect/live` chưa tồn tại. Hiện tại chỉ dùng đường poll ở trên.
</Callout>


# Mã lỗi CPP_* (/docs/developer/errors)



Receiver **không** trả lỗi tự do. Trả **mã chuẩn** để Citely map thẳng vào error-catalog
của nó và hiện đúng cách xử lý cho user — thay vì một "500 Internal Error" mù mờ.

Response lỗi: mã HTTP + JSON `{ "error": "<CODE>", "message": "mô tả ngắn" }`.

## Mã lỗi receiver → Citely [#mã-lỗi-receiver--citely]

| HTTP | `error` code              | Khi nào                                              | Citely xử lý / hiện cho user                                        |
| ---- | ------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------- |
| 401  | `CPP_SIG_INVALID`         | HMAC không khớp                                      | "Secret lệch giữa Citely và site → xoay lại secret & cập nhật env." |
| 401  | `CPP_REPLAY`              | `abs(now - ts) > 300s`                               | "Đồng hồ server site lệch > 5 phút → chỉnh NTP."                    |
| 400  | `CPP_VERSION_UNSUPPORTED` | Site chưa hỗ trợ `version`/`protocol` này            | "Site cần nâng cấp receiver lên CPP v1." Citely chặn publish.       |
| 422  | `CPP_VALIDATION`          | Payload thiếu/sai field bắt buộc (kèm `field`)       | Hiện đúng field lỗi (vd `title` vượt giới hạn Zod của site).        |
| 409  | `CPP_CONFLICT`            | Slug/externalId đụng bản ghi khác                    | "Trùng bài — kiểm tra externalId/slug."                             |
| 429  | `CPP_RATE_LIMITED`        | Site tự giới hạn tần suất                            | Citely backoff & retry.                                             |
| 500  | `CPP_STORAGE_FAILED`      | Ghi thất bại (DB write / file)                       | "Lỗi phía site khi lưu bài." Citely retry.                          |
| 502  | `CPP_UNREACHABLE`         | Không kết nối được endpoint (timeout, DNS, WAF chặn) | "Không gọi được site — kiểm firewall/WAF/allowlist IP Citely."      |

Quy ước: mọi mã bắt đầu `CPP_`, SCREAMING\_SNAKE, **không đổi tên** khi đã phát hành (thêm
mã mới nếu cần nghĩa mới). Với `CPP_VALIDATION`, kèm `"field"` để Citely chỉ đúng chỗ:

```json
{ "error": "CPP_VALIDATION", "message": "title too long (max 70)", "field": "title" }
```

## Trạng thái publish (`status` trong echo) [#trạng-thái-publish-status-trong-echo]

| `status`   | Nghĩa                                        | Adapter điển hình  |
| ---------- | -------------------------------------------- | ------------------ |
| `live`     | Bài đã hiển thị công khai tại `url`          | `db` (render động) |
| `building` | Đã nhận & lưu, đang chờ CI/build để hiển thị | `fs-build`         |

Chi tiết vòng đời `building → live`: [Trạng thái bất đồng bộ](/docs/developer/async-publish).

## Đối xứng hai chiều [#đối-xứng-hai-chiều]

Citely dùng bộ mã này ở **cả hai chiều**: khi transport gặp lỗi lúc `POST` tới site, nó phân
loại về đúng `CPP_*` và surface qua hệ lỗi của Citely. Cùng một ngôn ngữ lỗi từ Citely → site
→ về Citely, nên user luôn thấy thông điệp hành động được, không phải log thô.


# Citely Connect — Tổng quan (/docs/developer)





**Citely Connect** là cách Citely đẩy bài viết đã hoàn thiện ra **website của bạn**.
&#x2A;*Citely Publish Protocol v1 (CPP v1)** là *hợp đồng kỹ thuật* mà website xây theo để nhận bài — Citely đặt chuẩn, website conform.

Citely đóng vai CMS/bộ não nội dung. Nhiều landing page hiện đại (Astro, Next.js, Hugo, React thuần, Laravel…) **không có CMS quản trị blog**. Citely Connect lấp đúng chỗ đó: website chỉ cần dựng **một endpoint** theo CPP v1 là sẵn sàng nhận bài — không phải tự viết admin, editor, auth, storage.

## Kết nối bằng một dòng (copy cho AI) [#kết-nối-bằng-một-dòng-copy-cho-ai]

Admin website **không cần tự code**. Copy đúng một dòng và dán cho AI của bạn (Claude Code / Cursor / Copilot):

```text
Fetch https://citely-seo.com/connect/v1/agent.md — rồi nối repo này với Citely.
```

AI đó sẽ `Fetch` spec, tự nhận diện stack, chọn adapter, dựng endpoint, map field theo schema repo của bạn, và in ra hướng dẫn đặt `CITELY_WEBHOOK_SECRET`.

## Ba tầng của chuẩn [#ba-tầng-của-chuẩn]

| Tầng              | Ai định nghĩa    | Nội dung                                                                  |
| ----------------- | ---------------- | ------------------------------------------------------------------------- |
| 1. **Envelope**   | Citely phát      | 1 bài = 1 JSON canonical (html + markdown + jsonLd + meta + i18n + media) |
| 2. **Receiver**   | Website xây      | 1 endpoint: `GET` handshake năng lực + `POST` nhận bài                    |
| 3. **Vocabulary** | Cả hai nói chung | `status` + mã lỗi `CPP_*`                                                 |

## Chọn adapter theo "bạn muốn SỞ HỮU dữ liệu tới đâu" [#chọn-adapter-theo-bạn-muốn-sở-hữu-dữ-liệu-tới-đâu]

| Adapter         | Ai lưu bài                 | Website xây                                         | Lên sóng    |
| --------------- | -------------------------- | --------------------------------------------------- | ----------- |
| `citely-api` 🥇 | **Citely** (bạn 0 backend) | chỉ 1 *reader* (fetch + render), KHÔNG cần receiver | ngay        |
| `db`            | DB của bạn                 | receiver upsert row → render động                   | ngay        |
| `fs-build`      | đĩa/repo của bạn           | receiver ghi file + trigger build                   | sau rebuild |

* **`citely-api` = mặc định khuyến nghị:** bạn KHÔNG dựng endpoint — chỉ đăng ký site trong Citely, nhận read-key, rồi *đọc* read-API. Đây là adapter DUY NHẤT không cần receiver.
* **`db`** cho bên muốn dữ liệu nằm trong DB của mình (Cloudflare D1 › Neon / Turso › Supabase).
* **`fs-build`** cho site tĩnh self-host (ghi file + rebuild).

<Callout type="info">
  Adapter `git` (commit mỗi bài) và `citely-git` (GitHub App) **đã bỏ/gác lại** — ngàn commit + rebuild mỗi lần publish không scale.
</Callout>

## Cây quyết định [#cây-quyết-định]

```text
Bạn muốn SỞ HỮU dữ liệu tới đâu?
├─ "Chỉ cần có bài, khỏi backend"   → citely-api  (Citely host + read-API)   ⭐ mặc định
├─ "Muốn bài trong DB của tôi"      → db          (D1/Neon/Turso › Supabase)
└─ "Khăng khăng self-host tĩnh"     → fs-build    (ghi file + rebuild)
```

## Tiếp theo [#tiếp-theo]

<Cards>
  <Card title="Envelope (CPP v1)" href="/docs/developer/protocol-envelope" description="Cấu trúc JSON của một bài viết Citely gửi ra." />

  <Card title="Receiver endpoint" href="/docs/developer/receiver" description="GET handshake + POST nhận bài." />

  <Card title="Ký webhook" href="/docs/developer/webhook-signing" description="Standard Webhooks: header, HMAC, chống replay." />

  <Card title="Mã lỗi CPP_*" href="/docs/developer/errors" description="Từ vựng lỗi & trạng thái publish." />

  <Card title="Read-API" href="/docs/developer/read-api" description="Đọc bài với adapter citely-api (endpoint, auth, phân trang)." />

  <Card title="Adapters" href="/docs/developer/adapters/citely-api" description="citely-api · db · fs-build." />
</Cards>


# Envelope (CPP v1) (/docs/developer/protocol-envelope)





Mỗi lần publish, Citely gửi **một** JSON body mô tả trọn vẹn một bài viết. Envelope là
**superset & self-sufficient**: mọi thứ để render một bài đều nằm trong một `POST` —
website **không bao giờ** phải gọi ngược Citely để lấy thêm.

## Quy tắc bất biến [#quy-tắc-bất-biến]

1. **Forward-compatible.** Citely có thể thêm field mới bất cứ lúc nào trong cùng `version`.
   Receiver **PHẢI bỏ qua field lạ**, không được lỗi vì gặp field chưa biết.
2. **Optional trừ khi ghi "bắt buộc".** Field vắng mặt = không có dữ liệu đó; đừng suy diễn.
   Chỉ `version`, `event`, `title`, `slug`, `status` là luôn có.
3. **`version`** = phiên bản envelope. CPP v1 dùng `version: 1`. Chỉ bump khi có *breaking*
   change (đổi nghĩa/xoá field) — thêm field KHÔNG bump.
4. **HTML sạch, JSON-LD tách riêng.** `html` là thân bài ngữ nghĩa, **không** chứa
   `<script type="application/ld+json">`. Schema.org nằm ở mảng `jsonLd[]` để receiver tự
   đặt vào `<head>`.

## Body (JSON) [#body-json]

```jsonc
{
  "version": 1,
  "event": "article.publish",

  // ── Định danh & upsert ──────────────────────────────────────────────
  "externalId": "string | null", // id RECEIVER đã trả lần trước → UPDATE bản đó. null → CREATE mới.
  "title": "string",             // bắt buộc
  "slug": "string",              // bắt buộc, đã kebab-case/ASCII-hoá

  // ── Nội dung (receiver chọn định dạng nó "accepts") ─────────────────
  "html": "string",              // HTML ngữ nghĩa, render as-is (đã sạch Gutenberg)
  "markdown": "string",          // cùng bài, dạng Markdown (tiện cho SSG)

  // ── Meta SEO ────────────────────────────────────────────────────────
  "excerpt": "string",           // meta description (~150–160 ký tự)
  "focusKeyword": "string",
  "tags": ["string"],            // topic cluster / chủ đề
  "author": { "name": "string", "url": "string | null", "avatar": "string(url) | null" },
  "canonicalUrl": "string | null",
  "noindex": false,              // true → receiver set noindex + KHÔNG lên sitemap

  // ── Đa ngôn ngữ ─────────────────────────────────────────────────────
  "locale": "vi",                // BCP-47 gọn: "vi" | "en" | "vi-VN"
  "translationKey": "string|null", // nối hreflang giữa các bản dịch cùng 1 bài gốc

  // ── Media (URL tuyệt đối trên CDN Citely) ───────────────────────────
  "cover": "string(url) | null", // ảnh đại diện / OG
  "images": [{ "url": "string(url)", "alt": "string", "caption": "string" }],

  // ── JSON-LD (Schema.org, đã tách khỏi html) ─────────────────────────
  "jsonLd": [{ "@context": "https://schema.org", "@type": "Article" }],

  // ── Trạng thái & thời gian ──────────────────────────────────────────
  "status": "publish",           // "publish" | "draft" | "future"
  "publishedAt": "ISO-8601 | undefined",
  "modifiedAt": "ISO-8601 | undefined",

  "test": false                  // true = ping "Test Connection". Verify rồi trả 200, KHÔNG lưu.
}
```

## Ghi chú field [#ghi-chú-field]

| Field                       | Ghi chú cho receiver                                                                                                                 |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `externalId`                | Khoá upsert số 1. Khác `null` → cập nhật đúng bản ghi đó. `null` → tạo mới. Không lưu id thì upsert theo `slug`.                     |
| `html` vs `markdown`        | Chọn theo `accepts` bạn khai ở handshake. Site tĩnh thường lấy `markdown`; site động thường lưu `html`.                              |
| `tags`                      | Chuỗi tự do (không phải id). Map vào taxonomy của bạn; bỏ qua nếu schema không có.                                                   |
| `author`                    | Render byline + `Person` trong JSON-LD. `jsonLd[]` **đã** chứa Article/Person, nên `author` chỉ là tiện lợi.                         |
| `locale` / `translationKey` | Site song ngữ: `locale` → trường `lang`; các bài cùng `translationKey` là bản dịch của nhau → nối `<link rel="alternate" hreflang>`. |
| `cover` / `images[].url`    | URL tuyệt đối trên CDN Citely. Mặc định **hot-link** (0 việc). Muốn bền thì tải về R2/repo của bạn.                                  |
| `jsonLd[]`                  | Emit mỗi phần tử thành một `<script type="application/ld+json">` trong `<head>`. **Đừng** nhét lại vào `html`.                       |
| `status: "future"`          | Bài hẹn giờ. `publishedAt` là thời điểm tương lai → giữ nháp tới giờ đó.                                                             |

## Field-mapping (bước AI của website làm) [#field-mapping-bước-ai-của-website-làm]

AI của repo phải **đọc schema thật** (vd `src/content.config.ts` Zod của Astro, hay bảng DB)
rồi map field CPP → field local. Ví dụ:

| CPP field     | Frontmatter Astro (Zod) |
| ------------- | ----------------------- |
| `title`       | `title`                 |
| `excerpt`     | `description`           |
| `publishedAt` | `pubDate`               |
| `modifiedAt`  | `updatedDate`           |
| `cover`       | `heroImage`             |
| `locale`      | `lang`                  |
| `tags`        | `tags`                  |
| `author.name` | `author`                |

Field CPP không có trường tương ứng → bỏ qua. Trường Zod bắt buộc mà CPP không cấp → điền
default hợp lý (vd `pubDate = publishedAt ?? now`).

<Callout type="info">
  Bước tiếp theo: [Receiver endpoint](/docs/developer/receiver) — endpoint website phải dựng để nhận envelope này.
</Callout>


# Read-API reference (/docs/developer/read-api)





Read-API phục vụ bài đã publish cho adapter [`citely-api`](/docs/developer/adapters/citely-api&#x29;.
Chỉ trả bài &#x2A;*`status = published`**, luôn scoped theo site → không rò bài nháp hay của tenant khác.

Base URL: `https://citely-seo.com/connect/v1/sites/{siteToken}`

## Xác thực [#xác-thực]

* **`siteToken`** nằm trong URL — token ngẫu nhiên khó đoán (không phải id tuần tự), công khai.
* **read-key** (`Bearer`) — bí mật, đặt server-side là `CITELY_READ_KEY`. Bắt buộc cho `list` + `export`.
* **Origin allowlist** (mềm) + **rate-limit** phân tầng: request kèm read-key hợp lệ được coi là
  build của chủ site (hạn mức lớn); ẩn danh theo `(token, IP)` hạn mức chặt hơn.

| Method + path               | Auth                   | Trả về                                  |
| --------------------------- | ---------------------- | --------------------------------------- |
| `GET /posts/{slug}`         | công khai (edge-cache) | 1 bài (`Post`)                          |
| `GET /posts?limit=&cursor=` | `Bearer <read-key>`    | `{ posts: PostListItem[], nextCursor }` |
| `GET /export`               | `Bearer <read-key>`    | `{ posts: Post[], count, truncated }`   |

## `GET /posts/{slug}` [#get-postsslug]

Công khai, cache ở CDN. Tuỳ chọn `?locale=vi` để chọn đúng bản dịch khi một slug có nhiều
ngôn ngữ (không có `locale` → bản mới nhất).

```bash
curl https://citely-seo.com/connect/v1/sites/{siteToken}/posts/vi-du-slug
```

**Response `200` — object `Post`:**

```jsonc
{
  "slug": "string",
  "title": "string",
  "seoTitle": "string | null",
  "excerpt": "string | null",
  "html": "string",             // HTML sạch (JSON-LD KHÔNG nằm trong)
  "markdown": "string | null",
  "jsonLd": [{ "@type": "Article" }],
  "cover": "string(url) | null", // 1 ảnh đại diện/OG (KHÔNG phải mảng ảnh)
  "author": { "name": "string", "url": "string|null", "avatar": "string|null" } | null,
  "tags": ["string"],
  "locale": "vi",
  "translationKey": "string | null",
  "canonicalUrl": "string | null",
  "publishedAt": "ISO-8601 | null",
  "modifiedAt": "ISO-8601"
}
```

<Callout type="warn">
  Read-API trả &#x2A;*`cover`** (một ảnh) — **không** có mảng `images[]`. (Mảng `images[]` chỉ tồn tại ở [envelope push](/docs/developer/protocol-envelope), không phải ở read-API.)
</Callout>

## `GET /posts` — list phân trang [#get-posts--list-phân-trang]

Cần read-key. Phân trang **keyset** (ổn định, mới nhất trước). `limit` mặc định 20, tối đa 100.
Lặp bằng cách truyền `nextCursor` trả về vào `?cursor=`.

```bash
curl -H "Authorization: Bearer $CITELY_READ_KEY" \
  "https://citely-seo.com/connect/v1/sites/{siteToken}/posts?limit=20"
```

**Response `200`:**

```jsonc
{
  "posts": [
    {
      "slug": "string", "title": "string", "excerpt": "string | null",
      "cover": "string(url) | null", "tags": ["string"], "locale": "vi",
      "translationKey": "string | null",
      "publishedAt": "ISO-8601 | null", "modifiedAt": "ISO-8601"
    }
  ],
  "nextCursor": "string | null"   // null = hết trang
}
```

`PostListItem` bỏ bớt `html`/`markdown`/`jsonLd` (nhẹ). Cần thân bài → gọi `GET /posts/{slug}`.

## `GET /export` — xuất toàn bộ (chống lock-in) [#get-export--xuất-toàn-bộ-chống-lock-in]

Cần read-key. Trả tối đa **1000** bài; vượt → `truncated: true` (không bao giờ cắt âm thầm).

```bash
curl -H "Authorization: Bearer $CITELY_READ_KEY" \
  "https://citely-seo.com/connect/v1/sites/{siteToken}/export"
```

```jsonc
{ "posts": [ /* Post đầy đủ */ ], "count": 128, "truncated": false }
```

## Mã lỗi (riêng của read-API) [#mã-lỗi-riêng-của-read-api]

Response lỗi dạng `{ "error": "<CODE>", "message": "…" }`, luôn `no-store`.

| HTTP | code                   | Khi nào                                                                     |
| ---- | ---------------------- | --------------------------------------------------------------------------- |
| 404  | `CPP_NOT_FOUND`        | `siteToken` không tồn tại / không phải site citely-api (không lộ phân biệt) |
| 401  | `CPP_SIG_INVALID`      | thiếu/sai read-key ở `list`/`export`                                        |
| 403  | `CPP_ORIGIN_FORBIDDEN` | `Origin` không nằm trong allowlist của site                                 |
| 429  | `CPP_RATE_LIMITED`     | vượt hạn mức (kèm header `Retry-After`)                                     |

<Callout type="info">
  `CPP_NOT_FOUND` và `CPP_ORIGIN_FORBIDDEN` là mã **riêng của bề mặt read-API** (chưa nằm trong error-catalog chung của Citely). Khác với bộ [mã lỗi CPP\_\* của receiver](/docs/developer/errors) dùng khi Citely *push* bài.
</Callout>


# Receiver endpoint (/docs/developer/receiver)





Website conform CPP v1 = expose **một endpoint, hai method**:

* **`GET {endpoint}`** → khai báo năng lực (handshake). Không tác dụng phụ.
* **`POST {endpoint}`** → nhận một bài ([Envelope](/docs/developer/protocol-envelope)).

Cả hai được ký [Standard Webhooks](/docs/developer/webhook-signing) (HMAC-SHA256) bằng `CITELY_WEBHOOK_SECRET`.

## 1. `GET` — Handshake năng lực [#1-get--handshake-năng-lực]

Trước khi publish (và ở nút "Test Connection"), Citely gọi `GET` để **học** website là loại
gì rồi mới gửi payload đúng khẩu vị — Citely không phải đoán framework.

**Response** `200 application/json`:

```jsonc
{
  "citely": "receiver",
  "protocol": 1,             // bắt buộc = 1. Khác → Citely trả CPP_VERSION_UNSUPPORTED
  "profile": "static-git",   // "runtime-db" | "static-git" | "static-fs" | "citely-git"
  "storageAdapter": "git",   // "db" | "git" | "fs-build" | "citely-git"
  "accepts": ["markdown"],   // định dạng bạn tiêu hoá: "html" và/hoặc "markdown"
  "locales": ["vi", "en"],   // ngôn ngữ site hỗ trợ
  "async": true,             // true = POST trả 202 building; false = 200 live ngay
  "fieldMap": {              // (tuỳ chọn) để Citely hiển thị/kiểm tra ánh xạ
    "excerpt": "description",
    "cover": "heroImage",
    "locale": "lang"
  }
}
```

* `GET` **không bắt buộc verify chữ ký** (không tác dụng phụ, không lộ dữ liệu). Muốn chặt
  thì verify như `POST`.

## 2. `POST` — Nhận một bài [#2-post--nhận-một-bài]

### Thuật toán xử lý (đúng thứ tự) [#thuật-toán-xử-lý-đúng-thứ-tự]

1. **Đọc RAW body** (bytes nguyên văn) **TRƯỚC KHI** `JSON.parse` — chữ ký ký trên raw.
2. **Verify chữ ký** ([chi tiết](/docs/developer/webhook-signing)). Sai → `401 CPP_SIG_INVALID`.
   Lệch giờ > 300s → `401 CPP_REPLAY`.
3. **Kiểm `version`.** Không hỗ trợ → `400 CPP_VERSION_UNSUPPORTED`.
4. **`test === true`** → verify xong, trả `200 {ok:true}`, **KHÔNG lưu gì**.
5. **Idempotency theo `webhook-id`**: đã xử lý id này → trả lại kết quả cũ (đừng tạo trùng).
   Upsert theo `externalId` (nếu có), ngược lại theo `slug`.
6. **Lưu bài** (adapter của bạn: DB insert / ghi file + build).
7. **Trả echo** `{ id, url, status }`.

### Echo (response) khi thành công [#echo-response-khi-thành-công]

```jsonc
{
  "id": "string | number",               // bắt buộc → Citely lưu, gửi lại làm externalId lần sau
  "url": "https://site.com/blog/<slug>",  // bắt buộc → permalink công khai
  "status": "live"                        // "live" (đã hiển thị) | "building" (đã nhận, đang rebuild)
}
```

* **`db` adapter** → `200 { status: "live" }` (hiển thị ngay).
* **`fs-build`** → `202 { status: "building" }` (đã ghi, chờ CI/build). Citely tự poll `url`
  tới khi 200 rồi chuyển `live` — xem [Trạng thái bất đồng bộ](/docs/developer/async-publish).
* Thiếu `status` → Citely mặc định `"live"` (tương thích ngược).

### Lỗi [#lỗi]

Trả đúng mã HTTP + JSON `{ "error": "<CPP_CODE>", "message": "…" }`. Bộ mã chuẩn:
[Mã lỗi CPP\_\*](/docs/developer/errors).

## Checklist implement [#checklist-implement]

* [ ] `GET` trả capabilities với `protocol: 1` + `profile`/`accepts`/`locales`/`async`.
* [ ] `POST` đọc **RAW** body trước khi parse.
* [ ] Verify chữ ký đúng thuật toán; `401` khi sai; `401` khi lệch giờ > 300s.
* [ ] `test === true` → `200`, không lưu.
* [ ] Idempotent theo `webhook-id`; upsert theo `externalId` (else `slug`).
* [ ] Trả `{ id, url, status }`; `db` → 200 live, `fs-build` → 202 building.
* [ ] Lỗi trả mã `CPP_*` chuẩn.
* [ ] `CITELY_WEBHOOK_SECRET` đọc từ env, **không** hard-code.

<Callout type="info">
  Không muốn dựng receiver? Dùng adapter [`citely-api`](/docs/developer/adapters/citely-api) — Citely host bài, bạn chỉ *đọc* read-API.
</Callout>


# Ký & xác minh webhook (/docs/developer/webhook-signing)





Mọi `GET`/`POST` Citely gửi tới receiver đều được ký theo chuẩn mở
[Standard Webhooks](https://www.standardwebhooks.com/) (HMAC-SHA256) bằng
`CITELY_WEBHOOK_SECRET`. Receiver &#x2A;*verify chữ ký trên `POST`** trước khi lưu bất cứ gì.

## Headers trên mỗi delivery [#headers-trên-mỗi-delivery]

```
webhook-id:        msg_8b1f…        (idempotency key — dedupe trên cái này)
webhook-timestamp: 1751270400       (UNIX seconds — reject nếu lệch > 5 phút)
webhook-signature: v1,K5l8…         (danh sách "v1,<base64>" cách nhau bởi space)
content-type:      application/json
user-agent:        Citely/1.0 (+https://citely-seo.com)
```

## Thuật toán verify [#thuật-toán-verify]

```
id        = header "webhook-id"
ts        = header "webhook-timestamp"   (UNIX seconds)
sigHeader = header "webhook-signature"   (danh sách "v1,<base64>" cách nhau bởi space)

if !id || !ts || abs(now_seconds - ts) > 300:  reject (401 CPP_REPLAY)
key           = base64_decode( secret sau khi bỏ tiền tố "whsec_" )
signedContent = id + "." + ts + "." + rawBody
expected      = base64( HMAC_SHA256(key, signedContent) )
# tách sigHeader theo space; mỗi token lấy phần SAU dấu phẩy; so sánh constant-time.
# BẤT KỲ token nào khớp → hợp lệ. (Danh sách cho phép xoay secret.)
```

<Callout type="warn">
  Ký trên **RAW body** (bytes nguyên văn). Nếu bạn `JSON.parse` rồi `stringify` lại để ký, whitespace/thứ tự khoá đổi → chữ ký sai. Đọc raw trước, verify, rồi mới parse.
</Callout>

## Reference (Node/TypeScript, zero-dependency) [#reference-nodetypescript-zero-dependency]

```ts
import { Buffer } from 'node:buffer';
import crypto from 'node:crypto';

function verify(secret: string, body: string, h: Record<string, string>): boolean {
  const id = h['webhook-id'];
  const ts = h['webhook-timestamp'];
  const sig = h['webhook-signature'] ?? '';
  if (!id || !ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
    return false;
  }
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const exp = crypto
    .createHmac('sha256', key)
    .update(`${id}.${ts}.${body}`)
    .digest('base64');
  const eb = Buffer.from(exp, 'base64');
  return sig.split(' ').some((t) => {
    const s = Buffer.from(t.includes(',') ? t.slice(t.indexOf(',') + 1) : t, 'base64');
    return s.length === eb.length && crypto.timingSafeEqual(s, eb);
  });
}
```

Off-the-shelf tương đương:

```bash
npm i standardwebhooks
```

```ts
import { Webhook } from 'standardwebhooks';

const wh = new Webhook(process.env.CITELY_WEBHOOK_SECRET!);
wh.verify(rawBody, headers); // throw nếu chữ ký/timestamp sai
```

## Xoay secret [#xoay-secret]

Header `webhook-signature` là **danh sách** chữ ký (cách nhau bởi space). Khi bạn xoay
secret trong Citely, một giai đoạn ngắn Citely gửi nhiều chữ ký — receiver coi là hợp lệ
nếu **bất kỳ** token nào khớp. Nhờ vậy bạn xoay secret không downtime.

<Callout type="info">
  Sai chữ ký → trả `401 CPP_SIG_INVALID`. Lệch đồng hồ > 300s → `401 CPP_REPLAY`. Xem [Mã lỗi](/docs/developer/errors).
</Callout>


# Kết nối Google Search Console (/docs/guides/connect-google-search-console)





<Callout type="info">
  Trang đang hoàn thiện. Dưới đây là các bước chính.
</Callout>

Citely dùng **OAuth 3 bên**: bạn bấm "Kết nối Google", đồng ý, và Citely lưu **refresh token của
bạn** (theo từng tổ chức). Citely KHÔNG dùng service account hay GSC của nhà phát triển.

## Các bước [#các-bước]

1. Trong **Citely → Sites → (site) → Kết nối Google Search Console**.
2. Cửa sổ Google mở ra → chọn tài khoản **sở hữu property GSC** của website đó → **Đồng ý** cấp quyền.
3. Quay lại Citely — trạng thái chuyển sang *Đã kết nối*.
4. Từ đó Citely có thể đọc số liệu thứ hạng và (tuỳ tính năng) gửi yêu cầu lập chỉ mục.

<Callout type="warn">
  Tài khoản Google bạn chọn phải có quyền trên đúng **property** của website trong Search Console. Nếu chưa, thêm property/quyền trong GSC trước.
</Callout>


# Kết nối WordPress (/docs/guides/connect-wordpress)





<Callout type="info">
  Trang đang hoàn thiện. Dưới đây là các bước chính.
</Callout>

Citely kết nối WordPress qua **Application Password** (không cần plugin để bắt đầu).

## Các bước [#các-bước]

1. Trong **WordPress → Users → Profile → Application Passwords**, tạo một mật khẩu ứng dụng mới
   (đặt tên, ví dụ "Citely"). Copy chuỗi hiện ra.
2. Trong **Citely → Sites → Thêm site**, nhập:
   * **URL** website (vd `https://blog.example.com`)
   * **Username** WordPress của bạn
   * **Application Password** vừa tạo
3. Bấm **Kiểm tra kết nối** — Citely gọi thử REST API của WordPress.
4. Kết nối xong → bạn có thể [xuất bản bài](/docs/guides/publishing) thẳng lên site này.

<Callout type="warn">
  Nếu WordPress nằm sau tường lửa/WAF chặn IP lạ, kết nối trực tiếp có thể thất bại. Khi đó dùng **plugin Citely Companion** (kết nối theo chiều đi ra). Chi tiết sẽ bổ sung.
</Callout>


# Bắt đầu (/docs/guides/getting-started)





<Callout type="info">
  Trang đang hoàn thiện. Dưới đây là các bước chính.
</Callout>

## Các bước [#các-bước]

1. **Đăng ký & đăng nhập** tài khoản Citely.
2. **Tạo tổ chức (workspace).** Mỗi tổ chức quản lý website và tài khoản Google/WordPress riêng.
3. **Thêm website** vào mục *Sites* (xem [Kết nối WordPress](/docs/guides/connect-wordpress) hoặc [Citely Connect](/docs/developer) cho site không phải WordPress).
4. **Viết bài đầu tiên:** chọn *Viết từ từ khoá* → Citely nghiên cứu, lập dàn ý và sinh bài.
5. **Xuất bản:** đẩy bài ra website đã kết nối (xem [Xuất bản bài viết](/docs/guides/publishing)).

## Tiếp theo [#tiếp-theo]

* [Kết nối WordPress](/docs/guides/connect-wordpress)
* [Kết nối Google Search Console](/docs/guides/connect-google-search-console)


# Hướng dẫn sử dụng (/docs/guides)





Khu vực hướng dẫn dành cho **người dùng Citely** (không cần biết lập trình).

<Callout type="info">
  Đang hoàn thiện — các trang dưới đây có khung nội dung, sẽ được bổ sung chi tiết dần.
</Callout>

<Cards>
  <Card title="Bắt đầu" href="/docs/guides/getting-started" description="Đăng ký, tạo tổ chức, viết bài đầu tiên." />

  <Card title="Kết nối WordPress" href="/docs/guides/connect-wordpress" description="Dùng Application Password để Citely xuất bản lên site của bạn." />

  <Card title="Kết nối Google Search Console" href="/docs/guides/connect-google-search-console" description="Cấp quyền để theo dõi thứ hạng & lập chỉ mục." />

  <Card title="Xuất bản bài viết" href="/docs/guides/publishing" description="Đẩy bài ra website (WordPress hoặc site khác qua Citely Connect)." />
</Cards>

Bạn là nhà phát triển cần tích hợp website nhận bài từ Citely? Xem [tài liệu Nhà phát triển](/docs/developer).


# Xuất bản bài viết (/docs/guides/publishing)





<Callout type="info">
  Trang đang hoàn thiện. Dưới đây là các bước chính.
</Callout>

## Các bước [#các-bước]

1. Mở bài viết đã hoàn thiện trong Citely.
2. Chọn **Xuất bản** → chọn **site đích** (site đã kết nối).
3. Chọn trạng thái: **Xuất bản ngay**, **Nháp**, hoặc **Hẹn giờ**.
4. Citely đẩy bài (kèm ảnh, JSON-LD, meta SEO) sang site.

## Xuất bản đi đâu? [#xuất-bản-đi-đâu]

* **WordPress** → đăng thành bài WordPress (xem [Kết nối WordPress](/docs/guides/connect-wordpress)).
* **Website khác** (Astro/Next/Hugo/self-host) → qua **Citely Connect**. Site của bạn nhận bài theo
  giao thức CPP; xem [tài liệu Nhà phát triển](/docs/developer).

<Callout type="info">
  Với site tĩnh, bài có thể ở trạng thái *đang build* vài chục giây trước khi hiển thị — Citely tự theo dõi tới khi **live**. Xem [Trạng thái bất đồng bộ](/docs/developer/async-publish).
</Callout>


# citely-api (khuyến nghị) (/docs/developer/adapters/citely-api)





**Dùng khi:** bạn chỉ muốn *có bài trên site*, KHÔNG muốn dựng/duy trì backend (DB, endpoint,
xác thực webhook). Đây là **mặc định khuyến nghị** cho site mới.

Khác mọi adapter khác, `citely-api` **không có receiver**. Citely lưu bài đã enrich (HTML +
JSON-LD + meta + i18n) và phục vụ qua **read-API**. Website của bạn chỉ là một *reader*: fetch
bài rồi render dưới domain của bạn. Không HMAC, không DB, không build-server.

<Callout type="info">
  **Bất đối xứng:** `db`/`fs-build` = Citely **push** vào site (site có receiver). `citely-api` = site **pull** từ Citely (site có reader). Vì thế không có bước handshake `GET`/`POST` receiver ở đây.
</Callout>

## Chuẩn bị (làm 1 lần) [#chuẩn-bị-làm-1-lần]

1. Trong Citely: &#x2A;*Sites → Connect → "Citely-hosted (read-API)"** → tạo site.
2. Citely hiện: một **site token** công khai (dùng trong URL) + một **read-key** bí mật
   (Bearer). Đặt read-key vào env **phía server** là `CITELY_READ_KEY` (KHÔNG lộ xuống browser).
3. Publish bài như bình thường trong Citely → bài xuất hiện tức thì trên read-API.

## Đọc bài [#đọc-bài]

Base URL: `https://citely-seo.com/connect/v1/sites/{siteToken}`

| Method + path               | Auth                  | Trả về                      |
| --------------------------- | --------------------- | --------------------------- |
| `GET /posts/{slug}`         | công khai (cache CDN) | 1 bài                       |
| `GET /posts?limit=&cursor=` | `Bearer <read-key>`   | list phân trang             |
| `GET /export`               | `Bearer <read-key>`   | toàn bộ bài (chống lock-in) |

Chi tiết field, phân trang, mã lỗi: &#x2A;*[Read-API reference](/docs/developer/read-api)**.

## Dựng reader [#dựng-reader]

* **SSG** (Astro / Next export / Hugo): build-time fetch `GET /posts` (kèm read-key,
  server-side) → nạp slug vào `generateStaticParams` → fetch từng `GET /posts/{slug}`. Rebuild
  theo lịch hoặc qua deploy hook để nhận bài mới.
* **SSR** (Next SSR / Laravel / Rails): fetch `GET /posts/{slug}` mỗi request (public +
  edge-cache nên rẻ); trang list dùng `GET /posts` server-side với read-key.
* Render `html` as-is; mỗi `jsonLd[]` → `<script type="application/ld+json">` trong `<head>`.
  Đặt `<link rel="canonical">` về URL của CHÍNH bạn.
* Song ngữ: gom bài cùng `translationKey`, nối `<link rel="alternate" hreflang>`.

## Cache & độ sẵn sàng [#cache--độ-sẵn-sàng]

Read-API đứng sau **Cloudflare CDN** (Cache Everything + `s-maxage` + `stale-while-revalidate`

* Always Online): phần lớn read hứng ở edge. Khi bài được publish/sửa, Citely **purge cache**
  URL bài + list → bạn luôn thấy bản mới.

<Callout type="warn">
  Nội dung publish nằm trên web công khai → mục tiêu bảo mật là chống enumeration + abuse (Bearer + rate-limit + token khó đoán), KHÔNG hứa "giấu nội dung".
</Callout>


# db (site có database) (/docs/developer/adapters/db)





**Dùng khi:** site có **runtime + database** (Next.js SSR, Laravel, Astro SSR, Node/Nest,
Rails…). Case đơn giản nhất: publish xong **live ngay**, không cần rebuild.

Endpoint nhận bài → **upsert vào DB của bạn** → render động. Trả `200 { status: "live" }`.

<Callout type="info">
  **Chọn nền DB (ít bẫy nhất trước — tránh cold-pause):** Cloudflare **D1** (nếu ở CF Pages, không pause) › **Neon / Turso** (scale-to-zero, resume nhanh) › **Supabase** (⚠️ free pause sau 7 ngày → BẮT BUỘC kèm keep-alive cron ngoài). Nếu bạn "chỉ muốn có bài, khỏi backend" → dùng [`citely-api`](/docs/developer/adapters/citely-api).
</Callout>

## Handshake (`GET`) [#handshake-get]

```jsonc
{
  "citely": "receiver",
  "protocol": 1,
  "profile": "runtime-db",
  "storageAdapter": "db",
  "accepts": ["html"],
  "locales": ["vi", "en"],
  "async": false
}
```

`accepts: ["html"]` — site động thường lưu & render thẳng `html`. `async: false` → POST trả
`200 { status: "live" }`.

## Nhận bài (`POST`) — Next.js App Router [#nhận-bài-post--nextjs-app-router]

```ts
// app/api/citely/ingest/route.ts
export async function GET() {
  return Response.json({
    citely: 'receiver', protocol: 1, profile: 'runtime-db',
    storageAdapter: 'db', accepts: ['html'], locales: ['vi', 'en'], async: false,
  });
}

export async function POST(req: Request) {
  const raw = await req.text(); // RAW body trước khi parse
  const h = Object.fromEntries(req.headers) as Record<string, string>;
  if (!verify(process.env.CITELY_WEBHOOK_SECRET!, raw, h)) {
    return Response.json({ error: 'CPP_SIG_INVALID' }, { status: 401 });
  }

  const a = JSON.parse(raw);
  if (a.version !== 1) {
    return Response.json({ error: 'CPP_VERSION_UNSUPPORTED' }, { status: 400 });
  }
  if (a.test === true) {
    return Response.json({ ok: true });
  }

  try {
    const post = await db.posts.upsert({
      where: a.externalId ? { id: a.externalId } : { slug: a.slug },
      create: {
        title: a.title, slug: a.slug, body: a.html, excerpt: a.excerpt,
        jsonLd: a.jsonLd, cover: a.cover, locale: a.locale,
        translationKey: a.translationKey, tags: a.tags,
        author: a.author?.name, publishedAt: a.publishedAt, noindex: a.noindex,
      },
      update: {
        title: a.title, body: a.html, excerpt: a.excerpt,
        jsonLd: a.jsonLd, cover: a.cover, tags: a.tags, modifiedAt: a.modifiedAt,
      },
    });
    return Response.json({ id: String(post.id), url: `https://site.com/blog/${a.slug}`, status: 'live' });
  } catch (e) {
    return Response.json({ error: 'CPP_STORAGE_FAILED', message: String(e) }, { status: 500 });
  }
}
```

`verify` = hàm [Standard Webhooks](/docs/developer/webhook-signing).

## Lưu ý [#lưu-ý]

* **JSON-LD:** lưu `a.jsonLd` (mảng), emit mỗi phần tử thành `<script type="application/ld+json">`
  trong `<head>`. **Đừng** nhét vào `body` html.
* **ISR/cache (Next):** nếu trang blog cache tĩnh, gọi `revalidatePath('/blog/' + slug)` sau upsert.
* **Idempotency:** dedupe theo header `webhook-id` nếu muốn tuyệt đối an toàn khi Citely retry.


# fs-build (site tĩnh self-host) (/docs/developer/adapters/fs-build)





**Dùng khi:** site tĩnh (Astro/Hugo/Eleventy) **self-host trên máy chủ riêng** (VPS, không
deploy qua GitHub CI). Bạn có một **process thường trú** (Node/PM2, PHP, systemd).

Endpoint nhận bài → **ghi `.md` vào thư mục content** → **kích build** → nginx phục vụ `dist/` mới.

## Chuẩn bị [#chuẩn-bị]

* Một service nhỏ (Express/Fastify) chạy cạnh site, hoặc một route trong app runtime sẵn có.
* Env: `CITELY_WEBHOOK_SECRET`, `CONTENT_DIR=/var/www/site/src/content/blog`,
  `BUILD_CMD="npm --prefix /var/www/site run build"`.

## Handshake (`GET`) [#handshake-get]

```jsonc
{
  "citely": "receiver",
  "protocol": 1,
  "profile": "static-fs",
  "storageAdapter": "fs-build",
  "accepts": ["markdown"],
  "locales": ["vi"],
  "async": true
}
```

## Nhận bài (`POST`) — Node/Express [#nhận-bài-post--nodeexpress]

```ts
import { exec } from 'node:child_process';
import { writeFile } from 'node:fs/promises';
import express from 'express';

const app = express();
app.use(express.raw({ type: '*/*' })); // cần RAW body để verify chữ ký

app.get('/api/citely/ingest', (_req, res) =>
  res.json({
    citely: 'receiver', protocol: 1, profile: 'static-fs',
    storageAdapter: 'fs-build', accepts: ['markdown'], locales: ['vi'], async: true,
  }));

app.post('/api/citely/ingest', async (req, res) => {
  const raw = req.body.toString('utf8');
  const h = req.headers as Record<string, string>;
  if (!verify(process.env.CITELY_WEBHOOK_SECRET!, raw, h)) {
    return res.status(401).json({ error: 'CPP_SIG_INVALID' });
  }

  const a = JSON.parse(raw);
  if (a.version !== 1) {
    return res.status(400).json({ error: 'CPP_VERSION_UNSUPPORTED' });
  }
  if (a.test === true) {
    return res.status(200).json({ ok: true });
  }

  try {
    const fm = toFrontmatter(a); // map field CPP → Zod repo
    await writeFile(`${process.env.CONTENT_DIR}/${a.slug}.md`, `---\n${fm}\n---\n\n${a.markdown}\n`);
  } catch (e) {
    return res.status(500).json({ error: 'CPP_STORAGE_FAILED', message: String(e) });
  }

  // Kích build BẤT ĐỒNG BỘ — không chờ build xong trong request (tránh timeout).
  exec(process.env.BUILD_CMD!, err => err && console.error('build failed', err));

  return res.status(202).json({ id: a.slug, url: `https://your-site.com/blog/${a.slug}`, status: 'building' });
});
```

`verify` = hàm [Standard Webhooks](/docs/developer/webhook-signing).

<Callout type="warn">
  **Đừng chạy build đồng bộ trong request.** Build vài chục giây → Citely timeout. Trả `202 building` NGAY, build nền; Citely poll `url` tới khi live ([chi tiết](/docs/developer/async-publish)).
</Callout>

## Lưu ý [#lưu-ý]

* **Chống race build:** nhiều bài về dồn dập → debounce build (ghi hết file rồi build một lần).
* **An toàn lệnh:** `BUILD_CMD` là hằng số, **không** ghép chuỗi từ payload → tránh command
  injection. Sanitize `slug` (chặn `..`, `/`) trước khi ghép path.