Změny API

Zaznamenává změny chování, které se dotknou integrací.

Současný stav

Oblast	Stav
Verze	v1
Autentizace	povinný klíč aplikace X-API-Key + volitelný JWT uživatele s rotací obnovovacího tokenu — viz Autentizace
Oprávnění	vynucují se
Modul Sklad	zvenčí jen pro čtení
Specifikace	pokrývá jen přihlašovací endpointy; u každé operace vyžaduje apiKeyAuth

Známá omezení

Věci, o kterých víme a které se mohou změnit:

Omezení	Poznámka
Parametry v adrese	i u zápisu; tělo se nečte (kromě přihlášení a akcí s hesly)
Dva tvary odpovědi	čtení bez obálky, zápis s obálkou
Chyby s kódem 200	stavový kód rozliší jen 400, 401, 403, 429
Nekonzistentní obálka chyby	někdy tři klíče, jindy čtyři
Metoda HTTP se ignoruje	GET na mazací akci maže
Kolekce vlastníka	get-all a get-by jsou pro vlastníka zamítnuté
Chybějící HTTP obaly	košík, dokončení objednávky, přehledy „moje“
Tiché zahazování dat při zápisu	jediná stopa je v logu serveru

Tenhle seznam berte jako smlouvu

Popsané chování je stav, na kterém se dá stavět. Změní-li se, objeví se to tady.

Změny kontraktu od 1. 10. 2026

Co se změnilo	Dopad na klienta
notification: pole userId se jmenuje receiverUserId	filtry, řazení i čtení odpovědí musí používat nový název; starý alias neexistuje. Hodnota je příjemce notifikace, null = společná pro všechny administrátory. Sloupec v databázi se nezměnil
Nová podmíněná role receiver	nový typ pravidla v RBAC, viz Oprávnění
response (bazaar, comcat): akce get je dostupná příjemci	majitel inzerátu přečte detail odpovědi na svůj inzerát; dřív jen administrátor
response: nové pole readKey	náhodný tajný klíč pro odkaz „Označit jako přečtené"; nastavuje server, zvenčí se nezapisuje. Starší odpovědi ho mají prázdné
response: nová vnitřní akce mark-read-by-key	jen z webu; HTTP obal nemá
rating: akce save-reply jde přes roli receiver	odpoví majitel hodnoceného profilu; dřív to řešila role owner
message-thread, message, message-participant: akce nad jednou konverzací jsou pro owner a receiver	nemají HTTP obal; zvenčí je dál jen CRUD pro administrátora
nový zdroj external-connection (/api/system/external-connection)	jen administrátor; config obsahuje tajné klíče

config u external-connection obsahuje tajné klíče

Čtení i zápis smí jen administrátor. Odpověď s klíči neukládejte, nelogujte a nepředávejte dál.

Čtení bez rozlišení názvu userId už u notifikací nefunguje

Pokud váš klient filtroval notifikace podle userId, filtr teď selže nebo se zahodí. Přejmenujte ho na receiverUserId.

Změny kontraktu ze 2. 10. 2026 (odpoledne a večer)

Co se změnilo	Dopad na klienta
response (bazaar, comcat): měna je povinná jen s cenou (price, currencyId)	cena bez měny skončí odpovědí success: false, code: 2 (validace) a zprávou „Cena reakce je vyplněná, ale chybí měna.“ Měna bez ceny se zahodí (uloží se null) a zápis uspěje
response: měnou ceny smí být jen veřejná peněžní měna	interní nebo nepeněžní měna (třeba „Kredity“) skončí odpovědí success: false, code: 2 a zprávou „Měna #… není veřejná peněžní měna …“. Které měny smíte použít, zjistíte z currency: aktivní, monetary zapnuté, internal vypnuté
zápis, který obsahuje pole označená FieldAccess … Audience::None, je tiše ořezán	pole password a salt u user, accessToken u message-thread a cancelToken u reservation se z těla zápisu neberou na žádné cestě. Odpověď je úspěšná, pole se jen neuloží. Heslo uživatele se mění jen cestou, kterou k tomu určuje web
message-thread: subject konverzace z odpovědi nese název inzerátu (bazaar) nebo předmět poptávky (comcat)	hodnota je surový text bez předpony; „Reakce na inzerát: …“ / „Poptávka: …“ skládá až web při zobrazení. Starší konverzace mají subject prázdný
zápis jednoho sloupce (update-columns) s logickou hodnotou false	false se váže jako číslo 0; dřív na serveru v přísném režimu databáze selhalo

