# API ของหน้าออกแบบ — สร้างและแก้หน้าด้วยสคริปต์

> endpoint ของหน้า คอมโพเนนต์ เมนู และสื่อ, โครงสร้าง node ของหน้าออกแบบ, class ที่ render ออกมา, ชื่อสำหรับโค้ด (data-ref) และข้อควรระวังเวลาเรียกผ่าน Cloudflare

ที่มา: https://anasaki.live/docs/developers/designer-api

หน้าทุกหน้าที่สร้างในหน้าออกแบบเก็บเป็น **ต้นไม้ของ node (JSON)** ในฟิลด์ `design` ของบทความ สคริปต์และเครื่องมือ AI จึงสร้างหรือแก้หน้าได้ด้วย REST API ชุดเดียวกับที่หลังบ้านใช้ หน้านี้รวบรวมสิ่งที่ต้องรู้ไว้ที่เดียว (CMS 2.2.0)

## การยืนยันตัวตน

ส่ง `Authorization: Bearer ` ทุกคำขอ token ได้จาก `POST /api/v1/auth/login {email, password}` หรือ token ระยะยาวจาก `POST /api/v1/auth/tokens` การแก้ดีไซน์ต้องมีสิทธิ์ `edit_pages` และถ้ามีบล็อกโค้ดต้องมี `edit_scripts` ด้วย

> **ใช้ผ่าน Cloudflare:** ถ้าเว็บอยู่หลัง Cloudflare คำขอที่ไม่มี `User-Agent` หรือใช้ค่าเริ่มต้นของไลบรารีบางตัว เช่น `urllib` ของ Python จะได้ `403 error code: 1010` (Browser Integrity Check) ให้ตั้ง `User-Agent` เอง เช่น `my-script/1.0` หรือสร้าง WAF rule ยกเว้น `/api/v1/*` ที่มี header `Authorization`

```python
import json, urllib.request
req = urllib.request.Request(&#34;https://example.com/api/v1/posts/11&#34;,
    headers={&#34;Authorization&#34;: &#34;Bearer &#34; + TOKEN, &#34;User-Agent&#34;: &#34;qraft-sync/1.0&#34;})
page = json.load(urllib.request.urlopen(req))
```

## Endpoint

| Method | Path | ใช้ทำอะไร |
| --- | --- | --- |
| GET | `/api/v1/posts?type=page` | รายการหน้า (`perPage`, `page`, `q`, `status` = `draft` / `publish` / `scheduled` / `any`) |
| GET | `/api/v1/posts/{id}` | หน้าเดียว พร้อม `design`, `updatedAt` และ `draft` (ถ้ามีฉบับร่าง) |
| POST | `/api/v1/posts` | สร้าง `{type:&#34;page&#34;, title, slug?, status?, design?}` |
| PUT | `/api/v1/posts/{id}` | แก้ `{title?, slug?, status?, design?, baseUpdatedAt?, asDraft?, discardDraft?}` |
| GET / POST / PUT | `/api/v1/components` · `/api/v1/components/{id}` | ส่วนที่ใช้ซ้ำ `{name, node, baseUpdatedAt?}` |
| GET / POST / PUT | `/api/v1/menus` · `/api/v1/menus/{id}` | เมนู `{name, items:[{label, url}]}` |
| POST | `/api/v1/media` (multipart `file`) | อัปโหลดรูป/ไฟล์ → `{id, url, width, height}` |
| GET | `/api/v1/settings` → `theme` | สีและฟอนต์ของเว็บ (`var(--c-)`) และ `breakpoints` |
| POST | `/api/v1/links/replace {from, to}` | เปลี่ยนลิงก์ทุกที่ (ดีไซน์ คอมโพเนนต์ เมนู) เมื่อย้ายที่อยู่หน้า |

