 API

Dokumentace byla přeložena automaticky pomocí strojového učení.

S využitím API DiMaker lze vytvářet soubory s osobními údaji a podle potřeby je doručovat příjemcům. API dotazy mohou probíhat jak z jiného serveru, tak z prohlížeče prostřednictvím CORS dotazů.

Jak začít

V sekci „Integrace“ - „API Tokens“ je potřeba získat Secure token pro dotazy a povolit jeho použití. Kromě toho je nutné vytvořit dokument obsahující proměnné pro osobní údaje, šablonu e-mailu pro odesílaní a složku na Disku pro hotové soubory.

Vytváření souborů

Pro vytvoření souborů je nutné zaslat POST-DATA, POST-JSON nebo GET dotaz na adresu
https://dimaker.app/api/v1/create/
s uvedenými níže daty.
Kódování dotazu je 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 lze získat v adresním řádku, když je dokument otevřen. Dokument by neměl být v koši, ale může být v jakékoli složce Dokumentů.
mask*

JSON řetězec obsahující všechny proměnné pro náhradu ve formátu klíč (proměnná) - hodnota (text pro náhradu). Může obsahovat data pro vytvoření několika souborů (bez omezení na počet).
Příklad pro jeden soubor:
[{"%name": "Novák", "%body":"100"}]
Příklad pro několika soubory:
[{"%name": "Novák", "%body":"100"}, {"%name": "Dvořák", "%body":"200"}, {"%name": "Svoboda", "%body":"300"}]
Pro určení emailové adresy musíte použít %email, pro jméno souboru %filename. Pro zaslání vytvořených souborů na několik e-mailových adres je potřeba je uvést čárkou oddělené. Přitom stav odeslání na Disku bude zobrazován podle první adresy.
Lze použít pouze dvojité uvozovky v souladu se standardem. Pokud hodnota klíče obsahuje uvozovky, musí být eskapovány.