Kódy currencyRequired a currencyNotAllowed na drát nejdou

Server rozlišuje dva důvody (errorCode = currencyRequired / currencyNotAllowed), ale ty jsou jen v interním výsledku operace — odpověď API je nese jen jako text zprávy a data je null. Klient proto rozhoduje podle code: 2 a podle toho, co sám odeslal, ne podle textu zprávy (ten se může změnit).

Od 19. 10. 2026 je odpověď nese v data.errorCode, viz Změny kontraktu od 19. 10. 2026.

Posílejte měnu jen s cenou

Nejjednodušší klient pošle currencyId společně s price a bez ceny měnu vynechá.

Změny kontraktu ze 3. 10. 2026

Požadavky a odpovědi

Co se změnilo	Dopad na klienta
parametr ve špatném tvaru vrací HTTP 400 a kód 2	text místo pole (filters, orderBys, columns, data, meta, skipFields, values), chybějící nebo prázdné ids u update-columns, neplatné ids u register-event, neznámý zápis logické hodnoty (computeTotalCount=ano) a includes ve špatném tvaru se už nepřetypují ani neskončí chybou 500. Viz Chybové kódy
neznámý nebo špatně sestavený filtr vrací HTTP 400	dřív chyba 500 s HTML. Doplňkové klíče inclusive a isNull v adrese neprojdou (čekají pravdivostní hodnotu)
get-all: includes=* a columns vracejí HTTP 400	dřív chyba 500. Jedna cesta jako řetězec (includes=user) nově funguje i u výpisu; includes=* zůstává jen u get
filtry, řazení a sloupce jen nad poli, která smíte číst	cesta na heslo, IP adresu, osobní údaj cizího uživatele nebo neexistující pole vrátí HTTP 400 se zprávou Field path "…" is not allowed in filters, orderBys or columns. Viz Oprávnění
save: textové hodnoty z adresy se převádějí podle typu pole	data[currencyId]=3 se uloží jako číslo, true/false jako logická hodnota, datum jako datum; prázdný řetězec u nepovinného pole = null. Hodnota, která se převést nedá (1.9 do celého čísla), vrátí kód 604 se jménem pole. Dřív zápis číselných polí z adresy selhal. Viz CRUD vzor
save vlastníka tiše vynechá zamčená pole	vlastník smí upravit svůj účet (user/save), ale kredity, body, slevu, členství, e-mail, uživatelské jméno, avatar ani napojení na cizí službu nezmění — pole se vynechá a zůstane hodnota z databáze. U komentáře, hodnocení, odpovědi na inzerát a příspěvku nepřesunete záznam k jinému vláknu či inzerátu. regionId uživatele se dopočítá z paymentRegionId. Viz Úprava vlastního účtu
kvóta zakládání obsahu	nové odpovědi na inzerát a firemní profil, příspěvky a nahlášení v diskuzi, komentáře, nahlášení inzerátu a kontaktní zprávy: 30 za hodinu na uživatele a 60 za hodinu na adresu. Nad limitem success: false, kód 404, HTTP 200. Viz Limity

Data v odpovědích

Co se změnilo	Dopad na klienta
osobní údaje cizích uživatelů: telefon, ulice, PSČ, IČ, DIČ, název firmy a „o mně“	cizímu volajícímu přijdou prázdné. Kontakt na prodejce čtěte z user/public-profile a user/show-phone
IP adresy u inzerátů, odpovědí, hlášení, příspěvků, hlasů, plateb a objednávek	cizímu volajícímu přijdou prázdné
kredity, body, sleva a slevová úroveň cizího uživatele	klíč v odpovědi chybí; vlastník a administrátor je vidí
hesla a klíče inzerátů a příspěvků, aktivační klíč odběru novinek, readKey odpovědi, klíč košíku, heslo odchozí pošty, otisky tokenů	přes HTTP je nedostane nikdo, ani administrátor. readKey už tedy v odpovědi response nenajdete

