Agenda kontakt

Obsahuje kontakty firmy u inzerátů. Kontakt je sada telefonů, e-mailu a webu, kterou firma přiřadí inzerátu a která se u něj ukazuje místo údajů pobočky. Adresa, název prodejce („Prodejce“) a otevírací doba zůstávají vždy z pobočky.

Telefony jako celek: má-li kontakt aspoň jeden telefon, ukazují se u inzerátu jen telefony kontaktu (i jediný), jinak všechny telefony pobočky.
E-mail a web každý zvlášť: co kontakt nemá vyplněné, se vezme z pobočky.
E-mail pro dotazy (emailOdpovedi) se na webu nezobrazuje. Dotazy z formuláře u inzerátu chodí na něj, není-li vyplněný, na e-mail kontaktu, a teprve když kontakt nemá žádný e-mail, na e-mail pobočky.
Úprava kontaktu se projeví hned u všech inzerátů, které ho používají.

Funkce agendy

Název	Možnosti
Podporované metody	`GET`, `PUT`/`POST`, `DELETE`
Podpora úrovně detailu	✔ Výchozí je `summary` u seznamu a `full` u detailu kontaktu
Podpora filtrace	✔
Podpora fulltextu	✘
Podpora stránkování	✔
Podpora řazení	✔ Výchozí řazení je podle `id`
Podpora externích identifikátorů	✘ Kontakt se určuje jen svým ID
Podpora `schémat`	https://api.tipmoto.com/schemas/kontakt-{export\|import}.{xsd\|rng}
Podpora `?fail-on-warning`	✘ Agenda nevrací varování, neplatná data jsou vždy chyba
Podpora dry-run	✔ U všech zápisů včetně smazání
Vrací `location`	✔ Při založení kontaktu

ID kontaktu

ID kontaktu je jednoznačné v celém systému, ne jen v rámci firmy. Kontakt ale vždy patří jedné firmě a přes jinou firmu ho nelze číst, měnit ani přiřadit inzerátu.
0 u inzerátu znamená výchozí kontakt pobočky (inzerát ukazuje údaje pobočky). Kontakt s ID 0 v této agendě neexistuje.
Číslo smazaného kontaktu se znovu nepoužije.

Adresy a metody

Požadavek	Co dělá
`GET /c/{ID firmy}/kontakt.{format}`	Seznam kontaktů firmy. Výchozí detail `summary` = `id` (s atributem `ref` na detail kontaktu) a `nazev`; `detail=full` nebo `detail=custom:…` vypíše další položky. Podporuje filtraci, řazení a stránkování. Firma bez kontaktů vrátí prázdný seznam.
`GET /c/{ID firmy}/kontakt/{ID kontaktu}.{format}`	Detail kontaktu, výchozí detail `full`. Parametry filtrace, řazení a stránkování zde vrátí chybu `406`.
`PUT`/`POST /c/{ID firmy}/kontakt.{format}`	Založení kontaktu (data bez `id`). Vrátí `201 Created` a hlavičku `Location` s adresou nového kontaktu (lze vypnout parametrem `no-http-location`). S `id` v datech jde o úpravu toho kontaktu.
`PUT`/`POST /c/{ID firmy}/kontakt/{ID kontaktu}.{format}`	Úprava kontaktu. Chybějící prvek zůstane beze změny, prázdný prvek hodnotu vymaže. Liší-li se ID v adrese a v datech, vrátí `404`.
`DELETE /c/{ID firmy}/kontakt/{ID kontaktu}.{format}?replace-with={ID}`	Smazání kontaktu. Inzeráty, které kontakt používají, se přepnou na kontakt `replace-with` – jiný kontakt téže firmy, nebo `0` = výchozí kontakt pobočky (výchozí, když parametr chybí). U každého přepnutého inzerátu se zapíše změna `edit`. Totéž udělá `PUT`/`POST` s daty `<kontakt action="delete" replace-with="{ID}"><id>{ID kontaktu}</id></kontakt>`. Neplatný `replace-with` (nečíselný, ID mazaného kontaktu, kontakt, který firma nemá) vrátí `400` a nic se nesmaže. Odpověď obsahuje `prepnutoInzeratu` = počet přepnutých inzerátů.

