 API

S API aplikace DiMaker můžete vytvářet soubory s osobními údaji a v případě potřeby je doručit příjemcům. Požadavky na API mohou být odesílány jak ze serveru, tak přímo z prohlížeče přes CORS.

Začínáme

V sekci „Integrace“ - „API tokeny“ je nutné získat Secure token pro požadavky a povolit jeho použití. Dále je potřeba vytvořit dokument s proměnnými pro osobní údaje, šablonu e-mailu pro rozesílku a složku na Disku pro hotové soubory.

Vytváření souborů

Pro vytváření souborů je potřeba odeslat POST-DATA, POST- nebo GET požadavek na adresu
https://dimaker.app/api/v1/create/
s níže uvedenými daty.
Kódování požadavku - UTF-8. Povinná pole jsou označena hvězdičkou (*).

• secure*

  Token (řetězec, 36 znaků)

• doc_id*

  ID dokumentu (řetězec, 36 znaků), který bude použit pro vytvoření souboru. ID je možné získat v adresním řádku při otevření dokumentu. Dokument nesmí být v koši, ale může být uložen v jakékoli složce na Disku.

• mask*

  řetězec obsahující všechny proměnné pro nahrazení ve formátu klíč (proměnná) - hodnota (text nahrazení). Může obsahovat data pro vytvoření více souborů.
  Příklad pro jeden soubor:
  [{"%name": "Novák", "%body":"100"}]
  Příklad pro více souborů:
  [{"%name": "Novák", "%body":"100"}, {"%name": "Dvořák", "%body":"200"}, {"%name": "Svoboda", "%body":"300"}]
  Pro zadání e-mailové adresy použijte %email, pro název souboru %filename. Pro rozeslání souborů na několik emailových adres je nutné adresy oddělit čárkou, přičemž stav zasílání se zobrazí pouze pro první e-mail.
  Používejte výhradně dvojité uvozovky dle standardu. Pokud hodnota klíče obsahuje uvozovky, musí být escapovány.

  Pro nahrání obrázku do bloku s obrázky můžete použít přímý odkaz (http:// nebo https://), nebo obrázek kódovaný v Base64. V případě Base64 musí řetězec začínat na "data:image/".

  Alternativní metoda
  Pokud řetězec nemůžete odeslat, proměnné pro nahrazení lze odeslat jako jednotlivá pole požadavku. Každá proměnná musí začínat prefixem "mask_", například mask_name a obsahovat hodnotu pro nahrazení. V dokumentu bude vyhledána odpovídající proměnná. Například pole mask_name odpovídá proměnné %name. Pro e-mail je v tomto případě potřeba použít mask_email a pro název souboru mask_filename.

• mail_id

  ID šablony e-mailu (řetězec, 36 znaků) pro zasílání e-mailem. ID lze získat v adresním řádku při otevření šablony. Pokud není předána, e-mail nebude odeslán.

• email_send

  Čas odeslání e-mailu se souborem. Možnosti:
  onfinish - Odeslat všechny e-maily po vytvoření všech souborů (výchozí)
  oncreate - Odesílat e-maily ihned po vytvoření souboru. U jednoho souboru jsou onfinish a oncreate stejné.
  timeout - Odeslat e-maily po určité době. Potřebné parametry:
  email_timeout_value - číselná hodnota intervalu, po kterém odeslat e-mail (celé číslo)
  email_timeout_unit - jednotka intervalu. Může být "m" (minuty), "h" (hodiny), "d" (dny).
  Nebo přesné datum a čas ve formátu unix time pomocí email_timeout_timestamp. Pokud jsou zadány obě metody, přednost má email_timeout_timestamp.

• folder_id

  ID složky na Disku (řetězec, 36 znaků), kam budou soubory uloženy. Pokud složka neexistuje, vytvoří se automaticky při vytvoření prvního souboru.

• page_id

  Pořadové číslo listu (číslo nebo řetězec), pokud dokument obsahuje více listů. Lze zadat buď jeden index (první list - 0) nebo seznam indexů oddělených čárkou.

• result

  Definuje, jakým způsobem má být výsledek vrácen. Možnosti:

  • Výchozí. Vrátí řetězec obsahující výsledek požadavku (viz níže).
  • link. Vrátí odkaz na vytvořený soubor (v případě více souborů odkaz na první). Před samotným vytvořením souboru vrátí API chybu 404. Pokud nebyl vytvořen žádný soubor, vrátí s chybou.
  • file. Vrátí přímo vytvořený soubor (v případě více souborů pouze první). Pokud se očekává více než jeden požadavek za 5 sekund, tento parametr nepoužívejte kvůli možnosti zpoždění.

Výsledek

Odpovědí serveru bude řetězec s možnými hodnotami:

• result

  Výsledek požadavku. Možnosti:
  error - Chyba při provádění požadavku. Soubory nebyly vytvořeny.
  success - Požadavek byl úspěšně proveden. Je možné oznámit úspěšné vytvoření souborů nebo zobrazit widget pro jejich stažení.

• create_id

  ID generování. Pouze při úspěšném dokončení požadavku. Může být užitečné pro další požadavky k API.

• files

  Pole obsahující ID vytvořených souborů. Pouze při úspěšném dokončení požadavku. Pro stažení souboru ve formátu JPG otevřete https://dimaker.app/getfile/{ID}/. Pro PDF použijte variantu pdf/. Před dokončením vytvoření souboru vrátí API chybu 404. Připravit soubor může trvat mezi 1 až 5 sekundami.

• url

  URL řetězec pro zobrazení widgetu stažení souborů. Pouze při úspěšném dokončení požadavku. Pro správné získání souboru je vytvořte Iframe s tímto URL. Prostý přechod na URL nebude fungovat. Doména musí být uvedena v nastavení API. Pro modalní zobrazení přidejte parametr ?view=modal.

• error_text

  Pouze při chybě. Popis chyby. Možné chyby zahrnují neplatný Secure token, masku pro nahrazení, ID dokumentu, šablony e-mailu, ID složky nebo interní chybu serveru.

Další integrace