Přihlášení a hesla

Co se změnilo	Dopad na klienta
user/update-password vyžaduje currentPassword	bez něj nebo se špatným vrací kód 108; nové heslo kratší než 8 znaků 611. Úspěch vrací v data nový pár tokenů a odvolá ostatní obnovovací tokeny účtu — uložte ho. Viz Autentizace
hesla, klíče a tokeny jen v těle POST	update-password (password, currentPassword), reset-password (email, key, password) a is-auth-valid (token, nebo hlavička Authorization) čtou tělo — formulářové i JSON. Hodnota v adrese se ignoruje
user/send-new-password pošle odkaz, heslo nemění	odkaz platí hodinu; nové heslo nastaví POST user/reset-password. Neplatný klíč = kód 112
jednotná chyba přihlášení	neznámý účet i špatné heslo vracejí kód 110. Neaktivní (109) a zablokovaný (104) účet se hlásí až po správném hesle. Nový limit: 20 neúspěšných přihlášení za hodinu na účet ze všech adres
přístupový token neplatí po zablokování, deaktivaci nebo změně hesla	dřív platil až do vypršení (15 minut). Klient dostane 401 hned
zrušení účtu	rušený účet se nepřihlásí (kód 117, data.scheduledAt = datum zrušení), obnova jeho tokenu vrátí 102; zrušený účet nejde uložit (kód 120). Žádost i storno jsou jen na webu
přihlášení přes cizí službu potvrzuje propojení e-mailem	probíhá na webu; nové kódy 113–116

Odstraněné a vnitřní akce

Co se změnilo	Dopad na klienta
odstraněny akce payment-item/update-status-for-payment (bazaar, comcat, discussion) a user-payment/update-status-for-payment	vracejí 404. Stav platby mění jen platební brána a administrace
payment/express-offers je jen vnitřní	nabídku expresní SMS platby skládá web; HTTP obal nemá
payment/express-execute přijímá SMS od agregátora	odpovídá prostým textem podle specifikace agregátora; pro integrace není

Změny kontraktu z 5. 10. 2026

Co se změnilo	Dopad na klienta
přihlášení: limit účtu nad limitem ověřuje heslo jen ze známého zařízení nebo adresy	externí auth/login je vždy neznámé zařízení (cookie neposílá); pomůže mu jen adresa s úspěšným přihlášením účtu za posledních 30 dnů. Odpověď při zaškrcení je beze změny (429, Retry-After). Viz Limity
e-mail po vložení inzerátu nenese heslo, nese odkaz ke správě	odkaz platí 7 dní, jde použít opakovaně a po změně hesla inzerátu přestane platit. Heslo ve frontě odchozí pošty je zamaskované. Kdo prokáže přístup heslem inzerátu, vidí v odpovědi nemaskované osobní údaje jen toho inzerátu
klíč path v nahrávaných souborech se u externích volání zahazuje	externí klient posílá soubory jako base64 v data; odkaz na soubor na serveru přijímá jen interní volání z formulářů webu
get-all bez limit vrací 50 záznamů, limit je omezen na 500	klient, který spoléhal na úplný výpis jedním voláním, musí stránkovat (offset, limit, computeTotalCount=1). Větší limit se neodmítá, jen ořízne. Týká se volání zvenčí
obálka odpovědi nemá pole exception	klíče jsou success, message, data, code. Pole exception dřív bylo vždy null, klient ho nemá číst
u technického selhání je message prázdný, rozhoduje code	databázové, souborové a interní chyby API už nevrací text výjimky. Chyby validace a obchodních pravidel nesou zprávu jako dosud. Viz Formát odpovědí

Změny kontraktu ze 6. 10. 2026

Hlavní změna: každé externí volání API musí nést klíč aplikace.

