Šablony sběrů podkladů

Přehled

Šablony umožňují uložit si sadu položek a znovu ji použít na dalších projektech. Místo abyste položky pokaždé definovali od nuly, odkážete define_intake na šablonu a položky se doplní samy. Pro konkrétní projekt je pak můžete přebít nebo rozšířit.

Šablony se hodí hlavně v agenturách, kde opakovaně děláte stejný typ projektu — weby restaurací, stránky poradců, e-shopy — a chcete konzistentní, prověřenou sadu položek.

Vestavěné šablony

Tři veřejné šablony jsou k dispozici ve všech tarifech včetně Free. Jsou vždy přítomné a nelze je smazat. Všechny tři jsou české šablony (language: "cs") — popisky a nápovědy položek jsou v češtině, protože vznikly pro Radimovu vlastní agenturní praxi.

restaurant-web-cs

Pro weby restaurací a kaváren.

advisor-web-cs

Pro finanční poradce, kouče, konzultanty a podobné profesní profily.

club-web-cs

Pro sportovní kluby a jiné spolky — nejde o e-shopovou šablonu; žádná vestavěná e-shopová šablona v současnosti neexistuje.

Použití šablony v define_intake

Slug šablony předejte v poli template:

{
  "project_name": "Bella Cucina Restaurant Website",
  "client": {
    "email": "owner@bellacucina.cz",
    "name": "Marco"
  },
  "template": "restaurant-web-cs",
  "branding": {
    "sender_name": "Radim"
  }
}

Vznikne sběr podkladů se všemi položkami šablony restaurant-web-cs. Pole items je tady nepovinné — s vyplněným template ho POST /v1/intakes už nevyžaduje; když ho vynecháte (nebo pošlete "items": []), znamená to „všechny položky přijdou ze šablony". Bez template je items pořád povinné a nesmí být prázdné, se stejnou chybou 422 jako dřív.

Přebití a rozšíření

Když vedle template pošlete i pole items, můžete konkrétní položky přebít nebo přidat nové. Vaše položky se se šablonou slučují:

• Když se key shoduje s položkou ze šablony, vaše definice ji přebije
• Když je key nový, položka se připojí za položky ze šablony

Každá položka v poli items — i ta, kterou chcete jen upravit — musí být pořád úplná definice položky (key, type i label API vyžaduje vždy; žádná zkratka pro poslání jen toho jednoho pole, které měníte, neexistuje):

{
  "template": "restaurant-web-cs",
  "items": [
    {
      "key": "menu_pdf",
      "type": "file",
      "label": "Jídelní lístek (PDF)",
      "required": false,
      "help": "Potřeba jen tehdy, když chcete jídelní lístek ke stažení. Když ho spravujete online, přeskočte."
    },
    {
      "key": "allergen_info",
      "type": "file",
      "label": "Dokument s informacemi o alergenech",
      "required": false
    }
  ]
}

Vlastní šablony

Vlastní šablony vyžadují tarif Solo nebo vyšší (29 $/měs) — na Free skončí POST /v1/templates chybou plan_required a účty na Free mají k dispozici jen tři výše uvedené vestavěné veřejné šablony. POST /v1/templates navíc vyžaduje přihlášenou session z dashboardu — agent přihlášený jen API klíčem přes tento endpoint vlastní šablonu vytvořit nemůže; vytvořte ji z dashboardu (nebo o to požádejte kolegu, který do dashboardu přístup má).

V dashboardu je nejrychlejší cesta tlačítko Uložit jako šablonu vedle tlačítka Odeslat ve chvíli, kdy máte sběr podkladů sestavený. Uloží jen definice položek a jazyk — nikdy jméno klienta, jeho e-mail ani název projektu — takže stejnou šablonu můžete bez obav použít u dalšího klienta. Přes API existující sběr zkopírovat nejde: POST /v1/templates přijímá jen šablonu sestavenou od nuly, popsanou níže.

POST /v1/templates

