api.tipmoto.com » Dokumentace API » Referenční » Web-Hooky

Web-Hooky

Hooky jsou způsob, jak se ve Vaší aplikaci v reálném čase dozvědět o změně ve TipMoto.com. Princip je jednoduchý: když dojde na TipMoto.com ke změně, je (standardně do jedné minuty od změny) odeslán POST HTTP request na Vámi zadanou URL. Obsahem požadavku je popis dané konkrétní změny a to ve stejném formátu, jaký získáte v agendě change.
Ukázkový výstup:

<tipmoto>
  <change>
    <id ref="/c/123/change/987654.xml">987654</id>
    <c ref="/c/123.xml">123</c>
    <agenda ref="/c/123/moto.xml">moto</agenda>
    <agendaId ref="/c/123/moto/123456.xml">123456</agendaId>
  </change>
</tipmoto>

Nastavení hooku

Hook můžete zaregistrovat / upravit pomocí požadavku na agendu:

http(s)://api.tipmoto.com/c/{ID firmy}/hook.{format}

pomocí následujícího PUT nebo POST požadavku. Ukázka v XML formátu:

<tipmoto>
  <hook>
    <url>http://www.vasedomena.cz/vaseaplikace/</url>
    <format>xml</format>
    <method>PUT</method>
    <agenda>moto,dily</agenda>
    <secKey>Overovaci klic (není povinné)/</secKey>
  </hook>
</tipmoto>

Lze zadat i pomocí JSON formátu. Přehled všech možností je uveden v dokumentaci agendy.

Případně je možné zaslat GET požadavek:

http(s)://api.tipmoto.com/{ID firmy}/hook.{format}?url=URL?&agenda=AGENDA&method=METHOD&secKey=SECKEY

Zpracování Hooku na Vaší straně

Na hook je třeba odpovědět stavovým kódem HTTP 200 OK, popř. kódem 2xx a hook se tímto považuje za zpracovaný. Požadavek na Vaší straně je třeba vrátit cca do 15sec, jinak se může hook považovat za nezpracovaný! Pokud zpracování na Vaší straně trvá déle, doporučujeme uložit reprezentaci hooku, vrátit HTTP kód a spustit zpracování např. v jiném vkláknu!

Když nastane chyba

Není-li vrácen kód 2xx, hook se pokoušíme doručovat opakovaně. Nejprve každou minutu, následně začíná docházet ke zpožďování (které lze přečíst v agendě hook v parametru penalty), po týdnu je pak hook zcela vyřazen.

Nezapomeňte při zpracování

Přestože se hooky snažíme zasílat v pořadí, tak už z principu nedokážeme zaručit, že Vám na server dojdou ve správném pořadí, tj. pokud se inzerát např. edituje a vzápětí ihned smaže, je možné, že Vám přijde dříve editace, a pak smazání. Nebo např. může dojít k duplicitě a jeden hook Vám přijít opakovaně.

Hooky (i changes) mají metody tak, jak byly zaznamenány na Tipmoto. Avšak pozor - například metoda EDIT může znamenat i např. vyřazení/zařazení inzerátu ve výstupu (viz. položky zakázané v exportu)

Máte-li více firem

Na každou firmu musíte registrovat extra hoook. Jedna firma může mít registrovaných více hooků přes různé API loginy.

Hooky pro agendu lists

Analogicky lze sledovat i agendu lists.
Lze nastavit jeden hook na Váš přístup do API
Ačkoliv se hook ukrývá v agendě lists, pro přístup k hooku a jeho správu musíte být přihlášeni!
Hook můžete zaregistrovat / upravit pomocí požadavku na agendu:

http(s)://api.tipmoto.com/lists/listhook.{format}

Formát je shodný jako u hooku firmy, stejně tak lze analogicky použít i GET požadavek. Přehled sledovaných možností je uveden v dokumentaci agendy.

Kontaktujte nás