S parametrem ?dry-run=true proběhne u všech zápisů celá validace, ale nic se neuloží; u smazání vrátí prepnutoInzeratu = počet inzerátů, které by se přepnuly.

Položky agendy

Str. název	Název	Typ	Informace	rw	P	S	➀	➁
`id`	ID kontaktu	`integer`	Jednoznačné v celém systému. Při zakládání nevyplňujte. Ve výpisu seznamu má atribut `ref` s odkazem na detail kontaktu.			✔	✔	✔
`nazev`	Název	`string 64`	Interní název kontaktu pro výběr u inzerátu v administraci; zákazník ho nevidí. Musí být jedinečný v rámci firmy (bez ohledu na velká a malá písmena).	✔	✔	✔		✔
`telefon1`, `telefon2`, `telefon3`	Telefony	`string 16`	Telefon musí mít aspoň 9 číslic. Při uložení se telefony posunou nahoru i s poznámkou (prázdné pozice se vynechají), takže `telefon1` je vždy vyplněný, má-li kontakt nějaký telefon.	✔		✔
`telefon1Text`, `telefon2Text`, `telefon3Text`	Poznámky k telefonům	`string 16`	Poznámka k telefonu se stejným číslem. Poznámka bez telefonu je chyba.	✔		✔
`email`	E-mail	`string 1024`	E-mail zobrazený u inzerátu. Víc adres oddělených čárkou, každá musí být platná; uloží se malými písmeny.	✔		✔
`emailOdpovedi`	E-mail pro dotazy	`string 1024`	Na webu se nezobrazuje; chodí na něj dotazy z formuláře u inzerátu (pořadí viz úvod). Víc adres oddělených čárkou, každá musí být platná.	✔		✔
`url`	Web	`string 2048`	Víc adres oddělených čárkou. Adresa musí být `http://` nebo `https://`; bez schématu se doplní `http://`.	✔		✔
`lastModified`	Poslední úprava	`datetime`	Formát `YYYY-MM-DD HH:MM:SS`, jen ke čtení			✔

rw = lze zapisovat
P = povinná položka
S = dle položky lze filtrovat a řadit
➀ = je v detailu id
➁ = je v detailu summary

Validace

Název je povinný a jedinečný v rámci firmy.
Kontakt musí mít aspoň jeden telefon, e-mail nebo web; samotný e-mail pro dotazy nestačí (zákazník ho nevidí).
Telefony se při uložení posunou nahoru i s poznámkou.
E-maily (email i emailOdpovedi): každá adresa musí být platná.
Web: každá adresa musí být http:// nebo https://.
Neplatná data vrátí 400 se seznamem chyb v chyby a nic se neuloží.

Kontakt u inzerátu

V agendách moto, dily a prislusenstvi je u inzerátu prvek <kontakt id="N" ref="/c/{ID firmy}/kontakt/N.xml"/>. Vypisuje se jen u firem s aspoň jedním kontaktem, pak u každého inzerátu; id="0" (výchozí kontakt pobočky) je bez ref a kontakt, který firma už nemá (např. smazaný), se vypíše jako 0. Zápisem <kontakt id="N"/> v importu inzerátu kontakt přiřadíte, podrobnosti jsou na stránkách těchto agend.

Počet inzerátů, které kontakt používají, API nevydává.

Hooky a změny

Agendu kontakt lze sledovat hooky (hook) i v agendě change: založení, úprava a smazání kontaktu zapíše změnu add, edit nebo delete. Úprava kontaktu se u inzerátů jako změna nezapisuje; smazání kontaktu zapíše navíc změnu edit u každého přepnutého inzerátu (agenda moto, dily, prislusenstvi).

Příklady

GET /c/95/kontakt.xml (seznam, detail summary; vysvětlující komentáře výstupu vynechány):