{
  "name": "SaaS Landing Page",
  "description": "Standardní sběr podkladů pro landing page SaaS produktu",
  "language": "cs",
  "items": [
    {"key": "logo", "type": "image", "label": "Logo produktu"},
    {"key": "hero_headline", "type": "text", "label": "Hlavní nadpis", "constraints": {"max_chars": 80}},
    {"key": "hero_subline", "type": "text", "label": "Podnadpis", "constraints": {"max_chars": 160}},
    {"key": "stripe_keys", "type": "secret", "label": "API klíče ke Stripu"}
  ]
}

Pole slug se nezadává — slug se odvodí automaticky z name (malá písmena, nealfanumerické znaky nahrazené pomlčkou). language přijímá cs, en nebo de — ne celý šestijazyčný seznam portálu. Omezení jako max_chars musí být vnořené pod constraints, stejně jako v poli items u define_intake — max_chars přímo na položce API odmítne.

Nastavení šablony

Šablona může vedle položek uložit i všechna ostatní nastavení pro založení sběru — cyklus upomínek, retenci, branding a do jaké složky nové sběry padají. POST /v1/templates přijímá volitelný objekt settings s těmito poli, všechna nepovinná:

{
  "name": "SaaS Landing Page",
  "language": "cs",
  "items": [
    {"key": "logo", "type": "image", "label": "Logo produktu"}
  ],
  "settings": {
    "due_in_days": 14,
    "chase_schedule": "custom",
    "chase_interval": 5,
    "chase_interval_unit": "days",
    "retention": {"mode": "on_delivery", "anonymize": false}
  }
}

Nastavení jsou výchozí hodnoty, ne přebití. Když se sběr zakládá s vyplněným template, každé pole nastavení se použije, jen když ho požadavek na založení sběru sám nevyplní. Cokoli požadavek nastaví explicitně — i hodnota, která náhodou odpovídá tomu, co nastavuje i šablona — vždy vyhraje, pole po poli; uvnitř jednoho pole se nic neslučuje (email_copy poslané v požadavku nahradí objekt email_copy ze šablony celý, ne řádek po řádku). due_in_days se v okamžiku založení sběru přepočítá na skutečné due_date (den založení + N), pokud požadavek už sám nenese vlastní due_date.

Šablona bez settings — včetně tří vestavěných veřejných šablon — nemění nic kromě položek; GET/POST /v1/templates pak u settings vrací null.

settings je zatím jen přes API: tlačítko Uložit jako šablonu v dashboardu (výše) stále ukládá jen definice položek a jazyk.

Výpis šablon

GET /v1/templates

Vrátí veřejné šablony i vaše vlastní dohromady, jako { "templates": [...] }. Tento endpoint momentálně nemá žádný filtr přes ?public=true (ani jiný) — parametr v URL se ignoruje; chcete-li jen veřejné, filtrujte si výsledek sami (u nich je accountId null).

Odpověď je uložený řádek šablony tak, jak je, ne zjednodušený výpis — pole items je konkrétně celé pole definic položek (ne počet), settings je buď celý objekt nastavení popsaný výše, nebo null, a žádné pole nesleduje, který uživatel šablonu vytvořil, jen který účet ji vlastní. Pole v odpovědi jsou navíc syrové camelCase názvy sloupců z databáze (accountId, isPublic, createdAt, …), na rozdíl od zbytku API, které vrací snake_case.

Agency: šablony sdílené v týmu

V tarifu Agency vidí šablonu vytvořenou kterýmkoli uživatelem všichni uživatelé účtu. Žádné zvláštní sdílení není potřeba — šablony jsou týmové ve výchozím stavu.

Můžete si tak jednou postavit knihovnu standardních checklistů a používat ji na všech projektech bez ohledu na to, kdo z týmu sběry podkladů zakládá.

Ať se v šablonách vyznáte, držte se konzistentního pojmenování slugů:

restaurant-web-v2
advisor-web-minimal
webapp-onboarding

Vlastní šablony vyžadují Solo, Studio nebo Agency (Free žádné vytvořit nemůže). V tarifech Solo a Studio patří vlastní šablony jedinému uživateli daného účtu; v tarifu Agency jsou sdílené napříč všemi uživateli, jak popisuje sekce výše.