Pro přenos obrázku do bloku s obrázkem lze použít buď přímý odkaz (http:// nebo https://), nebo obrázek zakódovaný v Base64. V druhém případě by měl řetězec začínat "data:image/".

Alternativní způsob
Pokud není možné poslat JSON řetězec, řetězce pro náhradu lze poslat jako pole dotazu. Každá proměnná pro náhradu by měla začínat prefixem mask_, například mask_name a obsahovat hodnotu pro náhradu. V dokumentu se pak uskuteční hledání proměnné podle prefixu. Například do pole mask_name odpovídá proměnná %name. Pro určení e-mailové adresy v tomto případě musíte použít mask_email, a jméno souboru - mask_filename.
mail_id

ID šablony e-mailu (řetězec, 36 znaků) pro zaslání emailem. ID lze získat v adresním řádku, když je šablona otevřena. Pokud proměnná není předána, e-mail nebude zaslán.
email_send

Čas, kdy poslat e-mail se souborem. Může přijímat následující hodnoty:
onfinish - Odeslat všechny e-maily po vytvoření všech souborů (výchozí)
oncreate - Odeslat e-maily ihned po vytvoření souboru. Při vytváření jednoho souboru jsou onfinish a oncreate identické.
timeout - Odeslat e-maily po uplynutí doby. V tomto případě musíte zadat ještě dva parametry:
email_timeout_value - číselná hodnota intervalu, po kterém poslat e-maily, celé číslo
email_timeout_unit - jednotka měření intervalu. Může být ve formátu "m" (minuty), "h" (hodiny), "d" (dny).
Nebo, pro určení přesného času odeslání, čas ve formátu unix time ve email_timeout_timestamp. Pokud jsou předány email_timeout_value a email_timeout_timestamp, priorita bude na poslední.
folder_id

ID složky na Disku (řetězec, 36 znaků) pro uložení souborů. Pokud složka neexistuje, bude automaticky vytvořena při vytváření prvního souboru.
storage_period

Doba uchovávání souborů na Disku. Pokud není parametr uveden, soubory se ukládají bez omezení, dokud nejsou ručně smazány. Pro smazání po určité době by mělo obsahovat hodnotu:
timeout. V tomto případě je nutné zadat ještě dva parametry:
storage_period_timeout_value - číselná hodnota intervalu, po kterém smazat soubory, celé číslo
storage_period_timeout_unit - jednotka měření intervalu. Může být ve formátu "m" (minuty), "h" (hodiny), "d" (dny).
Nebo, pro určení přesného času smazání, čas ve formátu unix time ve storage_period_timeout_timestamp. Pokud jsou předány storage_period_timeout_value a email_timeout_timestamp, priorita bude na poslední.
page_id

Pořadové číslo listu (číslo nebo řetězec), pokud dokument obsahuje několik listů. Můžete poslat jedno číslo (první list - 0) nebo čísla (oddělená čárkou) listů, které chcete použít pro vytvoření souboru.
result

Určuje, jakým způsobem vrátit výsledek. Může mít následující hodnoty:
- Žádná hodnota. Bude vrácen JSON řetězec s výsledkem dotazu (viz níže)
- link. Při úspěšném dotazu bude vrácen řetězec obsahující odkaz na vytvořený soubor (pokud bylo v dotazu uvedeno vytvoření několika souborů, pak odkaz na první). Pro získání samotného souboru musíte přejít na uvedený odkaz. Příprava samotných souborů zabere čas - od 1 do 5 sekund na každý soubor. Před vytvořením souboru bude dotaz na tuto adresu vracet chybu 404. Pokud dotaz nevedl k vytvoření souboru, bude vrácen JSON řetězec s chybou (viz níže).
- file. Při úspěšném dotazu bude vrácen hotový soubor (pokud bylo v dotazu uvedeno vytvoření několika souborů, pak jen první). Vzhledem k tomu, že vytvoření souboru trvá 1-5 sekund, návrat se uskuteční až poté, co bude soubor vytvořen. Při velkém množství dotazů na API se čas vytvoření souboru prodlouží. Pokud nebude soubor připraven do 30 sekund, API vrátí chybu 404 (i když samotný dotaz na vytvoření souboru nakonec bude vykonán). Pokud dotaz nevedl k vytvoření souboru, bude vrácen JSON řetězec s chybou (viz níže). Pokud se očekává, že by dotazů k API mělo být více než 1 dotaz za 5 sekund, není vhodné tento parametr používat.

Výsledek

Server vrátí JSON řetězec s následujícími možnými hodnotami:

result

Výsledek dotazu. Může přijímat následující hodnoty:
error - chyba dotazu. Soubory nebyly vytvořeny.
success - úspěšný dotaz na vytvoření souborů. V závislosti na užívání API můžete informovat o úspěšném vytvoření souborů nebo zobrazit formulář pro získání souborů.
create_id

ID generace. Pouze při úspěšném provedení dotazu. Může být užitečné pro další dotazy na API.
files

Pole obsahující ID vytvořených souborů. Pouze při úspěšném provedení dotazu. Pro získání samotného souboru ve formátu JPG je třeba se obrátit na https://dimaker.app/getfile/{ID}/. Pro stažení PDF souboru je třeba přidat k adrese pdf/. API vrací ID souboru ihned, ale příprava samotných souborů zabere čas - od 1 do 5 sekund na každý soubor. Před vytvořením souboru bude dotaz na https://dimaker.app/getfile/{ID}/ vracet chybu 404.
url

URL řetězec pro zobrazení widgetu stahování souborů. Pouze při úspěšném provedení dotazu. Je třeba vytvořit Iframe s uvedeným URL. Pouhý přechod na URL nepřinese výsledek. Doména webu, na kterém dochází k získávání souboru, musí být správně uvedena v nastavení API.
Vytvoření každého souboru trvá 1 sekundu + několik sekund na zpracování celé skupiny. Ihned po odeslání dotazu můžete otevřít Iframe s uvedenými URL. Pokud ještě nedošlo k vytvoření souborů, zobrazí se odpovídající zpráva. Jakmile jsou soubory připraveny, budou nabídnuty ke stažení.
Widget stahování můžete zobrazit v dialogovém okně nad stránkou. K tomu je třeba vytvořit Iframe s následujícími dodatečnými styly: position:fixed; width:100%; height:100%; top:0; bottom:0; right:0; left:0; z-index:10000; background: rgb(0 0 0 / 72%); K adresnímu řádku je třeba přidat ?view=modal. A umístit tento iframe do body.
error_text

Pouze při chybě. Textový popis chyby. Možné chyby: nesprávný Secure token, maska pro náhradu, ID dokumentu, ID šablony e-mailu, ID složky na Disku, nebo interní chyba serveru.

Příklad vrácených dat při úspěšném dotazu:
{
"result":"success",
"create_id":"b4caf05b-6757-4d9c-b4bc-1924a9b31796",
"url":"https://embed.dimaker.app/widgets/get/927ebf68-2f55-4b20-a18c-c1171ee113db/b4caf05b-6757-4d9c-b4bc-1924a9b31796/",
"files":[
"369dc61e-40c2-46c0-81f4-e31ca8c33cc2",
"d94c6efb-0076-438b-bb84-fead9c1ae556",
"716e1081-c8ee-442b-b0b0-0681b2ed5d90"
]
}

Vytvoření více souborů v jednom dotazu

V jednom dotazu můžete zaslat žádost o vytvoření více souborů z různých dokumentů. Pomocí takového dotazu je možné vytvořit více souborů, například s použitím šablon v českém a anglickém jazyce. Při zaslání jednoho dotazu server vytvoří potřebný počet souborů.

Pro zaslání takového dotazu musí být proměnná doc_id polem (název proměnné - doc_id[]). V takovém případě může být v jednom dotazu několik proměnných doc_id[] - pro vytvoření více souborů. Další proměnné, jako jsou mail_id, email_send, folder_id, mohou být také odeslány jako pole, aby každý soubor byl odeslán s konkrétní šablonou, v konkrétní čas nebo uložen ve specifické složce. Pokud to není nutné, mělo by být jako pole pouze pole doc_id.

Například je nutné vytvořit dva soubory z různých dokumentů a uložit je do různých složek na Discu. K tomu je nutné zaslat dvě proměnné doc_id[] a dvě proměnné folder_id[] (ve stejném pořadí). Navíc, pokud je úkolem zaslat je jediným e-mailem, je třeba zadat jedno mail_id a v email_send[] nejprve uvést "manual" a poté "oncreate". V tomto případě se nejprve vytvoří jeden soubor, poté druhý. A až po vytvoření druhého dojde k odeslání s e-mailem uvedeným v mail_id.

Odesílání souboru na svou emailovou adresu po vytvoření

Soubor bude odeslán na e-mailovou adresu účtu ihned po vytvoření. V poli „Šablona e-mailu“ lze vybrat, jakou šablonu použít pro odeslání. Předem je možné v „Šablony e-mailů“ vytvořit zvláštní šablonu pro zasílání e-mailů na adresu účtu. Pokud do textu e-mailu napíšete proměnnou %data, budou na toto místo přidána všechna data souboru jako tabulka.

Vymazání souborů

Pro vymazání souborů je nutné zaslat POST-DATA, POST-JSON nebo GET dotazy na adresu
https://dimaker.app/api/v1/drive/files/delete/
s uvedenými níže daty.
Kódování dotazu je UTF-8. Povinná pole jsou označena hvězdičkou.

secure*

Token (řetězec, 36 znaků)
file_id

ID souboru (řetězec, 36 znaků), který bude odstraněn. ID souboru je vráceno v poli files při vytváření přes API. Soubor by neměl být v koši.

NEBO
file_ids

Pole ID souborů (řetězec, 36 znaků), které budou odstraněny, pokud je třeba odstranit několik souborů v jednom dotazu.

NEBO
creater_id

ID generace (řetězec, 36 znaků), pokud byl soubor vytvořen přes API. ID generace lze předat místo file_id nebo file_ids. V tomto případě budou odstraněny všechny soubory s tímto ID generace. ID generace je vráceno v poli create_id při vytváření souborů přes API.

delete_forever

Mělo by být soubor odstraněn trvale, bez přesunu do koše. Ve výchozím nastavení soubor přechází do koše. Může přijímat hodnoty:
- 0 - přesunout do koše (ve výchozím nastavení)
- 1 - odstranit trvale
Soubory z koše jsou automaticky vymazány po 60 dnech od přesunu do koše.

Příklad

Příklad správného dotazu na odstranění souborů:
{
"secure":"b4caf05b-6757-4d9c-b4bc-1924a9b31796",
"file_id":"369dc61e-40c2-46c0-81f4-e31ca8c33cc2"
}

Výsledek

Server vrátí JSON řetězec s následujícími možnými hodnotami:

result

Výsledek dotazu. Může přijímat následující hodnoty:
error - chyba dotazu. Soubory nebyly odstraněny.
success - úspěšný dotaz na odstranění souborů.
files

Pole obsahující ID odstraněných souborů. Pouze při úspěšném provedení dotazu.
error_text

Pouze při chybě. Textový popis chyby. Možné chyby: nesprávný Secure token, ID souboru, ID generace, nebo interní chyba serveru.

Příklad vrácených dat při úspěšném dotazu:
{
"result":"success",
"files":["369dc61e-40c2-46c0-81f4-e31ca8c33cc2"]
}

Další integrace

Integrace s Google Sheets Formulář pro tvorbu Integrace přes API Integrace s GetCourse Integrace s TypeForm

Připraveni začít?

Otevřít Otevřít webovou aplikaci