Typy položek

Položky v BriefGate mají typ. Agent řekne, co potřebuje; klientský portál vstup kontroluje v reálném čase; get_intake_results vrátí data, která agent rovnou použije, bez dalšího parsování a převodů typů.

Každá definice položky potřebuje minimálně key (jedinečný v rámci sběru podkladů), label (vidí ho klient) a type. Většina typů přijímá nepovinná constraints, která portál vynutí ještě před odesláním.

Komu položka patří: `assignee`

Každá položka má i assignee, ve výchozím stavu "client" — tedy to, kvůli čemu sběr podkladů vznikl.

Nastavením "assignee": "owner" ve sběru podkladů přidáte svůj vlastní úkol: „zavolat klientovi", „zaregistrovat doménu", „objednat fotografa". Vlastní úkol

se nikdy neobjeví v klientském portálu,
nikdy se nepřipomíná v urgenci,
nepočítá se do postupu, který klient vidí,
a nikdy nedrží sběr podkladů otevřený — ten je hotový, když je hotový klient.

Odklikáváte ho v dashboardu, nebo přes POST /v1/intakes/:id/items/:key/done. Na prosté odškrtnutí použijte type: "boolean".

Protože se vlastní úkol nikdy nedostane do portálu, nemůže použít typy, které se odesílají právě tam: file, file_list, image a secret jsou s assignee: "owner" odmítnuty.

json

{
  "key": "call_client",
  "label": "Zavolat klientovi kvůli termínu spuštění",
  "type": "boolean",
  "assignee": "owner"
}

text

Jednořádkové textové pole. Hodí se na krátké strukturované řetězce, jako jsou měřicí ID, názvy účtů nebo kódy.

Omezení (uvnitř objektu constraints)

Pole	Typ	Popis
`min_chars`	integer	Nejmenší počet znaků.
`max_chars`	integer	Největší počet znaků. Když se nenastaví, výchozí je 2000.

Pole přímo na položce

Pole	Typ	Popis
`pattern`	string	Regulární výraz ECMAScript, kterému hodnota musí odpovídat. Patří přímo do definice položky, ne do `constraints`.

Příklad — měřicí ID Google Analytics

json

{
  "key": "ga4_id",
  "label": "Google Analytics 4 Measurement ID",
  "help": "Found in GA4 > Admin > Data Streams. Format: G-XXXXXXXXXX",
  "type": "text",
  "required": true,
  "pattern": "^G-[A-Z0-9]+"
}

Co vrátí get_intake_results

json

"ga4_id": "G-K4M9X3R2B1"

longtext

Víceřádkové pole na několik odstavců. Hodí se na delší texty, medailonky, poslání firmy a všude, kde klient potřebuje prostor.

Omezení

Pole	Typ	Popis
`min_chars`	integer	Nejmenší počet znaků.
`max_chars`	integer	Největší počet znaků. Když se nenastaví, výchozí je 20000.

Příklad — text do hlavičky

json

{
  "key": "hero_copy",
  "label": "Homepage hero text",
  "help": "A short paragraph (up to 400 characters) that captures the spirit of the restaurant. Appears above the fold.",
  "type": "longtext",
  "required": true,
  "constraints": {
    "max_chars": 400
  }
}

Co vrátí get_intake_results

json

"hero_copy": "Since 1987, handcrafted Neapolitan pizza in the heart of the city. Come hungry, leave happy."

file

Nahrání jednoho souboru. Hodí se na dokumenty, PDF, tabulky, fonty a další binární soubory, které nejsou obrázky.

Omezení

Pole	Typ	Popis
`formats`	string[]	Povolené přípony bez tečky, například `["pdf","docx"]`. Nerozlišuje velikost písmen.
`max_bytes`	integer	Největší velikost souboru v bajtech. Výchozí je 52 428 800 (50 MB).

Příklad — podepsaná smlouva

json

{
  "key": "signed_contract",
  "label": "Signed project contract",
  "help": "Upload the signed PDF you received by email.",
  "type": "file",
  "required": true,
  "constraints": {
    "formats": ["pdf"],
    "max_bytes": 10485760
  }
}

Co vrátí get_intake_results

json

"signed_contract": {
  "filename": "bella-napoli-contract-signed.pdf",
  "url": "https://files.briefgate.dev/in_8f3kQmR2/signed_contract.pdf?token=sig_abc&expires=1710615600",
  "mime": "application/pdf",
  "size": 283492,
  "checksum_sha256": "a3f2e1..."
}

url je podepsaná adresa s platností 24 hodin. Stáhněte soubor včas, nebo si zavolejte get_intake_results znovu a dostanete čerstvou adresu.