- **กันเขียนทับ:** ส่ง `baseUpdatedAt` เป็นค่า `updatedAt` ที่อ่านมา ถ้ามีคนบันทึกใหม่กว่าในระหว่างนั้น ระบบตอบ `409` แทนการทับงานของเขา
- **id ของชั้นต้องไม่ซ้ำ:** ถ้า id ซ้ำ ระบบตอบ `400` พร้อมบอก id นั้น (ตั้งแต่ 2.1.1)
- **หมวดของบทความ:** `terms: {&#34;category&#34;: [&#34;news&#34;, 12]}` รับได้ทั้ง slug และ id
- **status:** ไม่ใส่ หรือ `any` / `all` = ทุกสถานะ ค่าอื่นที่ไม่รู้จักตอบ `400` (ตั้งแต่ 2.3.0 ก่อนหน้านี้ได้รายการว่าง)
- **ฉบับร่างของหน้าที่เผยแพร่แล้ว (2.3.0):** `asDraft: true` เก็บ `title` / `slug` / `design` ไว้ใน `draft` ของหน้า ผู้เยี่ยมชมยังเห็นฉบับที่เผยแพร่ ส่งอีกครั้งโดยไม่มี `asDraft` (หรือ `status: &#34;publish&#34;`) เพื่อเผยแพร่ ส่ง `discardDraft: true` เพื่อทิ้งฉบับร่าง — หน้าที่ยังไม่เผยแพร่ `asDraft` ไม่มีผล (บันทึกตามปกติ)
- **ยืนยันตัวตน:** สคริปต์ใช้ `Authorization: Bearer` ส่วนหน้าจัดการ (2.3.0) ใช้คุกกี้ `HttpOnly` คู่กับ header `X-Anasaki-Session: cookie` คุกกี้อย่างเดียวไม่นับเป็นการล็อกอิน
- ทุกการบันทึกเก็บเวอร์ชันก่อนหน้าไว้ ดูได้ที่ `GET /api/v1/posts/{id}/revisions` (25 เวอร์ชันล่าสุด)

## โครงสร้าง node

```ts
interface Node {
  id: string;                 // ไม่ซ้ำในหน้า → class n-<id>
  type: 'frame' | 'text' | 'rect' | 'image' | 'button' | 'menu' | 'postList' | 'postContent' | 'instance'
      | 'embed' | 'collection' | 'pluginBlock' | 'download' | 'breadcrumb' | 'icon' | 'shape' | 'vector'
      | 'pagination' | 'input' | 'codeblock';
  name?: string;              // ชื่อในแผงชั้น
  visible?: boolean; locked?: boolean;
  absolute?: boolean; x?: number; y?: number;   // วางอิสระในกล่อง auto layout
  width: Size; height: Size;  // { mode: 'fixed', value: 320 } | { mode: 'fill' } | { mode: 'hug' }
  layout?: { mode?: 'none' | 'horizontal' | 'vertical'; gap?: number; padding?: [top, right, bottom, left];
             align?: 'start' | 'center' | 'end' | 'stretch'; justify?: 'start' | 'center' | 'end' | 'between';
             wrap?: boolean; columns?: number };
  style?: Style;              // ด้านล่าง
  props?: Record<string, any>; // ตามชนิด ด้านล่าง
  responsive?: { tablet?: Override; mobile?: Override };  // ค่าที่ต่างไปบนจอเล็ก (มือถือได้ค่าของแท็บเล็ตด้วย)
  children?: Node[];
}
// Override = { x?, y?, width?, height?, visible?, layout?: Partial<layout>, style?: Partial<style> }
```

**style ที่ใช้บ่อย:** `fill` `color` `stroke` + `strokeWidth` (+ `strokeStyle`) `radius` / `radii` `shadow` `opacity` `fontFamily` (ใส่หลายฟอนต์คั่นด้วยจุลภาคได้ เช่น `&#34;Kanit, system-ui&#34;`) `fontSize` `fontWeight` `lineHeight` `letterSpacing` `textAlign` `maxWidth` `minHeight` `minHeightScreen` + `minHeightOffset` (สูงเท่าจอ หักแถบเมนู) `backgroundImage` `overlay` `objectFit` `hover: {fill, color, stroke, scale, lift, shadow, opacity, duration}` `active: {fill, color, stroke}` (แท็บที่เลือก / ลิงก์ของหน้าปัจจุบันในเมนู) `anim: {type: 'fade' | 'up' | …, delay, duration}` `textStyle` (id ของสไตล์ตัวอักษรในธีม) และสำหรับเมนู `linkPadding: [v, h]` `linkRadius`

