Site files: product feeds and plain files on the storefront host

Резюме по-русски. Файлы на хосте витрины — на корне или в разделе дерева: фиды Яндекса (YML) и Google (XML), CSV, ads.txt, верификация, простая html-страница без скриптов. Тело — шаблон Go на живом каталоге. Здесь — короткий вход; полный справочник по разделам — /docs/feeds-reference?section=<slug>.

Status: draft · Verified: 2026-09-24 against branch feature/site-files-feeds · Owner: site files line (ФИДЫ-РЕКЛАМЫ) Serves: GET /docs/feeds · full reference GET /docs/feeds-reference

What site files are

A site file is {category_id, name, body, is_published, in_sitemap} served by the shop's storefront host at the root (category_id 0) or under any category (/sofas/feed.yml); the full path is computed. The body is a Go text/template (≤ 64 KB) rendered on the live catalogue as an anonymous buyer sees it, at storefront listing prices: a Yandex YML or Google Merchant feed, CSV/JSON for a partner, ads.txt, a verification file, a simple .html page. Scopes site-files:read / site-files:write, owner or administrator only, writes with a production key only.

How it works

• Serving: https://<host>/<path> on the shop host and its custom domain; Content-Type by extension, ETag/304, X-Robots-Tag: noindex except .html, Content-Security-Policy: sandbox on every answer — scripts never run (interactive pages are HTML widgets).
• Cache: one built copy per file and host, up to 60 minutes; a file edit or a catalogue change is seen within ~15 s. A failed render of an unedited file serves the last good copy (≤ 7 days) — only preview shows the error.
• Publish: is_published: false — stored and previewable, 404 on the host; the site itself must be published (no PIN). in_sitemap: true lists a published .html file in /sitemap.xml.
• Nesting: the path follows the category's slugs — renaming a slug moves the URL; a deleted category leaves the file orphaned (404).
• Permanent address: /_file/<id> serves the same file wherever it lives now, with Link: rel="canonical" to the current path.

Quick start: three requests

# 1. the reference body (yandex_yml, google_xml, empty)
curl -s "$API/site-files/templates" -H "$T"
# 2. render it on 20 live products without saving → errors: []
curl -s -X POST "$API/site-files/preview" -H "$T" -H "$J" \
  -d '{"path":"/yandex-feed.yml","body":"…","limit":20}'
# 3. create it published (add "category_id" to put it under a section)
curl -s -X POST "$API/site-files" -H "$T" -H "$J" \
  -d '{"name":"yandex-feed.yml","body":"…","is_published":true}'

Then fetch the returned url: 200 and the expected offer count. The full walk-through with jq is ?section=3-quick-start-a-yandex-feed-in-three-requests.

Key rules

• Refer by id, never by path. Find ids with GET /site-files?q=…. Inside a site file link with file_url ID, file_path ID, category_url ID, product_url ID; anywhere else (widgets, components, menus) with /_file/<id>. Both follow a moved or renamed target.
• Escaping is automatic per format (XML, HTML, CSV, JSON): write only the constant markup; no CDATA, no quotes around {{ }} in CSV, never html, js, urlquery.
• Preview after every edit: saving checks syntax only (SITE_FILE_TEMPLATE_INVALID with the line); wrong fields, options and category slugs surface in POST /site-files/preview or on the host.
• Safe edit: send row_version back as know_version; a concurrent save answers SITE_FILE_VERSION_CONFLICT.
• One product out of every feed: PUT /products/{id}/ad-participation {"mode":"exclude"} (catalog:write); a category out of one feed: exclude_category= in that template.
• Limits: name [A-Za-z0-9._-]{1,120} + .xml .yml .csv .txt .json .html; body 64 KB; render 30 s / 50 MB; 50 000 products per range; preview 30 calls a minute. Tariff site_files_max: Free 5, Pro 50 live files per shop (SITE_FILE_LIMIT_REACHED, 429). Machine block: ?section=11-limits.

Reference: sections

GET /docs/feeds-reference?section=<slug>: