CRUD vzor#

Všechny zdroje sdílejí tutéž sadu akcí. Každé volání níže (adresy jsou zkrácené na cestu) nese hlavičku X-API-Key s klíčem aplikace; zápis a „moje“ data navíc Authorization: Bearer <token>.

🔴 Parametry se posílají v adrese#

Tělo požadavku se u CRUD akcí nečte vůbec

Ani formulářové, ani JSON. Všechno — včetně dat k uložení — jde do dotazu v adrese, v zápisu polí jazyka PHP: data[title]=…&data[category][id]=3.

Výjimky jsou přihlašovací endpointy, které naopak čtou formulářové tělo, a akce s hesly a klíči (update-password, reset-password, is-auth-valid), které je čtou jen z těla — formulářového i JSON.

Metoda HTTP nerozhoduje#

GET /api/…/delete?id=5 skutečně smaže

Akce se určuje z adresy, ne z metody. Nedávejte adresy API do předběžného načítání ani nikam, kde je projde robot.

Tvar parametrů se kontroluje#

Parametr ve špatném tvaru se nepřetypuje „nějak“ — požadavek skončí HTTP 400 s kódem 2 dřív, než se cokoli načte nebo zapíše. Text místo pole (filters=x), neznámý zápis logické hodnoty (computeTotalCount=ano) nebo seznam místo jednoho ID tedy nevrátí jiná data, ale chybu. Úplný přehled je v Chybových kódech.

Akce#

Akce	K čemu
`get`	jeden záznam podle `id`
`get-by`	jeden záznam podle filtru
`get-all`	výpis
`save`	vložení i úprava
`update-columns`	změna vybraných polí
`delete`	smazání
`delete-all`	smazání podle filtru

Parametry čtení#

Parametr	Význam
`id`	identifikátor
`filters`	filtry, viz níže
`orderBys`	řazení
`offset`, `limit`	stránkování; viz poznámka o limitu níže
`includes`	načtení vazeb
`computeTotalCount`	`1` spočítá celkový počet; jen `1`/`0`, `true`/`false`, `on`/`off`

columns zvenčí u výpisu nefunguje

Zúžení vrácených polí parametrem columns u get-all skončí HTTP 400. Odpověď nese všechna pole, která smíte číst.

Výpis bez limit vrací 50 záznamů, nejvýš 500

U get-all zvenčí vrátí chybějící, nečíselný nebo menší než 1 limit 50 záznamů. Větší hodnota se ořízne na 500 — není to chyba, odpověď prostě obsahuje nejvýš 500 záznamů. Další záznamy načtěte stránkováním: opakujte volání s rostoucím offset a zastavte se podle totalCount (pošlete computeTotalCount=1).

Řazení#

orderBys[created]=1     vzestupně
orderBys[created]=0     sestupně
orderBys[category.name]=1

Směr je pravdivostní hodnota, ne asc / desc

orderBys[name]=desc je neprázdný řetězec, tedy pravda — seřadí vzestupně. Používejte 1 a 0.

Vazby#

includes[]=translations&includes[]=user.roles
includes=translations

includes je jedna cesta, nebo seznam cest.

includes=* funguje jen u get

U detailu natáhne všechny vazby — snadná cesta k obrovské odpovědi. U get-all skončí HTTP 400. Vyjmenujte, co potřebujete.

Filtry#

Filtr je trojice [typ, pole, hodnota]:

?filters[0][0]=equal&filters[0][1]=activated&filters[0][2]=1
&filters[1][0]=like&filters[1][1]=title&filters[1][2]=notebook&filters[1][matchType]=both
&filters[2][0]=in&filters[2][1]=id&filters[2][2][]=1&filters[2][2][]=2

Filtry se skládají operací a zároveň.

Typ	Doplňkové klíče
`equal`, `notEqual`
`like`, `notLike`	`matchType`: `both`, `start`, `end`
`in`, `notIn`
`isNull`, `isNotNull`
`between`	`from`, `to`
`range`	`inclusive`
`greaterThan`, `greaterOrEqual`	zkratky `gt`, `gte`
`lessThan`, `lessOrEqual`	zkratky `lt`, `lte`
`comparison`	`operator`
`date`, `dateBetween`, `dateAfter`, `dateBefore`	`operator`, `format`
`group`, `or`, `and`	`filters`, `logic`
`fulltext`	`mode`, `minScore`

Neznámý nebo špatně sestavený filtr vrátí 400

Překlep v názvu typu, filtr bez pole nebo vnořená skupina ve špatném tvaru skončí HTTP 400 s kódem 2. Doplňkové klíče inclusive a isNull čekají pravdivostní hodnotu, kterou adresa nepřenese — v dotazu je nepoužívejte.

Filtrovat a řadit smíte jen podle polí, která smíte číst

Filtr nebo řazení nad heslem, IP adresou, e-mailem cizího uživatele nebo nad neexistujícím polem vrátí HTTP 400 se zprávou Field path "…" is not allowed. Podrobně v Oprávněních.

Uložení#

Jeden endpoint pro vložení i úpravu. Rozlišuje se přítomností data[id].

/api/blog/article/save?data[title]=Novinka&data[category][id]=3

data, meta i skipFields musí být pole; text místo nich vrátí HTTP 400. Prázdná data vrátí kód 602.

