> העתק ציבורי של מדריך המפתחים של ViewStream (לקריאה גם על ידי סוכני AI). רשימת המדריכים: https://www.viewstream.co.il/he/developers/guide/index.md · תיעוד ה-API: https://api.viewstream.co.il/docs/

# ה-API של Sites Delivery

ה-API של Sites Delivery הוא ה-API **הציבורי, לקריאה בלבד וניתן לשמירה במטמון** שמאחורי ViewStream Sites. מנוע ההצגה המתארח
של האתרים משתמש בו; גם אתם יכולים להשתמש בו כדי לבנות ממשק קדמי (front end) משלכם (אתר, אפליקציה, טלוויזיה חכמה) על התוכן שאתם מנהלים ב-Studio ←
אתרים.

- בסיס: `https://api.viewstream.co.il/s/v1/{site}/…` — `{site}` הוא ה-slug של האתר (Studio ← **אתרים**).
- בלי מפתח API. מוחזר רק תוכן שפורסם (טיוטות דורשות טוקן תצוגה מקדימה).
- מסמך OpenAPI נפרד: `https://api.viewstream.co.il/openapi/sites-delivery.yaml` (בחרו **Sites Delivery API**
  ב-`/docs/`).
- מקורות: הנתיבים ב-sites/delivery.go (באנגלית); ההתנהגות מתוארת
  ב-sites.md (באנגלית); אפיון המוצר
  viewstream-sites-spec.md (באנגלית).

צד הניהול (עריכת אתרים, עמודים, תוכניות, אנשים, תפריטים, ערכת עיצוב) הוא ה-API הרגיל של `/v1` עם ההרשאות
`sites:*` — ראו [getting-started.md](getting-started.md#3-הרשאות).

## נתיבים

| נתיב | מה מוחזר |
|---|---|
| `GET /s/v1/{site}/config` | האתר: טוקנים של ערכת העיצוב, תפריטים שפורסמו, מילון, סקריפטים, הסכמה (consent), נגישות, SEO, הנגן (`tenant`, `config`, `cdn_hostname`), הגדרות EPG, אזור זמן, מצב זחלני AI |
| `GET /s/v1/{site}/route?path=/show/evening-news` | מה הנתיב מייצג: `{kind: page \| template \| redirect \| not_found, page_id?, template_for?, entity?, redirect?}`. הסדר: הפניות, נתיבי עמודים, טבלת הנתיבים של האתר, ואז הנתיבים המובנים (`/show/:slug`, `/podcast/:slug`, `/v/:slug`, `/c/:slug`, `/p/:slug`, `/live/:slug`, `/person/:slug`, `/category/:slug`, `/search`, `/epg`) |
| `GET /s/v1/{site}/pages/{id}?sections=5[&entity=type:slug][&preview=<token>]` | גרסת העמוד שעולה כרגע, כש-N המקטעים הראשונים כבר מפוענחים (`items`, `more`), `next_cursor`, והישות עבור תבניות |
| `GET /s/v1/{site}/pages/{id}/sections?cursor=&count=` | המקטעים הבאים של עמוד |
| `GET /s/v1/{site}/entities/{type}/{slug}` | פריט אחד (תוכנית, סרטון, קליפ, תוכנית משודרת, ערוץ, אדם …) עם `playback {mode, src, tenant, channel?, kind}`, ה-`now`/`next` של ערוץ, סדרות ואנשים; תוכניות משודרות וסרטונים כוללים גם `article` אחרי שעורך פרסם את כתבת ה-AI שלהם (`headline`, `standfirst`, `summary`, `chapters`, `quotes` עם `start_ms`, `entities`, `tags`, `label`, `reviewed`) — אף פעם לא טיוטה |
| `GET /s/v1/{site}/epg?channel=&day=YYYY-MM-DD` | יום אחד בלוח השידורים (היום לפי `Asia/Jerusalem`) עם `catchup`, `start_over`, `start_over_src`, `series`; ערוצים שפורסמו בלבד |
| `GET /s/v1/{site}/search?q=&type=&cursor=` | חיפוש שמותאם לעברית בתוכניות, בסרטונים ובתוכניות של צפייה חוזרת |
| `GET /s/v1/{site}/suggest?q=` | עד 8 הצעות מהירות |
| `GET /s/v1/{site}/sitemap/{index\|pages\|shows\|videos\|programmes}.xml` | מפות אתר (מפת אתר לווידאו עבור סרטונים, קליפים וצפייה חוזרת) |
| `GET /s/v1/{site}/robots` | קובץ ה-robots.txt של האתר |
| `GET /s/v1/{site}/podcast/{slug}/feed.xml` | פיד RSS של פודקאסט של תוכנית |
| `GET /s/v1/_host?…` | דומיין מותאם ← slug של אתר (משמש את מנוע ההצגה) |

## כללי זמינות

- תוכנית מציעה **צפייה חוזרת** כשהיא הסתיימה, התחילה בתוך תקופת השמירה של הערוץ ואחרי הדקה הראשונה שהוקלטה בערוץ,
  ואינה מוחרגת על ידי כלל החרגה מצפייה חוזרת.
- **צפייה מההתחלה** מוצעת כל עוד התוכנית משודרת, אם תחילתה הוקלטה.
- סרטונים מופיעים כשהם `ready` ומפורסמים; קליפים כשהם `ready` או `final`.

## תמונות

לפריטים יש `images` עם כתובות WebP לכל תבנית: `tile_16x9` (640×360), `tile_16x9_320` (320×180, המועמדת לטלפון),
`tile_1x1`, `tile_2x3`, `poster` (1280×720), `hero_16x9` (1920×1080), `title_art`. כל מפתח הוא אופציונלי — בהיעדרו חזרו ל-
`tile_16x9`. `srcset` מומלץ: `tile_16x9_320 320w, tile_16x9 640w, poster 1280w`.

## שמירה במטמון

| כותרת | ערך |
|---|---|
| `Cache-Control` | `public, s-maxage=30, stale-while-revalidate=300, stale-if-error=86400` (מפות אתר 600 שניות, robots 3600 שניות; תשובות של תצוגה מקדימה `private, no-store`) |
| `ETag` | שלחו `If-None-Match` כדי לקבל `304` |
| `Cache-Tag` | `site:<id>, page:<id>, entity:<type>:<id>…` (משמש לניקוי מטמון) |
| `X-VS-Sites-API` | `1` — גרסת ה-API |
| CORS | מותר לשמות המארח של האתר עצמו ול-Studio |

עמוד עם שינוי מתוזמן מגביל את `s-maxage` עד לרגע השינוי, כך שההחלפה מתבצעת בזמן.

## שגיאות

השגיאות הן `application/problem+json` עם `Cache-Control: no-store`. אתר מושעה או לא מוכר עונה `404`
(`"no such site"`). כש-Sites לא מופעל בפריסה, כל הנתיבים עונים `503`.

הערה: ה-URI של `type` כאן נגזרים מטקסט הסטטוס של HTTP (`…/problems/not-found`), ולא מקודי ה-`snake_case`
של ה-API הראשי (`…/problems/not_found`) — ראו פערים ידועים.

## רכיבי Web

אריחים ורכיבי נגן מוכנים לעמודים שלכם: `@viewstream/sites-wc`
(`https://player.viewstream.co.il/sdk/sites-wc@0.2.4.js`, הדגמה ב-`/sdk/demo.html`; תיעוד ב-
studio/packages/sites-wc/README.md (באנגלית)). ראו גם
[player-integration.md](player-integration.md).