Publishing the FAQ
The shop operator writes and reviews the FAQ in the shop admin (Entwickler → FAQ): proposals are generated from the shop's settings, help texts and website, then confirmed, edited or dismissed one by one. Only confirmed questions ever leave the admin. Your part as the website's developer is to get the confirmed FAQ onto the website and to keep it current. The shop server renders it for you in three forms, all under one public URL, no login or API key required:
https://<shop host>/v3/faqdownload/<shop>
<shop> is the shop's system name, the same token used in its shop URLs. The admin's "Vorschau
und Download" section shows the ready-made addresses for the shop at hand.
| Parameter | Values | Meaning |
|---|---|---|
format |
page (default), fragment, jsonld |
which form, see below |
lang |
one of the shop's configured language codes, e.g. de, en |
content language (fragment, JSON-LD) or the language shown first (page). Default: the shop's base language. An unknown code answers 400 with the configured codes in the message |
download |
1 |
adds a Content-Disposition: attachment header; leave it out when fetching by script |
The three forms
format=page — the complete page
A self-contained HTML document: inline CSS, inline script, no external references. It holds every
configured language at once; a small flag switcher toggles which one is visible, and ?lang=
decides which one is shown first. Topics are collapsed <details> blocks with an <h2> in the
<summary>, every question has an id derived from its slug, so #faq-<slug> deep links work.
An HTML comment plus a <script type="application/ld+json"> block with the schema.org FAQPage
sits at the top of the body. Use this form when the FAQ gets its own page, e.g. faq.html on a
static site, or in an iframe.
format=fragment&lang=<code> — one language, no shell
Only the FAQ content: one <div class="faq-page" lang="<code>"> with a scoped <style> block
(rules on .faq-* classes only, nothing that restyles the host page), the same <details>
structure, no script. Use this form to paste the FAQ into an existing page of a CMS, where it
inherits menu and design. Instead of JSON-LD it carries schema.org microdata on the visible
elements (itemscope/itemprop for FAQPage, Question, Answer), because the usual editors
strip <script> blocks and HTML comments on save, see below. One fragment per language, so a
bilingual site fetches it twice and places each copy on its language's page.
format=jsonld&lang=<code> — the structured data alone
The FAQPage JSON-LD as application/ld+json, for a CMS that offers a dedicated field for
head-injected structured data (many SEO plugins do). Combine it with the fragment when you want
JSON-LD rather than microdata, or when your editor leaves no visible markup untouched. Do not
emit both microdata and JSON-LD for the same questions on one page; pick one.
Languages and missing translations
The shop has a base language and up to two alternative languages. Translations of question, answer and topic exist per language only where the operator (or the shop's automatic translation) filled them in. The output never shows an empty or duplicated translation:
- The page emits an alternative-language span only where a translation exists. Where none
does, the base-language span stays visible in that language too (it lists those languages in
data-fallback-for). Every text span carries its reallangattribute. - The fragment and the JSON-LD fall back to the base-language text; in the fragment that
element then carries the base
lang, e.g.<h3 lang="de">inside an English fragment. So an English fragment is always complete, but may contain German where nothing was translated. - A language is offered on the page's switcher only when at least one text is translated into it.
What editors break
- TinyMCE/CKEditor-style WYSIWYG editors (WordPress classic editor, many "rich text" fields)
remove
<script>blocks and HTML comments on save, and some do not know<details>and unwrap it. Paste the fragment into a raw HTML block (WordPress: "Custom HTML" / Gutenberg has a native Details block as well), not into the visual editor. - Inline styles get stripped by some editors. The fragment relies on none; its only styling is
the scoped
<style>block, which you may delete and replace with your own rules on the.faq-*classes. - Answers are real markup (
<p>,<br>), not text relying onwhite-space: pre-wrap, so line breaks survive a stripped stylesheet.
Keeping the published copy current
The FAQ changes whenever the operator confirms, edits or deletes a question. There is no push. The footer of page and fragment, and the opening comment of the fragment, carry the date of the last change ("Stand"), the same date the admin shows, so an outdated copy is recognisable.
- Manual publishing: the operator downloads again after every change and replaces the file or the pasted block. Tell them which form you built on, so they fetch the right one.
- Automatic publishing: fetch the fragment (or the page) by GET from your CMS, build or cron
job and replace the stored copy. Every response carries an
ETagand aLast-Modifiedheader; send the ETag back asIf-None-Matchand you get a304 Not Modifiedwith no body while nothing changed, so even hourly polling costs next to nothing. Views also carryCache-Control: public, max-age=300, so a page that fetches the fragment live may be served from a cache for up to five minutes after a change. - No FAQ yet: a shop without confirmed questions returns a page or fragment with no topics and
an empty footer date. Check for at least one
.faq-itembefore publishing automatically.
Related
- Using the API for the general conventions of the shop API; the FAQ endpoint is a
plain servlet outside the versioned
/api/namespace and needs no session. - Built-in chat: the chat reads the same shop settings and help texts the FAQ generator does, so a well-filled FAQ and a good chat go together.
- The admin's FAQ tab documents the generation side (sources, topics, review) for the shop operator.