Документация API
Документация для разработчиков и ИИ-агентов. Тексты живут в бэке и обновляются вместе с ним.
Для агентов: llms.txt · openapi.json · /docs/skills
Текст страницы ещё не написан. Ниже — техническое задание: по нему юрист или нейросеть готовит текст. Исходник ТЗ: packages/legal/tz/docs-home.md
Начало работы
Руководства
Family cards on a category pagebuild a level-1 family-card component and two insertions, verify it and roll it back/docs/guide-family-cardsTransfer a finished site into a Vizen shopdraft: you already HAVE a site, template or export — move it 1:1, do not rebuild it: a folder is a level-3 widget in real page DOM (scripts run, position:fixed works), header/footer are chrome groups, site-wide CSS is the layout folder, shop data is re-bound with vz- keysdraft/docs/transferVizen catalogue import via the APIfilling a catalogue end to end: categories, attributes, variants, groupings, gallery by groups, publication/docs/catalog-importWeb coding guide: build a shop page with codebuilding a shop page with your own HTML/CSS/JS: modes, layout parameters, images, page assembly, limits, page layers/docs/webcodingReady-made modules for your markupready-made modules for your own markup — copy a snippet instead of drawing your own: lightbox, product window (quick view), gallery zoom, variant picker, cart and favourites, search, menu, toggle, form button, variant chips, live state/docs/modules
Справочник
Области API
Forms, leads and CRM boardscreate and insert forms, open them with form:<id>, submit a quiz, manage leads and CRM boards, choose a test mode without confusing dev drafts with live delivery/docs/formsCatalogue: products, categories, filters, imagesbefore reading or filling a shop's goods: a filter written without the `filter.` prefix is swallowed and returns the WHOLE catalogue with a 200 — compare `total` before and after/docs/catalogueCharacteristics: definitions, groups, templates, values and filtersbefore creating characteristics, options, filters or spec templates: a filter needs a binding to THAT section with is_filterable, or a template row with filterable_here, plus list access — miss one and the panel stays empty with a 200; repeating records (reviews, Q&A, galleries) are /docs/record-sets/docs/characteristicsRecord sets: repeating records in products and sectionsbefore storing or showing reviews, Q&A, galleries, authors or documents on a product or section: the set must be opened to buyers, the site reads GET /record-sets on the API origin (base64 → UTF-8 → JSON, always pass code), records are not in the template scope/docs/record-setsReviews: buyer reviews, moderation, seller repliesbefore reading, adding, moderating or replying to buyer reviews, or choosing who may post them (anyone, only buyers of the product, only the shop): moderation is always on, a draft key cannot write, buyer posting is a session action/docs/reviewsFile storage, Studio folders and static site foldersbefore using Studio folders or uploading a multi-page static site: storage UUID collections, site-folder release paths and feed templates are different APIs; inspect scopes, per-file limits and URL routing; also choosing what opens at / (any section or a site folder, /v1/home-page)/docs/file-storageWidgets area (prose): platform blocks and their settingsthe fast path: platform blocks with live data, a look as wide as their props. Props are nested (`props.listing.…`); writing to the root of `props` is accepted and does nothing/docs/widgets-areaOwn markup: your HTML, CSS and JS in a Vizen shopthe bespoke path: your own HTML/CSS/JS over live shop data — vz- keys, what the block wrapper does to your layout, images through the resizer/docs/own-markupComponents: one piece of markup, many insertionsthe SAME markup on many pages with different content: a folder with `component.json` beside `index.html` and `{{key}}` in the markup — the owner fills the values, a new release updates every insertion at once. One page, one piece of code — stay on own-markupdraft/docs/componentsSite chrome: header, menu, footer and the page skeletonheader, menu, footer and the page skeleton: a GROUP lists blocks and a slot binds it, groups take ANY block including your own markup — that is how a custom header is made; a slot bound to 0 means "nothing here"/docs/chromeEditorial content: rubrics, materials and their feedseditorial pages — rubrics, dated materials and their feeds: a rubric is a category with `type: "news"` and is created UNPUBLISHED (404 until published); the cover and title of a material are drawn by the template's `articleHeader` widget, so a heading in the body is a second H1; `sidebar_config` is accepted and does nothing/docs/newsQuantity pricing rulesbefore adding wholesale or quantity prices: a pricing rule fixes the unit price and hard-locks promotions; it is not a discount, cost field or staff role/docs/pricingPromotions, combo sets, coupons and promo codesbefore printing any price next to a discount: the price a shopper sees is COMPUTED from rules, not stored, so a client that recomputes it disagrees with the cart on the first product two rules touch/docs/promotionsOrders and the cart: one snapshot, four statusesdraft: an order is a SNAPSHOT — nothing recomputes its money after checkout, and editing a promotion afterwards changes no existing order. Four statuses, freely in both directionsdraft/docs/ordersWebhooks: events delivered to your endpoint, signed, at least oncebefore building a receiver: a signed POST per event, at least once and unordered — dedupe by `event_id`, answer 2xx within 10 s, and never treat the event as the source of truth/docs/webhooksStock: the number, the ledger and the rounds of a cancelled orderdraft: stock is a NUMBER plus a LEDGER. `NULL` means "not tracked" (a service, a made-to-order item), not "zero" — otherwise a seller who never set stock reads as sold outdraft/docs/stockTasks: boards and cards of the shop's own workthe shop's own work — task boards and cards (`tasks:*`, not leads): 64-bit ids are JSON strings, `extra` is base64 of a whitelisted object, `column_id: 0` is the intake, board and column endpoints take the right of the board's kind, assignee ids come from `GET /v1/orgs/{company_id}/members`, and a misspelled `GET /tasks` filter returns every task/docs/tasksSite files: product feeds and plain files on the storefront hostfiles on the storefront host under `site-files:*` — at the root or under any category (`category_id` + `name`, the full `path` is computed): Yandex YML and Google Merchant feeds, CSV, ads.txt, verification files, simple .html pages (scripts never run: CSP sandbox; interactive pages are HTML widgets): a Go template rendered on the live catalogue at listing prices with values escaped per format; saving checks syntax only, `POST /site-files/preview` catches the rest; `/products/{id}/ad-participation` keeps a product out of every feeddraft/docs/feedsStorefront redirects: old addresses that keep their trafficbefore moving, renaming or deleting a category, product or article, or when old addresses must keep their traffic (`redirects:*`): exact rules, masks (`*`, `**`, `$1`), prefixes, `query_match`, the nearest-section fallback, the CSV exchange, the 404 log of missed addresses; before `POST /categories/move` call it with `dry_run: true` and ask the user whether to pin the old addresses with `pin_rules`draft/docs/redirectsStorefront resource accessbefore building anything for a shop that is still under construction: a site can be UNPUBLISHED — closed behind a short numeric PIN, `Disallow: /` for crawlers, three wrong PINs locking an address out for 10 minutes. The PIN is readable in plain text by the owner. The per-resource password matrix below it is still stageddraft/docs/resource-access
Полные справочники
Site files: full referencethe full site files reference behind /docs/feeds: requests, template language and functions, recipes, serving and cache, ad participation, silently ignored, checklists, the limits JSON — read one section with ?section=<slug>draft/docs/feeds-referenceStorefront redirects: full referencethe full storefront redirects reference behind /docs/redirects: endpoints with JSON, the CSV exchange, the address check, the storefront's matching order (301/302 vs 308/307), mask grammar, the URL lifecycle of a move, rename and delete, loops, refusal codes, the limits JSON — read one section with ?section=<slug>draft/docs/redirects-referencevz- keys: your own markup on shop datathe readable table of vz- keys and substitutions for own markup (HTML page; machine form is /docs/vz-keys.json)/docs/vz-keys
Машинные схемы
Token scopesevery scope a personal token can carry, sensitive ones marked — generated from the whitelist/docs/scopes.jsonWebhook events and deliveryevery webhook event with its sensitivity, plus attempts, backoff, timeout, signature and headers — generated from the code/docs/events.jsonWidgets JSON schema: kinds, props and wrapperJSON Schema of every block kind and the wrapper defaults, derived from the storefront code/docs/widgetsOwn markup keys (machine)vz- keys, page scope, isolation levels, recipes — machine form/docs/vz-keys.jsonPromotions: kinds, ladder, refusal codesrule kinds, classes, the ladder, refusal codes and rounding — generated from the engine constants/docs/promotions.jsonOpenAPI (full)every path, enriched with scopes and PAT access; feed it to a client generator/openapi.jsonOpenAPI (partner projection)the same schema without methods closed to personal tokens/partner/openapi.json
Для ИИ-агентов
llms.txt — reading order for agentswhat to read first and in which order; the shortest complete map of the surface/llms.txtSkills indexthe list of skills with descriptions — pick the one for the path your task takes/docs/skillsStart hereEntry point for building a Vizen shop through a personal API token — read the key passport, learn the map, and pick the right path BEFORE writing anything. Invoke first for any task touching /content-blocks, /html-documents, /design/bindings, categories or products. Question 0 — a finished site or export? — routes to a site folder or vizen-transfer, never to components; the rest to vizen-widgets, vizen-own-markup, vizen-chrome, vizen-catalog and vizen-troubleshoot./docs/skill/vizen-startTransfer a finished siteMove a FINISHED site or template — an HTML/CSS/JS folder, a static React/Vite export, a Figma/Webflow/Tilda export — into a Vizen shop through a personal token as it is: folder = level-3 widget in real page DOM, one command per folder, scripts and position:fixed work, no rebuild, no Shadow DOM. Layout folder, header/footer, pages, product/category templates, live-data re-binding, the check. A whole site kept separate, byte for byte, is a site folder instead (/docs/file-storage). Invoke when the task says transfer, migrate, "we already have a site", or hands you a folder, ZIP or repo./docs/skill/vizen-transferCatalogueRead and fill a Vizen catalogue through a token — products, categories, filters, images and the resizer, plus what a shop's data can silently fail to tell you. Use before building any page that shows real goods./docs/skill/vizen-catalogHeader, menu, footer, layoutsBuild a Vizen shop's header, menu and footer — configure the platform chrome widgets or replace them with your own markup, assemble a second chrome group, bind it to one section or to a LAYOUT (theme) without touching the rest of the shop, dress the system pages (cart, checkout, account), make a custom header stick, and replace the bundled product card./docs/skill/vizen-chromeYour own markupWrite your own HTML, CSS and JS into a Vizen shop — vz- keys and substitutions, isolation levels, what the block wrapper does to your layout, images through the resizer, live catalogue data in your own markup, modals and dropdowns, and the component with parameters when the same markup has to stand on many pages. Use when the task asks for a unique design rather than platform widgets./docs/skill/vizen-own-markupWhen the API said yes and the site says noDiagnose Vizen storefront problems where the API answered 200 but nothing changed on the site — silently ignored props, filters without the filter. prefix, clipped dropdowns, a header that will not stick, two product cards on one page. Also holds the acceptance checklist for any storefront change./docs/skill/vizen-troubleshootPlatform widgetsConfigure Vizen's built-in blocks — header, menu, footer, product listing, product card, covers, cards, slideshow — through their props, and know where their limits are. Use to configure built-in blocks through props; for authored markup and CSS integration, follow vizen-own-markup./docs/skill/vizen-widgets