Co se změnilo	Dopad na klienta
povinný klíč aplikace v hlavičce X-API-Key (jen HTTPS)	klíč vydává administrátor webu v Nastavení → Aplikace s přístupem k Api a zobrazí se jen jednou; identifikuje aplikaci, ne uživatele. Tvar coolcms_ a 64 hexadecimálních znaků. Vyžadují ho i přihlášení, obnova tokenu a odhlášení. Viz Autentizace
klíč a token uživatele platí společně	bez Authorization: Bearer se volání vyhodnotí jako guest (to, co vidí anonymní návštěvník webu); s tokenem s rolemi uživatele. Neplatný nebo vypršelý token dál vrací 401 s kódem 103, nespadne tiše na hosta
chybějící, špatný, vypnutý nebo zrušený klíč	vždy tatáž odpověď: HTTP 401, kód 501 (API_UNAUTHORIZED), zpráva A valid application key (X-API-Key) is required.. Neříká, který případ nastal. Viz Chybové kódy
limity pro aplikaci	výchozí 20 za sekundu a 600 za minutu na klíč, sdílené všemi uživateli aplikace; pod nimi limit na volajícího (účet z tokenu, bez tokenu a u veřejných akcí adresa IP), výchozí 120 za minutu. Okna jsou pevná. Administrátor webu hodnoty může u aplikace změnit. Viz Limity
překročený limit	HTTP 429, hlavička Retry-After, tělo se zprávou Too many requests., data.retryAfter a kódem 404 (RATE_LIMIT_EXCEEDED, ne stavový kód HTTP). Zvláštní limity endpointů platí dál; limit přihlášení a obnovy tokenu vrací beze změny zprávu Too many requests, retry in <N>s s data.retryAfter
klíč nemá rozsahy (scopes)	klíč neurčuje, jaká data aplikace dostane, ani nenahrazuje přihlášení. Co volání smí, určují role uživatele (bez tokenu guest)
povolené role aplikace	administrátor webu určuje, které role smí aplikace použít. Výchozí pro novou aplikaci: guest, registrated, owner, receiver; administrátorské role jen výslovně. Administrátor přes aplikaci bez role admin jedná jako běžný uživatel (403 u akcí jen pro administrátory, bez polí jen pro administrátory a bez nemaskovaných osobních údajů). Bez role owner nejde upravit ani vlastní záznam. Role guest je povolená vždy (bez ní by nešlo volat bez tokenu ani se přihlásit). Viz Oprávnění
endpointy bez klíče	/api/system/payment/execute, /api/system/payment/delivery, /api/system/payment/express-execute a /api/system/auth/oauth-deauthorize-callback volají třetí strany, které klíč poslat nemohou. Partnerské aplikace je nevolají
X-API-Key v CORS	je povolená hlavička předběžného dotazu; klíč v aplikaci nebo skriptu v prohlížeči není tajný
specifikace OpenAPI	/api-docs.json u každé operace vyžaduje apiKeyAuth společně s volitelným bearerAuth

Klient bez klíče dostane 401

Doplňte hlavičku X-API-Key do každého volání. Dřívější popis klíče jako náhrady přihlášení pro volání ze serveru už neplatí: klíč je součástí každého požadavku a token uživatele se k němu přidává.

Změny kontraktu ze 6. 10. 2026 (klíče s expirací)