file_list

Skupina více nahraných souborů. Hodí se na fotogalerie, balíčky podkladů a všude, kde potřebujete několik souborů stejné kategorie.

Omezení

Pole	Typ	Popis
`formats`	string[]	Povolené přípony souborů.
`max_bytes`	integer	Největší velikost jednoho souboru.
`min_count`	integer	Nejmenší požadovaný počet souborů.
`max_count`	integer	Největší přijímaný počet souborů.

Příklad — fotky restaurace

json

{
  "key": "photos",
  "label": "Food and interior photos",
  "help": "Upload between 5 and 15 photos of your food, interior, and ambience.",
  "type": "file_list",
  "required": true,
  "constraints": {
    "formats": ["jpg", "png", "heic"],
    "min_count": 5,
    "max_count": 15
  }
}

Co vrátí get_intake_results

json

"photos": [
  {
    "filename": "interior-01.jpg",
    "url": "https://files.briefgate.dev/in_8f3kQmR2/photos/interior-01.jpg?token=...",
    "mime": "image/jpeg",
    "size": 3204812,
    "checksum_sha256": "b4c1d2..."
  },
  {
    "filename": "pizza-margherita.jpg",
    "url": "https://files.briefgate.dev/in_8f3kQmR2/photos/pizza-margherita.jpg?token=...",
    "mime": "image/jpeg",
    "size": 2917034,
    "checksum_sha256": "f9e3a1..."
  }
]

image

Nahrání obrázku s volitelnými omezeními na rozměry a formát. Použijte místo file, když potřebujete vynutit rozlišení nebo průhlednost.

Omezení

Pole	Typ	Popis
`formats`	string[]	Povolené přípony souborů, například `["svg","png"]`. Bez výchozí hodnoty — když se vynechá, přijme se jakýkoli obrázek.
`min_width`	integer	Nejmenší šířka obrázku v pixelech. U nahrávek `svg` se ignoruje — vektor nemá pevný rozměr v pixelech.
`max_width`	integer	Největší šířka obrázku v pixelech. U `svg` se ignoruje.
`min_height`	integer	Nejmenší výška obrázku v pixelech. U `svg` se ignoruje.
`max_height`	integer	Největší výška obrázku v pixelech. U `svg` se ignoruje.
`max_bytes`	integer	Největší velikost souboru v bajtech. Nemůže přesáhnout limit velikosti nahrávky na účtu (výchozí 52 428 800 / 50 MB), i kdyby se nastavilo víc.
`transparent_background`	boolean	S `true` portál klienta upozorní, když obrázek nemá alfa kanál.

Příklad — logo

json

{
  "key": "logo",
  "label": "Company logo",
  "help": "SVG or PNG with a transparent background. Minimum 512px on the shortest side.",
  "type": "image",
  "required": true,
  "constraints": {
    "formats": ["svg", "png"],
    "min_width": 512,
    "transparent_background": true
  }
}

Co vrátí get_intake_results

json

"logo": {
  "filename": "logo-transparent.png",
  "url": "https://files.briefgate.dev/in_8f3kQmR2/logo-transparent.png?token=...",
  "mime": "image/png",
  "width": 1024,
  "height": 512,
  "size": 48210
}

color_list

Výběr jedné nebo více barev v hexadecimálním zápisu. Portál nabízí vizuální výběr barvy i zadání hexu. Portál vždy ověří, že jde o platný hex kód; všechna ostatní omezení jsou nepovinná.

Omezení (uvnitř objektu constraints)

Pole	Typ	Popis
`min_count`	integer	Nejmenší požadovaný počet barev.
`max_count`	integer	Největší přijímaný počet barev. Když se nenastaví, výchozí je 12.

Příklad — firemní paleta

json

{
  "key": "brand_colors",
  "label": "Brand colors",
  "help": "Select your primary and secondary brand colors. Add as many as you use.",
  "type": "color_list",
  "required": true
}

Co vrátí get_intake_results

json

"brand_colors": ["#1B2A4A", "#E8E2D9", "#C8382E"]

select

Rozbalovací seznam nebo přepínače, kde klient vybere právě jednu možnost ze seznamu, který zadáte. Hodí se, když potřebujete omezenou sadu hodnot.

Povinná pole

Pole	Typ	Popis
`options`	array	Pole objektů `{value, label}`. `value` se uloží, `label` vidí klient.

Příklad — platforma webu

json

