Which version is for me? Two ways to read this guide. Step by step is for anyone — even if you've never opened a terminal; it walks you through it and includes a builder that writes the command for you. Quick reference (this page) is for developers who just want the parameters and the HTTP API.

Nasazení formuláře

Zprovozněte funkční kontaktní formulář na libovolném webu jediným příkazem. Brána (Gateway) se postará o ochranu proti spamu, ukládání dat i e-mailová upozornění — vy pouze popíšete, jak má formulář vypadat. Začínáte s terminálem? Vyzkoušejte průvodce krok za krokem s nástrojem pro sestavení formuláře, který příkaz připraví za vás.

How it works Authentication CLI HTTP API Put it on a page Form fields Onboarding recipe Two patterns What you get for free

Jak to funguje

Jedna brána (Gateway) obsluhuje všechny weby. Formulář je definice uložená v databázi — není to kód — takže jeho přidání nebo změna je jen zápis dat, který se projeví okamžitě, bez nového nasazení (redeploy).

Stránka odešle svá pole na https://forms.flowsmith.online/f/<site>/<form>. Brána (Gateway) data ověří, uloží odeslání a pošle e-mailové upozornění příjemci formuláře. Formulář definujete jednou; HTML kód pro vložení do stránky se vygeneruje automaticky.

Editing a definition doesn't rewrite a page. The definition (recipient, required fields, origins) controls the gateway and the generated snippet — it takes effect instantly. But a form already published on a page is plain HTML; changing the definition won't add or remove fields there. To change what a page shows, copy the updated snippet and paste it back onto that page.

Autentizace

Správa formulářů probíhá pomocí servisního tokenu (service token), který se odesílá v hlavičce (header):

Authorization: Bearer <FORMS_ADMIN_TOKEN>

The token is a secret. It is issued to you privately by Flowsmith and lets the holder create and change forms. Keep it out of source control, client-side code and screenshots. It only grants form management — it cannot read submitted data (that stays behind the password-protected admin). If a token leaks, tell us and we'll rotate it.

CLI — `onboard-form.mjs`

Skript obaluje API, takže nemusíte pracovat přímo s čistým HTTP. Vyžaduje Node 18+ a repozitář, ve kterém je dodávaný. Ještě nemáte Node? Podívejte se na Přípravu počítače. (Nemáte žádné nástroje? Průvodce krok za krokem udělá totéž jedním řádkem curl — bez instalace.)

Čte dvě proměnné prostředí:

Proměnná	Povinná	Význam
`FORMS_ADMIN_TOKEN`	povinné	Váš servisní token.
`FORMS_BASE`	volitelné	Základní URL brány (Gateway base URL). Výchozí hodnota je `https://forms.flowsmith.online`.

Příkazy

Příkaz	Co dělá
`list`	Vypíše všechny definice formulářů.
`get <site> <form>`	Zobrazí jednu definici.
`put <site> <form> [flags]`	Vytvoří nebo aktualizuje formulář (idempotentní operace).
`snippet <site> <form>`	Vypíše HTML připravené ke vložení do stránky.
`delete <site> <form> [--hard]`	Deaktivuje formulář (přidáním `--hard` jej odstraníte úplně).

Volby (flags) pro `put`

Volba	Povinný	Význam
`--recipient <email>`	povinné	Kam se posílají upozornění. Musí jít o ověřený cíl v našem e-mailovém směrování.
`--origins <a,b>`	volitelné	Čárkou oddělený seznam webů, které smějí odesílat data (apex doména + www). CORS allowlist.
`--require <a,b,c>`	volitelné	Čárkou oddělené názvy povinných polí (např. `name,email,message`).
`--subject "…"`	volitelné	Předmět e-mailového upozornění.
`--label "…"`	volitelné	Srozumitelný název zobrazovaný v administraci.
`--sender "Name <from@…>"`	volitelné	Přepsání odesílatele (From override). Výchozí je odesílatel brány (Gateway sender).
`--no-turnstile`	volitelné	Vypne kontrolu přes Turnstile (pouze pro integrační testování).

Příklad — zprovoznění celého webu jedním řádkem

FORMS_ADMIN_TOKEN=… node scripts/onboard-form.mjs put madhouse contact \
  --recipient [email protected] \
  --origins https://madhouse.vip,https://www.madhouse.vip \
  --require name,email,message

Potom získejte HTML pro vložení do stránky:

FORMS_ADMIN_TOKEN=… node scripts/onboard-form.mjs snippet madhouse contact

HTTP API

Pokud ho chcete volat přímo (nebo z AI agenta), endpointy pod /admin/api/forms odpovídají CLI. Všechny vyžadují hlavičku Authorization: Bearer.

Metoda	Cesta	Účel
GET	`/admin/api/forms`	Vypsat všechny definice
GET	`/admin/api/forms/{site}/{form}`	Jedna definice
PUT	`/admin/api/forms/{site}/{form}`	Vytvořit nebo aktualizovat (idempotentně)
DELETE	`/admin/api/forms/{site}/{form}`	Deaktivace (`?hard=1` pro odstranění)
GET	`/admin/api/forms/{site}/{form}/snippet`	HTML připravené ke vložení

site a form jsou slugy (slugs): malá písmena, číslice a pomlčky.

Tělo PUT požadavku

