REST API: přihlášení a základní volání

REST API umožňuje externí aplikaci zakládat případy, pracovat s úkoly a proměnnými, nahrávat dokumenty a číst data TAS. Tato kapitola popisuje, jak se k API připojit, jak fungují seznamy a filtry a jak vypadají chybové odpovědi. Je určená integrátorům a administrátorům, kteří integraci připravují. Adresy a parametry odpovídají verzi TAS 5.19.12.

Žádný společný prefix
API nemá společnou předponu jako /api nebo /rest. Cesty v této kapitole (např. /tasks) se připojují přímo za adresu vaší instalace TAS, například https://vase-tas.cz/tasks.

Ověření

TAS přijímá tři druhy přihlašovacího tokenu, všechny ve stejné hlavičce:

Authorization: Bearer <token>
DruhOdkud token pocházíKdy ho použít
API tokenAdministrace › Přístup k API › API TokenyDlouhodobá integrace mezi servery bez OAuth.
OAuth přístupový tokenPOST /oauth/token (OAuth klient)Nové integrace, krátkodobé tokeny, aplikace, které potřebují souhlas uživatele.
Relace (cookie)Přihlášení v prohlížečiJen volání z vlastního webového rozhraní TAS, ne pro externí integrace.

Všechny tři druhy TAS rozpozná podle obsahu tokenu a chová se stejně – volání pracuje s právy uživatele, kterého token zastupuje (u API tokenu a důvěrného OAuth klienta je to přiřazený systémový uživatel, u OAuth klienta s souhlasem uživatele je to uživatel, který přístup schválil). Jak token nebo klienta získat a jak s ním pracovat podrobně popisuje článek API tokeny a OAuth klienti v praxi.

Název hlavičky je u instalace možné přejmenovat; výchozí a v naprosté většině instalací platný název je Authorization.

Stránkování, filtrování a řazení

Seznamové endpointy (například GET /tasks) přijímají tyto parametry v query stringu:

ParametrVýznam
limitPočet vrácených záznamů. Když ho vynecháte, platí výchozí limit instalace.
offsetKolik záznamů od začátku přeskočit.
orderSloupce pro řazení oddělené čárkou, např. order=createdAt,name. Lze použít i tečkovou notaci přes vazbu, např. order=owner.name.
sortSměr řazení pro každý sloupec z order, oddělený čárkou: asc nebo desc. Sloupec bez odpovídajícího směru se řadí vzestupně.
filterPodmínka pro filtrování, syntaxe níže.
total_countKdyž je true (výchozí), odpověď obsahuje celkový počet záznamů.
only_countKdyž je true, vrátí se jen { "items": [], "totalCount": N } bez dat.
columnsOmezí vrácené sloupce na vyjmenované.
distinctVrátí jen odlišné záznamy.
includeDeletedZahrne do výsledku i smazané záznamy.
nullsLastPrázdné hodnoty řadí až na konec (jen PostgreSQL).
disable_accentVypne porovnávání bez diakritiky při filtrování.

Syntaxe filtru

Podmínka má tvar pole<operátor>"hodnota", podmínky lze spojovat <and> / <or> a seskupovat do závorek:

OperátorVýznam
<eq>rovná se
<ne>nerovná se
<gt>větší než
<lt>menší než
<ge>větší nebo rovno
<le>menší nebo rovno
<like>obsahuje (LIKE), hodnota může obsahovat %
<nlike>neobsahuje
<in>je jedna z hodnot, oddělených čárkou
<nin>není žádná z hodnot
<isn>je prázdné (NULL)
<isnn>není prázdné
curl "https://vase-tas.cz/tasks?filter=(name<like>\"%Objednávka%\"<or>state<eq>\"Open\")<and>ownerId<eq>\"123\"&order=dueDate&sort=asc&limit=20" \
  -H "Authorization: Bearer <token>"