{
  "key": "platform",
  "label": "Preferred website platform",
  "type": "select",
  "required": true,
  "options": [
    { "value": "wordpress", "label": "WordPress" },
    { "value": "webflow",   "label": "Webflow" },
    { "value": "shopify",   "label": "Shopify" },
    { "value": "custom",    "label": "Custom / I'm not sure" }
  ]
}

Co vrátí get_intake_results

json

"platform": "wordpress"

Výsledkem je vždy řetězec z value, nikdy label.

multiselect

Skupina zaškrtávacích políček, kde klient vybere libovolný počet možností ze seznamu, který zadáte — i žádnou. Hodí se, když klient může potřebovat vybrat víc než jednu možnost.

Povinná pole

Pole	Typ	Popis
`options`	array	Pole objektů `{value, label}`. `value` se uloží, `label` vidí klient.

Omezení (uvnitř objektu constraints)

Pole	Typ	Popis
`min_count`	integer	Minimální počet možností, které musí být vybrány.
`max_count`	integer	Maximální počet možností, které lze vybrat.

Příklad — požadované služby

json

{
  "key": "services_needed",
  "label": "Which services do you need?",
  "type": "multiselect",
  "required": true,
  "constraints": {
    "min_count": 1,
    "max_count": 3
  },
  "options": [
    { "value": "design",     "label": "Design" },
    { "value": "copywriting","label": "Copywriting" },
    { "value": "seo",        "label": "SEO" },
    { "value": "hosting",    "label": "Hosting" }
  ]
}

Co vrátí get_intake_results

json

"services_needed": ["design", "seo"]

Výsledkem je vždy pole řetězců z value, nikdy label, a to i když je vybraná jen jedna možnost.

boolean

Přepínač ano/ne. Portál ho podle motivu vykreslí jako dvojici jasně popsaných tlačítek nebo jako zaškrtávátko.

Příklad — dotaz na stávající web

json

{
  "key": "has_existing_site",
  "label": "Do you have an existing website?",
  "type": "boolean",
  "required": true
}

Co vrátí get_intake_results

json

"has_existing_site": true

url

Pole pro adresu s vestavěnou kontrolou http/https. Volitelně ho omezíte na konkrétní doménu nebo tvar cesty.

Pole přímo na položce

Pole	Typ	Popis
`pattern`	string	Regulární výraz ECMAScript, kterému adresa musí odpovídat. Patří přímo do definice položky, ne do `constraints`. Použijte pro omezení na konkrétní doménu.

Příklad — adresa stávajícího webu

json

{
  "key": "existing_site_url",
  "label": "Existing website address",
  "help": "The full URL including https://",
  "type": "url",
  "required": false
}

Co vrátí get_intake_results

json

"existing_site_url": "https://old.bellanapoli.com"

secret

Pole pro šifrovaný přístupový údaj. Portál zobrazí pole jako u hesla, s ikonou zámku a jasnou informací, že se hodnota ukládá bezpečně. Hodnota se přenese přes HTTPS a server ji před uložením zapečetí přes libsodium sealed box; nikdy se neloguje, neindexuje ani neposílá ve webhook payloadu.

Přístupy propadají po 30 dnech a odhalit je lze jen jednou — s krátkým ochranným oknem (níž) pro volajícího, kterému odpověď nikdy nedorazila.

Příklad — přihlášení do administrace CMS

json

{
  "key": "cms_credentials",
  "label": "WordPress admin credentials",
  "help": "Your current admin username and password. Stored encrypted and only accessible to your project team.",
  "type": "secret",
  "required": false
}

Co vrátí get_intake_results

Při prvním volání se dešifrovaný text vrátí přímo:

json

"cms_credentials": {
  "value": "username:password",
  "one_time": true,
  "first_reveal": true,
  "expires_at": "2024-04-15T10:22:00Z"
}

Volání ze stejného API klíče do 5 minut od prvního odhalení dostane tutéž hodnotu znovu (ochranné okno pro odpověď, která nikdy nedorazila). Po uplynutí okna, nebo z jiného klíče, je results.cms_credentials místo toho null a proč se dozvíte z doprovodného záznamu meta.cms_credentials:

json

"cms_credentials": null

json

"meta": {
  "cms_credentials": {
    "secret_unavailable": true,
    "reason": "Already revealed — secrets are one-time and cannot be shown again.",
    "revealed_at": "2024-04-15T09:10:00Z"
  }
}

Uložte si text dřív, než budete pokračovat — spoléhat na to, že ho dostanete podruhé, nejde.

Vyžaduje scope secrets:read nebo admin na API klíči.

structured