**props ตามชนิด**

| ชนิด | props |
| --- | --- |
| `text` | `text`, `rich` (HTML ย่อย), `tag` (`h1`…`p`), `href`, `newTab` |
| `button` | `text`, `href`, `newTab`, `icon` (ชื่อไอคอน), `iconPosition: 'end'`, `action` |
| `image` | `src`, `alt`, `href`, `lightbox` (2.4.0: กดแล้วเปิดรูปเต็มในแกลเลอรี จัดกลุ่มตามเฟรมที่ครอบ) |
| `menu` | `menuId`, `burger` (พับเป็น ☰ บนมือถือ) |
| `postList` | `query: {postType, category, limit, order}` + การ์ดใบแรกเป็น `children` |
| `input` | `kind` (`text` `search` `select` `checkbox` …), `name`, `placeholder`, `value` (+ `valueText: true` = ข้อความตรงตัว), `options`, `filter: {collection, param}` |
| `codeblock` | `html`, `css` (`:scope` = ตัวบล็อก), `js` |
| `instance` | `componentId`, `variant`, `overrides` |
| `icon` | `icon`, `strokeWidth`, `label` |

ทุกชนิดมี `props.ref` (ชื่อสำหรับโค้ด) และ `props.showWhen` (เงื่อนไขแสดง) ได้

## class ที่ render ออกมา

- แต่ละชั้นได้ `class=&#34;n-&#34;` ซึ่งคงที่ตราบที่ id ไม่เปลี่ยน ส่วนชั้นข้างในคอมโพเนนต์ที่วางไว้ได้ `n--`
- id เปลี่ยนได้เมื่อ **ทำซ้ำ วาง หรือแยกคอมโพเนนต์** และหน้าออกแบบจะตั้ง id ใหม่ให้ชั้นที่ซ้ำกันตอนเปิดหน้า โค้ดที่ต้องการชื่อถาวรจึงควรใช้ **ชื่อสำหรับโค้ด** แทน

## ชื่อสำหรับโค้ด (data-ref)

ตั้งได้ที่แท็บ **เนื้อหา → ชื่อสำหรับโค้ด** ของทุกชั้น (หรือ `props.ref` ใน API) ระบบ render เป็น `data-ref=&#34;&#34;` และบล็อกโค้ดหาชั้นนั้นได้ด้วย

```js
const btn = anasaki.ref('download');           // ตัวแรก (หรือ null)
anasaki.refs('card').forEach(c => …);          // ทุกตัว เช่น การ์ดในรายการ
```

ชื่อใช้ได้ `a-z` ตัวแรก ตามด้วย `a-z A-Z 0-9 _ -` ไม่เกิน 40 ตัว แผงชั้นแสดงป้าย `` ที่ชั้นซึ่งมีชื่อสำหรับโค้ด ผู้ออกแบบจะได้รู้ว่ามีโค้ดอ้างถึงชั้นนั้นอยู่

## ไฟล์ที่บล็อกโค้ดใช้ร่วมกัน

ไฟล์ในโฟลเดอร์ `public/` ของ Site Code (เช่น `public/qr.js`, `public/base.css`, `.svg`, `.txt`, `.json`) จะไม่ถูก bundle แต่เวอร์ชันที่เผยแพร่จะเสิร์ฟไฟล์เหล่านี้ที่ `/site-assets/` บล็อกโค้ดโหลดไฟล์ที่ใช้ร่วมกันได้ครั้งเดียวต่อหน้า:

```js
await anasaki.lib('qr');        // รัน /site-assets/qr.js หนึ่งครั้ง (ทุกบล็อกรอ promise เดียวกัน)
await anasaki.style('base');    // ใส่ /site-assets/base.css
```

ใน Site Code ใช้ `site.asset('public/qr.js')` เพื่อได้ `url` (พร้อม `?v=` และ cache หนึ่งปี) และ `text()`