Hodnoty se převádějí podle typu pole#

Z adresy přijde každá hodnota jako text. Server ji převede podle typu pole, do kterého patří:

Typ pole	Přijme	Nepřijme
celé číslo	`12`, `-3`, `0`	`1.9`, `1e2`, `+1`, `01`, mezery
desetinné číslo	`1.5`, `-0.25`, `.5`, `2e3`	čárku, mezery
logická hodnota	`1`, `0`, `true`, `false`, `on`, `off` (malými písmeny)	`ano`, `yes`, `TRUE`
datum a čas	to, co přečte PHP `new DateTime()`, např. `2026-10-03 14:30`	neexistující datum (`2026-02-31`), mezery okolo
text	cokoli	—

Prázdný řetězec znamená u pole, které smí být prázdné, null; u povinného je to chyba. Hodnota, která se převést nedá, vrátí kód 604 se jménem pole a nic se neuloží:

{"success":false,"code":604,"message":"Invalid value for field \"currencyId\": expected int, got \"1.9\"."}

Část dat se tiše zahodí#

Odpověď hlásí úspěch, ale hodnota se neuloží

Zahazuje se:

meta — u většiny zdrojů celé,
pole označená jako jen pro čtení zvenčí (hodnotu určuje server),
pole, která váš účet nesmí zapsat — vlastník nezmění třeba kredity, slevu nebo e-mail svého účtu (viz Úprava vlastního účtu),
vnořené kolekce, které daný zdroj nepovoluje.

U úpravy zůstane v databázi původní hodnota, u vložení výchozí. Jediná stopa je v logu na serveru. Po zápisu si data načtěte znovu a zkontrolujte.

Vlastníka a IP adresu dosazuje server

Při vkládání se vlastník bere z přihlášení a IP adresa z požadavku. Poslaný identifikátor uživatele ani adresa se nepoužijí.

Úprava vlastního účtu#

Přihlášený uživatel smí přes /api/system/user/save upravit svůj účet (data[id] = jeho id; cizí id skončí 403).

Smí změnit	Nezmění (pole se tiše vynechá)
jméno a příjmení, telefon, ulici, město, PSČ, stát a zemi	uživatelské jméno a e-mail
firmu, IČ, DIČ, příznak firmy, typ uživatele	kredity, body, slevu a slevovou úroveň
platební region, jazyk, web, „o mně“	členství (`memberUntil`)
	avatar (`assetPath`), napojení na cizí službu (`type`, `externalId`)
	heslo — to mění jen `update-password`

Region se odvozuje z platebního regionu

Pole regionId uživatele dopočítá server z paymentRegionId; poslaná hodnota se přepíše.

Zrušený účet se uložit nedá

U anonymizovaného účtu vrátí uložení kód 120.

Podobně jsou zamčená pole i u dalších záznamů, které vlastník upravuje: komentář, hodnocení ani odpověď na inzerát nepřesunete k jinému vláknu nebo inzerátu a příznaky moderace či „přečteno“ přes save nenastavíte.

Kvóta zakládání obsahu#

Nové odpovědi na inzerát nebo firemní profil, příspěvky a nahlášení v diskuzi, komentáře, nahlášení inzerátu a zprávy z kontaktního formuláře mají horní mez počtu za hodinu. Nad ní vrátí save success: false a kód 404 (s HTTP 200). Hodnoty jsou v Limitech.

Změna vybraných polí#

/api/eshop/order/update-columns?ids[]=5&values[stav]=2

ids musí být neprázdné pole a values pole; jinak HTTP 400.

Zvenčí to u většiny zdrojů nefunguje

Seznam povolených sloupců je výchozím nastavením prázdný, takže volání skončí kódem 607. Funguje jen u sloupců, které mají výslovnou výjimku.

Žádný částečný zápis

Stačí jeden nepovolený sloupec a padá celé volání.

Mazání#

/api/bazaar/watchdog/delete?id=123
/api/bazaar/watchdog/delete?id[]=1&id[]=2

Hromadné mazání neprojde kontrolou vlastnictví

Pro roli vlastníka je vždy zamítnuté.

delete-all bez filters smaže celou kolekci

Smí-li volající akci použít, chybějící filtr znamená „všechno“. Špatně sestavený filtr naopak vrátí HTTP 400 a nesmaže nic.

Stromové zdroje#

Kategorie a menu nabízejí navíc move-up, move-down, move-subtree, move-subtree-to, insert-tree-node a delete-node.

delete-node smaže celý podstrom

Ne jen uzel.

Události#

register-event zvýší počítadlo o jedna:

/api/comcat/advert/register-event?ids[]=1&property=views

Povolené názvy počítadel jsou omezené seznamem. ids musí být neprázdný seznam kladných celých čísel, jinak HTTP 400.

🔴 Řada funkcí není zvenčí dostupná#

Zdroj může existovat a přesto vracet 404

Systém obsahuje mnoho operací, které používá jen web zevnitř a které nemají HTTP obal. Patří sem košík, dokončení objednávky, přehledy „moje“, dostupnost a aktuální ceny.

Poznáte to tak, že akce vrátí 404 s HTML, přestože zdroj i oprávnění existují.

Nastavení cookies