Co se změnilo	Dopad na klienta
aplikace může mít víc klíčů (nejvýš 5 platných)	administrátor vydá další klíč, aniž by ten dosavadní přestal platit — výměna klíče bez výpadku. Viz Autentizace
klíč může mít expiraci	po ní klíč vrací stejnou odpověď jako neznámý klíč: HTTP 401, kód 501. Expiraci jde nastavit i dodatečně (rotace: starému klíči expirace, nový klíč, nasazení, po expiraci smazání). Klíč čtěte z konfigurace, ať výměna nevyžaduje nový kód
zrušení jednoho klíče	zrušený klíč vrací 401 s kódem 501 hned, ostatní klíče aplikace platí dál
limity patří aplikaci	výchozí 20 za sekundu a 600 za minutu sdílejí všechny klíče aplikace (dřív „na klíč", aplikace měla jeden)

Změny kontraktu od 19. 10. 2026

Hlavní změna: API hlídá zápis neprivilegovaného volajícího stejně jako formuláře webu a externí čtení inzerátů vrací jen to, co web zobrazuje. Administrátor (role admin) se nekontroluje ani nefiltruje.

Čtení

Co se změnilo	Dopad na klienta
advert (bazaar, comcat): get, get-by, get-all a search vracejí jen inzeráty a profily aktivní a neprošlé (expirationDate dnes nebo později), nebo vlastní (insertUserId = uživatel z tokenu)	skrytý záznam zmizí i s vazbami (parametry, kategorie, obrázky, soubory, texty); get skrytého vypadá jako nenalezený. Stránka může mít méně záznamů než limit, totalCount je horní odhad. Dřív zůstával prošlý inzerát ve výpisu. Viz Bazaar
category (bazaar, comcat): jen aktivní kategorie	vypnutá kategorie se nevrátí
blog/carousel: get-all je veřejné	čte host (jen klíč aplikace) i přihlášený uživatel

Zápis — nová odmítnutí

Co se změnilo	Dopad na klienta
odmítnutý save nese data.errorCode	stálý název důvodu; dřív byl data u neúspěchu null. Ostatní podrobnosti (číslo parametru, chybějící pole, typ blokovaného údaje) jsou jen v textu zprávy. Viz Chybové kódy
advert/save (bazaar, comcat): pravidla parametrů jako ve formuláři	code: 2 s errorCode parameterTooLong, parameterUrlNotAllowed, parameterBlacklistedWord (aktivní zakázaná slova v jazyce stránky požadavku), parameterRequired (povinnost podle pravidel parametrů, např. typ ceny) a parameterOptionNotAllowed. Povinné parametry se kontrolují při vložení; nahrávání souborů a skrytá pole ne
advert/save: vypnutá kategorie nebo kategorie jen pro administrátora	code: 615, errorCode: advertCategoryNotAllowed
advert/save: nový obrázek nad limit velikosti	obrázek se neuloží, zbytek zápisu projde; saveInfo.rejectedUploads obsahuje {"name": …, "reason": "size"}. Limit: max_size parametru, jinak nastavení maxImageSize, jinak 50 MB
advert/extend-expiration v placené kategorii	code: 607, data: null — prodloužení se platí na webu
user/save: typ účtu vyžaduje IČ a název firmy nebo DIČ	code: 2, errorCode: userTypeDataMissing; jen když zápis nese typ účtu. Viz System
blacklist e-mailů, telefonů a IP adres (i rozsahy CIDR)	nové komentáře, odběratelé newsletteru, inzeráty a profily, odpovědi, hlídací psi, kontaktní zprávy, příspěvky diskuze, reklamace, objednávky, rezervace a nové účty se zablokovaným údajem: code: 615, errorCode: blacklisted. U úpravy účtu jen změněný e-mail nebo telefon. Viz System
comment/save do vlákna s vypnutými komentáři	code: 607, errorCode: commentsClosed
comment/save hosta, kde smějí komentovat jen přihlášení	code: 400, errorCode: commentOnlyForLoggedIn (HTTP 200)
response/save (bazaar) na prodaný inzerát	code: 607, errorCode: advertSold
zakázaná slova jsou jeden seznam (system/blacklisted-word)	inzerce, katalog firem i diskuze sdílejí systémový seznam; modulové seznamy neexistují

Změny kontraktu od 29. 10. 2026

Co se změnilo	Dopad na klienta
technické selhání (chyba databáze, souboru, externí služby, fronty, neznámá chyba — např. code 1, 300, 500) už v message nenese text výjimky	message je obecná hláška „An internal error occurred. Quote the reference when contacting support.“ a odpověď má navíc klíč errorRef (krátký náhodný kód). Ostatní klíče (success, code, errorCode, data) se nemění; doménové chyby (validace, stav, nenalezeno) zůstávají beze změny a bez errorRef. Viz Chybové kódy

Chování při změnách

Vypínač oprávnění platí pro celé API

Přepnutí režimu změní chování všech zdrojů naráz. Váš klient musí umět zpracovat zamítnutí u akce, která dřív procházela.

Piště klienta obranně

Kontrolujte typ obsahu, existenci klíčů a stavový kód. Odpověď se může v podrobnostech lišit zdroj od zdroje.

Co se chystá

Věc	Stav
Doplnění specifikace o CRUD zdroje	plánované
HTTP obaly pro chybějící operace	podle potřeby integrací

Potřebujete něco, co není dostupné?

Ozvěte se provozovateli. Řada operací existuje a chybí jim jen HTTP obal — doplnit ho je otázka jednoho zdroje, ne nové funkce.

Nastavení cookies