{
  "recipient": "[email protected]",
  "origins": ["https://madhouse.vip", "https://www.madhouse.vip"],
  "subject": "New MADHOUSE enquiry",
  "label": "MADHOUSE — Contact",
  "require_turnstile": true,
  "active": true,
  "schema": { "fields": [
    { "name": "name",    "required": true },
    { "name": "email",   "required": true },
    { "name": "message", "required": true }
  ] }
}

Odpověď: { "ok": true, "created": true|false, "site": "…", "form": "…" }

Vložení na stránku — dva způsoby

Dynamické vložení (dynamic embed, automaticky se aktualizuje)

Vložíte zástupný prvek (placeholder) a jeden skript. Pole se načítají živě z Flowsmithu a vykreslí se pomocí vlastních stylů vaší stránky (výstupem jsou obyčejná vstupní pole). Když pole upravíte v administraci nebo přes API, každá stránka s tímto vložením (embed) se aktualizuje sama — není potřeba nic znovu vkládat.

<div data-kh-embed="madhouse/contact"></div>
<script src="https://forms.flowsmith.online/assets/js/kh-forms-embed.js" defer></script>

Vyžaduje JavaScript. Na pozadí čte veřejnou, necitlivou definici na GET /f/<site>/<form>/def (pole, Turnstile sitekey, endpoint — nikdy příjemce).

Automaticky vícejazyčné. Vložení (embed) se vykreslí v jazyce stránky — přečte si <html lang> stránky (lze přepsat pomocí data-kh-lang="de", záloha je jazyk prohlížeče návštěvníka a potom angličtina). Popisky, tlačítko, stavové zprávy i lokálně věrohodné ukázkové placeholdery (přirozeně působící jméno, telefon, firma) se vrátí přeložené. U jazyků jako arabština a hebrejština se formulář přepne zprava doleva. Rozpoznává se zhruba 100 ISO kódů jazyků; jazyky, které ještě nejsou přeložené, se korektně zobrazí anglicky, dokud se jejich texty nedoplní. Na vícejazyčném webu se formulář jednoduše přepíná spolu se stránkou.

Statický snippet (pevný)

Vygenerované HTML (z CLI příkazu snippet nebo z tlačítka Snippet v administraci). Funguje bez JavaScriptu; pole jsou pevně daná v okamžiku vložení — pokud je chcete změnit, vložíte nový snippet.

Which to use? Dynamic embed for central control and auto-updates across many pages; static snippet when you need a no-JS fallback or full control of the markup.

Pole formuláře

Každé pole, které formulář odešle, se uloží a zobrazí v administraci. Některé názvy mají speciální význam:

Pole	Význam
`email`	Ověřuje se jako e-mail; použije se jako `Reply-To`, takže můžete odpovědět přímo ze své schránky.
`message`	Ve vygenerovaném snippetu se vykreslí jako víceřádkové pole (textarea).
`company_website`	Honeypot — ponechte ho v markup kódu, skrytý a vždy prázdný. Boti ho vyplní; skuteční uživatelé ne.
`_redirect`	Volitelné skryté pole; u odeslání bez JavaScriptu (no-JS) sem brána (Gateway) po úspěchu přesměruje.

Povinná pole označte buď pomocí --require (CLI), nebo v těle schema. Povinná pole se vynucují v prohlížeči i na serveru.

Postup zprovoznění

Definujte formulář — put <site> <form> --recipient … --origins …. Je aktivní okamžitě.
Získejte markup — snippet <site> <form>. Dva script tagy vložte jednou na stránku a samotný formulář tam, kde se má zobrazit.
Povolené zdroje (allowed origins) — hodnoty nastavené v --origins tvoří CORS allowlist; zahrňte apex doménu i www.
Hostname pro Turnstile — přidejte hostname webu do Turnstile widgetu kh-forms (aktuálně jednorázový ruční krok v Cloudflare).

Dva běžné scénáře

Jeden formulář, více stránek

Definujte formulář jednou a stejný snippet vložte na tolik stránek, kolik potřebujete — domovská stránka, stránka O nás, patička. Všechny odesílají data na stejné /f/<site>/<form>, končí v jedné schránce a v administraci se seskupí dohromady. Jen uveďte v origins všechny hostname, na kterých tyto stránky běží (apex + www a případné subdomény).

Jiný formulář pro jednu sekci

Když některá sekce potřebuje vlastní strukturu — například academy s jinými poli nebo jiným příjemcem — definujte pod stejným webem druhý formulář s vlastním slugem:

node scripts/onboard-form.mjs put photorobot academy \
  --recipient [email protected] \
  --origins https://photorobot.com,https://academy.photorobot.com \
  --require name,email,course,message

Jeden web může mít libovolný počet formulářů; každý má vlastní pole, příjemce a snippet. Pokud sekce běží na jiné subdoméně, přidejte ji do origins.

Co získáte bez další práce

Každý formulář na bráně (Gateway) je chráněný stejným způsobem, aniž byste museli cokoliv nastavovat:

Cloudflare Turnstile — neviditelná kontrola botů při každém odeslání.
Honeypot — skryté pole, které tiše zahodí odeslání od botů.
Rate limiting — omezení podle IP adresy napříč všemi formuláři, aby se otupil nápor.
Origin allowlist — odesílat smějí jen uvedené weby.
Validace povinných polí — vynucuje se v prohlížeči a znovu na serveru.
Uložení + e-mail — každé odeslání skončí v databázi i jako e-mail; stav doručení se zaznamená.

Submitted data is private. It's visible only in the password-protected admin (sign-in by one-time code to an authorised email) — the management token used for this guide cannot read it.