Hodnota v JSON odpovídající schématu JSON Schema, které zadáte. Portál ze schématu vygeneruje formulář (u jednoduchých plochých schémat) nebo nabídne editor JSON (u složitých a vnořených). Odeslaná hodnota se proti schématu ověří na serveru dřív, než se položka přijme.

Povinná pole

Pole	Typ	Popis
`schema`	object	Platný objekt JSON Schema, draft-07 (výchozí pro Ajv). Buď vynechte `"$schema"`, nebo nastavte meta-schéma draft-07 — schéma s `"$schema": ".../2020-12/schema"` se nezkompiluje.

Příklad — otevírací doba

json

{
  "key": "opening_hours",
  "label": "Opening hours",
  "help": "Your regular weekly schedule. Use a simple time range like '12:00-22:00' or the word 'Closed'.",
  "type": "structured",
  "required": true,
  "schema": {
    "type": "object",
    "required": ["mon_fri", "sat", "sun"],
    "properties": {
      "mon_fri": { "type": "string", "title": "Monday to Friday", "example": "12:00-22:00" },
      "sat":     { "type": "string", "title": "Saturday",          "example": "12:00-23:00" },
      "sun":     { "type": "string", "title": "Sunday",            "example": "Closed" }
    }
  }
}

Co vrátí get_intake_results

json

"opening_hours": {
  "mon_fri": "12:00-22:00",
  "sat": "12:00-23:00",
  "sun": "13:00-21:00"
}

Vrácený objekt zaručeně odpovídá zadanému schématu.

Typy dohromady: příklad webu restaurace

Následující pole items pokrývá hlavní typy položek na realistickém projektu:

json

[
  {
    "key": "logo",
    "label": "Restaurant logo",
    "type": "image",
    "required": true,
    "constraints": { "formats": ["svg","png"], "min_width": 512, "transparent_background": true }
  },
  {
    "key": "brand_colors",
    "label": "Brand colors",
    "type": "color_list",
    "required": true
  },
  {
    "key": "hero_copy",
    "label": "Hero section tagline",
    "type": "longtext",
    "required": true,
    "constraints": { "max_chars": 400 }
  },
  {
    "key": "ga4_id",
    "label": "Google Analytics 4 ID",
    "type": "text",
    "required": false,
    "pattern": "^G-[A-Z0-9]+"
  },
  {
    "key": "has_existing_site",
    "label": "Do you have an existing website?",
    "type": "boolean",
    "required": true
  },
  {
    "key": "existing_site_url",
    "label": "Existing website URL",
    "type": "url",
    "required": false
  },
  {
    "key": "platform",
    "label": "Preferred platform",
    "type": "select",
    "required": true,
    "options": [
      { "value": "wordpress", "label": "WordPress" },
      { "value": "webflow", "label": "Webflow" },
      { "value": "custom", "label": "Custom / I'm not sure" }
    ]
  },
  {
    "key": "cms_credentials",
    "label": "Existing CMS credentials",
    "type": "secret",
    "required": false
  },
  {
    "key": "menu_pdf",
    "label": "Menu (PDF)",
    "type": "file",
    "required": true,
    "constraints": { "formats": ["pdf"], "max_bytes": 10485760 }
  },
  {
    "key": "photos",
    "label": "Food and interior photos",
    "type": "file_list",
    "required": true,
    "constraints": { "formats": ["jpg","png","heic"], "min_count": 5, "max_count": 15 }
  },
  {
    "key": "opening_hours",
    "label": "Opening hours",
    "type": "structured",
    "required": true,
    "schema": {
      "type": "object",
      "required": ["mon_fri","sat","sun"],
      "properties": {
        "mon_fri": { "type": "string" },
        "sat":     { "type": "string" },
        "sun":     { "type": "string" }
      }
    }
  }
]

Kontrola vstupů

Kontrola běží na serveru a probíhá při nahrání, ještě než se položka označí jako submitted. Když soubor nesplní omezení (špatný formát, příliš malý, málo souborů, neodpovídá vzoru), klient dostane zpětnou vazbu přímo v portálu. Neplatnou položku odeslat nemůže.

Jediným zdrojem pravdy je definice položky od agenta — type, constraints a schema. BriefGate omezení nedovozuje z obsahu souboru ani jinou heuristikou. Když potřebujete omezení zpřísnit poté, co je sběr podkladů živý, přidejte přes add_items náhradní položku s novým key a přes request_revision klienta k novému poli nasměrujte.

Typy položek

Komu položka patří: assignee

text

longtext

file

file_list

image

color_list

select

multiselect

boolean

url

secret

structured

Typy dohromady: příklad webu restaurace

Kontrola vstupů

Komu položka patří: `assignee`