<tipmoto>
  <kontakt>
    <id ref="/c/95/kontakt/15.xml">15</id>
    <nazev>R&amp;D</nazev>
  </kontakt>
</tipmoto>

GET /c/95/kontakt.xml?detail=full:

<tipmoto>
  <kontakt>
    <id ref="/c/95/kontakt/15.xml">15</id>
    <nazev>R&amp;D</nazev>
    <telefon1>777 333 444</telefon1>
    <telefon1Text>dílna</telefon1Text>
    <telefon2/>
    <telefon2Text/>
    <telefon3/>
    <telefon3Text/>
    <email>info@firma.cz</email>
    <emailOdpovedi>dily@firma.cz</emailOdpovedi>
    <url>http://www.firma.cz/?a=1&amp;b=2</url>
    <lastModified>2026-10-03 10:00:00</lastModified>
  </kontakt>
</tipmoto>

GET /c/95/kontakt/15.json (detail kontaktu; id zde nemá ref):

{"tipmoto":{"kontakt":{"id":"15","nazev":"R&D","telefon1":"777 333 444","telefon1Text":"dílna","telefon2":"","telefon2Text":"","telefon3":"","telefon3Text":"","email":"info@firma.cz","emailOdpovedi":"dily@firma.cz","url":"http:\/\/www.firma.cz\/?a=1&b=2","lastModified":"2026-10-03 10:00:00"}}}

Založení – PUT /c/95/kontakt.xml, odpověď 201 Created s hlavičkou Location:

<tipmoto><kontakt><nazev>Servis</nazev><telefon1>777 111 222</telefon1></kontakt></tipmoto>

<tipmoto>
  <success>true</success>
  <result>
    <id ref="/c/95/kontakt/99.xml">99</id>
  </result>
</tipmoto>

Úprava – PUT /c/95/kontakt/15.xml změní jen telefon2, ostatní položky zůstanou:

<tipmoto><kontakt><telefon2>777 111 333</telefon2></kontakt></tipmoto>

<tipmoto>
  <success>true</success>
  <result>
    <id ref="/c/95/kontakt/15.xml">15</id>
  </result>
</tipmoto>

Neplatná data – odpověď 400:

<tipmoto>
  <success>false</success>
  <chyby>
    <chyba>Neplatný e-mail „o'neil@x.cz“.</chyba>
  </chyby>
  <result/>
</tipmoto>

Zkouška smazání – DELETE /c/95/kontakt/15.xml?replace-with=0&dry-run=true; nic se nesmaže, prepnutoInzeratu je počet inzerátů, které by se přepnuly:

<tipmoto>
  <success>true</success>
  <dryRun>true</dryRun>
  <result>
    <id>15</id>
    <prepnutoInzeratu>9</prepnutoInzeratu>
  </result>
</tipmoto>

Smazání přes PUT /c/95/kontakt.xml; inzeráty se přepnou na výchozí kontakt pobočky:

<tipmoto><kontakt action="delete" replace-with="0"><id>15</id></kontakt></tipmoto>

<tipmoto>
  <success>true</success>
  <result>
    <id>15</id>
    <prepnutoInzeratu>6</prepnutoInzeratu>
  </result>
</tipmoto>

Chyby

HTTP kód	Kdy
`400`	neplatná data kontaktu (seznam chyb v `chyby`), název, který firma už má, neplatný `replace-with`, neplatná hodnota parametru `dry-run`; nic se neuloží ani nesmaže
`402`	login nemá právo čtení (u zápisu právo zápisu) do agend firmy, nebo firma nemá povolené exporty/importy
`404`	kontakt neexistuje nebo nepatří firmě; ID v adrese a v datech se liší; smazání bez ID kontaktu
`405`	jiná metoda než `GET`, `PUT`/`POST`, `DELETE`
`406`	chybné XML/JSON nebo chybí struktura `kontakt`; chybný parametr `filter` nebo filtrace s detailem `id`; filtrace, řazení nebo stránkování u detailu kontaktu; chybný `xpath`