Vlastní akční tlačítka

Vlastní akční tlačítko přidá do aplikace vaše vlastní tlačítko, které zavolá externí službu. Uživatel tak nemusí opouštět mWork365 — klikne u zákazníka na Odeslat do ERP nebo u zakázky na Vystavit fakturu a vaše služba dostane požadavek s tím, o který záznam jde.

Zatímco webhooky se ozvou samy, jakmile něco nastane, tlačítko spouští uživatel — a na rozdíl od webhooku se výsledek volání hned zobrazí v aplikaci.

Jak to funguje

Kliknutí v aplikaci → Požadavek na vaši URL → Akce ve vaší službě → Hláška uživateli

Volání jde ze serveru mWork365, ne z prohlížeče uživatele — vaše služba tedy musí být dostupná z internetu, ale nemusí řešit CORS.

Jak tlačítko nastavit

Tlačítka přidáte v Nastavení firmy → Integrace v sekci Tlačítka vlastních akcí (uživatel musí mít roli administrátor). Klikněte na Přidat tlačítko a vyplňte:

Pole	Význam
Název	Text na tlačítku.
Popis	Interní poznámka pro přehled v nastavení.
Metoda	GET, POST, PUT nebo DELETE. Určuje i to, jak se předají data — viz Co mWork365 odešle.
URL	Adresa vaší služby. Může obsahovat zástupné značky {id} a {externalId}.
Entita	Agenda, ke které tlačítko patří.
Umístění	Tabulka (přehled) nebo Detail (konkrétní záznam).
Viditelné pro techniky / Viditelné pro dispečery	Komu se tlačítko zobrazí. Administrátor vidí vždy všechna.
Signature secret	Klíč pro podpis odchozích požadavků. Necháte-li pole prázdné, vygeneruje se automaticky.
Vyžadovat potvrzení po kliknutí	Před odesláním se uživatele zeptáme „Opravdu chcete provést tuto akci?“. Vhodné u nevratných operací.
Obnovit data po dokončení	Po úspěšném volání aplikace načte data znovu — použijte, když vaše služba v mWork365 něco změní.
Ikona tlačítka	Volitelná ikona z nabídky.

Kde se tlačítka objeví

U tlačítka určujete entitu a umístění:

• Umístění „Tabulka“ — tlačítko je v záhlaví přehledu a pracuje s agendou jako celkem (například „Spustit synchronizaci“). Neváže se na konkrétní záznam.
• Umístění „Detail“ — tlačítko je mezi akcemi na detailu záznamu a mWork365 spolu s ním pošle, o který záznam jde.

Tlačítka lze přidat k těmto entitám: zákazník, zařízení, zakázka, výjezd, externí požadavek, požadavek zákaznického portálu, materiál a sklad. U skladu je k dispozici pouze umístění Detail.

Když se na jednu obrazovku hodí víc tlačítek, aplikace je sloučí do rozbalovací nabídky Vlastní akce. Tlačítka fungují ve webové i v mobilní aplikaci.

Co mWork365 odešle

U tlačítka v detailu se odesílají údaje o záznamu:

Pole	Obsah
id	Identifikátor záznamu v mWork365.
externalId	Externí ID záznamu, pokud je vyplněné.
name	Název záznamu — jen u entit, které název mají (zákazník, zařízení, zakázka, materiál, sklad).
userId	Identifikátor uživatele, který na tlačítko klikl.
isTest	true, pokud jde o testovací spuštění z nastavení.

U tlačítka v tabulce se odesílá jen userId a isTest — tlačítko se neváže na žádný konkrétní záznam.

Jak se data předají, závisí na metodě:

• POST a PUT — data jdou v těle požadavku jako JSON:

  {
    "id": "3f2b8c14-0a7e-4f39-9a1e-2d5b7c9e0f11",
    "externalId": "ERP-1042",
    "name": "Novák s.r.o.",
    "userId": "8c1a54d2-77b0-4c63-9e2f-1a4d6b8e3c05",
    "isTest": false
  }

• GET a DELETE — data se připojí jako parametry dotazu:

  https://vase-sluzba.cz/mwork/export?id=3f2b8c14-…&externalId=ERP-1042&name=Nov%C3%A1k%20s.r.o.&userId=8c1a54d2-…&isTest=false

Kromě toho můžete identifikátory dostat rovnou do cesty URL — značky {id} a {externalId} mWork365 před odesláním nahradí hodnotami záznamu. Z URL

https://vase-sluzba.cz/zakaznik/{externalId}/sync

se tak stane https://vase-sluzba.cz/zakaznik/ERP-1042/sync. Zástupné značky fungují jen u tlačítek v detailu.

Jak zpracovat odpověď

Aplikace vyhodnotí HTTP status odpovědi a dá uživateli vědět:

• 2xx — akce se povedla. Vrátíte-li JSON s polem message, zobrazí se jeho text; jinak se ukáže obecná hláška Akce proběhla úspěšně.
• Cokoli jiného — uživateli se ukáže chybové hlášení se stavovým kódem a začátkem odpovědi (prvních 500 znaků). Pole message se použije jako titulek chyby, takže i chybovou hlášku můžete formulovat sami.

{ "message": "Zákazník byl odeslán do ERP pod číslem 1042." }

Upozornění

Na rozdíl od webhooků mWork365 čeká na odpověď vaší služby a volání neopakuje. Dlouhé operace proto raději jen nastartujte a odpovězte hned — uživatel jinak čeká na odpověď u otevřené obrazovky.

Ověření podpisu

Vaše URL je veřejně dostupná, takže by na ni mohl zavolat kdokoli. Aby vaše služba poznala, že požadavek opravdu poslal mWork365, je každé volání podepsané — z dat požadavku spočítáme HMAC SHA-256 pomocí Signature secretu daného tlačítka a výsledek pošleme v hlavičce X-Provider-Signature.

U tlačítek se podepisuje něco jiného podle metody: u POST a PUT tělo požadavku, u GET a DELETE zřetězení metody, URL a časového razítka z hlavičky X-Timestamp. Výpočet i postup ověření popisuje Podpis odchozích požadavků — stejný mechanismus platí i pro webhooky.

Otestování tlačítka

V seznamu tlačítek v nastavení má každý řádek ikonu přehrání — tou tlačítko zkusíte rovnou z nastavení, bez hledání vhodného záznamu v aplikaci. mWork365 u tlačítek v detailu vybere náhodný záznam dané entity z vaší firmy a do dat přidá isTest: true, takže vaše služba pozná testovací volání a může u něj akci přeskočit.

Výsledek se ukáže stejně jako při běžném kliknutí — včetně chybového hlášení i s odpovědí vaší služby, takže se dá podle něj ladit.