Pole v camelCase
Názvy polí ve filtru i v order/sort jsou vlastnosti entity v camelCase (např. dueDate), ne názvy databázových sloupců. Velká písmena a podtržítka TAS sice převede automaticky, ale camelCase je bezpečná volba napříč verzemi.

Formát chyby

Neúspěšné volání vrací chybový kód (400, 401, 403, 404, 409, 500 …) a tělo:

{
  "error": {
    "createdAt": "2026-10-31T08:15:00.000Z",
    "message": "Unauthorized.",
    "codeName": "UNAUTHORIZED",
    "error": "Unauthorized",
    "status": 401,
    "statusCode": 401,
    "chain": null,
    "meta": {}
  }
}

codeName je strojově čitelný kód chyby, message text pro zobrazení nebo log. U chyby ověření se v odpovědi navíc může objevit sessionExpired: true.

Nejpoužívanější endpointy

Založení případu z hlavičky

curl -X POST "https://vase-tas.cz/processes/activate/61" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"header_id": 2270}'

61 je ID šablony (tproc_id), header_id je ID konkrétní hlavičky, ze které se případ zakládá. Odpověď obsahuje ID založeného případu a první úkol, který na případu čeká:

{
  "result": true,
  "IPROC_ID": 27500,
  "NEXT_ITASK_ID": 420999,
  "NEXT_ITASK_NAME": "Vyplnění objednávky",
  "taskQueue": [{ "ITASK_ID": 420999, "ITASK_NAME": "Vyplnění objednávky", "IPROC_ID": 27500 }]
}

Které hlavičky smí přihlášený uživatel (respektive uživatel API tokenu) použít, zjistíte přes GET /template-processes/to-start.

Seznam úkolů

curl "https://vase-tas.cz/tasks?filter=itaskStateId<eq>\"1\"&limit=50" \
  -H "Authorization: Bearer <token>"

Vrací úkoly, které smí vidět uživatel zastupovaný tokenem, se stránkováním a filtrem popsaným výše. Jeden konkrétní úkol přečtete přes GET /tasks/:id.

Splnění úkolu

curl -X POST "https://vase-tas.cz/tasks/finish/420999" \
  -H "Authorization: Bearer <token>"

Úkol musí být rozpracovaný uživatelem/tokenem, který volání provádí, jinak TAS odpoví chybou nedostatečných práv. Odpověď obsahuje informaci o dalším úkolu, na který se případ posunul.

Čtení a zápis proměnných úkolu

curl "https://vase-tas.cz/tasks/420999/variables" \
  -H "Authorization: Bearer <token>"
curl -X POST "https://vase-tas.cz/tasks/420999/variables" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '[{"id": 15321, "value": "IKEA"}]'

id je ID proměnné na úkolu (ivar_id), ne ID proměnné šablony. Zápis vyžaduje, aby úkol řešil uživatel/token, který volání provádí.

Proměnné případu jen pro administrátora
Obdobné endpointy GET a POST /processes/:iprocId/variables čtou a zapisují proměnné na úrovni celého případu. Zápis (POST) smí jen administrátor – u běžného uživatelského API tokenu skončí chybou nedostatečných práv. Pro zápis z běžné integrace použijte proměnné úkolu.

Nahrání dokumentu k případu

curl -X POST "https://vase-tas.cz/dms/upload" \
  -H "Authorization: Bearer <token>" \
  -F "iprocId=27500" \
  -F "filename=Objednavka.pdf" \
  -F "file=@./Objednavka.pdf"

Soubor se nahrává jako multipart/form-data. Místo iprocId lze zadat itaskId, pokud chcete dokument připojit ke konkrétnímu úkolu. Volající musí mít k případu právo zápisu dokumentů.

Související: API tokeny a OAuth klienti v praxi, MCP server, Přístup k API.

API tokeny a OAuth klienti v praxi
Team assistant (opens in a new tab)

Powered by HelpDocs (opens in a new tab)