 API

Выкарыстоўваючы API DiMaker можна ствараць файлы з персанальнымі дадзенымі і пры неабходнасці перадаваць іх атрымальнікам. Запыты да API могуць адбывацца як з іншага сервера, так і з браўзера праз CORS запыт.

З чаго пачаць

У раздзеле «Інтэграцыя» - «Токены API» трэба атрымаць Secure токен для запытаў і дазволіць выкарыстоўваць гэты токен. Акрамя таго, неабходна стварыць дакумент, які змяшчае зменныя для персанальных дадзеных, а таксама шаблон ліста для рассылкі па электроннай пошце і тэчку ў Дыску для гатовымі файламі.

Стварэнне файлаў

Для стварэння файлаў неабходна адпраўляць POST-DATA, POST-JSON або GET запыты на адрас
https://dimaker.app/api/v1/create/
з указанымі ніжэй дадзенымі.
Кадзіроўка запыту - UTF-8. Абавязковыя палі пазначаны зорачкай.

• secure*

  Токен (радок, 36 сімвалаў)

• doc_id*

  ID дакумента (радок, 36 сімвалаў), які будзе выкарыстоўвацца для стварэння файла. ID можна атрымаць у адрасным радку, калі дакумент адкрыты. Дакумент не павінен быць у кошыку, але можа знаходзіцца ў любой тэчцы Дакументаў.

• mask*

  JSON-радок, якая змяшчае ўсе зменныя для замены ў выглядзе ключ (зменная) - значэнне (тэкст для замены). Можа ўтрымліваць дадзеныя для стварэння некалькіх файлаў (без абмежаванняў на колькасць).
  Прыклад для аднаго файла:
  [{"%name": "Іваноў", "%балы":"100"}]
  Прыклад для некалькіх файлаў:
  [{"%name": "Іваноў", "%балы":"100"}, {"%name": "Пятроў", "%балы":"200"}, {"%name": "Сідараў", "%балы":"300"}]
  Для ўказання адрасу электроннай пошты трэба выкарыстоўваць %email, імя файла - %filename. Для адпраўкі створаных файлаў на некалькі адрасоў электроннай пошты трэба ўказаць іх праз коску. Пры гэтым статус адпраўкі ў Дыску будзе адлюстроўвацца па першым адрасу.
  Можна выкарыстоўваць толькі двайныя двукоссі ў адпаведнасці са стандартам. Калі значэнне ключа ўтрымлівае двукоссі, то яны павінны быць экаўзадаронены.

  Для перадачы выявы ў блок з выявай можна выкарыстоўваць альбо прамую спасылку (http:// або https://), альбо закодаванае ў Base64 выява. У другім выпадку радок павінен пачынацца з "data:image/".

  Альтэрнатыўны метад
  Калі адправіць JSON-радок не магчыма, то радкі для замены можна адправіць як поля запыту. Кожная зменная для замены павінна пачынацца з прэфікса mask_, напрыклад mask_name і ўтрымліваць значэнне для замены. Пры гэтым у дакуменце будзе ажыццёўлены пошук зменнай пасля прэфікса. Напрыклад, полю mask_name адпавядае зменная %name. Для ўказання адрасу электроннай пошты ў гэтым выпадку трэба выкарыстоўваць mask_email, а імя файла - mask_filename.

• mail_id

  ID шаблона ліста (радок, 36 сімвалаў) для адпраўкі па электроннай пошце. ID можна атрымаць у адрасным радку, калі шаблон адкрыты. Калі зменная не перададзена, то ліст не будзе адпраўлена.

• email_send

  Час, калі адпраўляць ліст з файлам. Можа прымаць наступныя значэнні:
  onfinish - Разаслаць усе лісты пасля стварэння ўсіх файлаў (па-змаўчанні)
  oncreate - Адпраўляць лісты адразу ж пасля стварэння файла. Пры стварэнні аднаго файла onfinish і oncreate ідэнтычныя.
  timeout - Разаслаць лісты праз прамежак часу. У гэтым выпадку неабходна перадаць яшчэ два параметра:
  email_timeout_value - лічбавае значэнне прамежку, праз які адпраўляць лісты, цэлае значэнне
  email_timeout_unit - адзінка вымярэння прамежку. Можа прымаць значэнне "m" (хвіліны), "h" (гадзіны), "d" (дні).
  Альбо, для ўказання дакладнага часу адпраўкі, трэба перадаць час у фармаце unix time у email_timeout_timestamp. Калі перададзены email_timeout_value і email_timeout_timestamp, то прыярытэт будзе ў апошняга.

• folder_id

  ID тэчкі ў Дыску (радок, 36 сімвалаў) захавання файлаў. Калі тэчкі няма, то яна будзе створана аўтаматычна пры стварэнні першага файла.

• storage_period

  Час захоўвання файлаў на Дыску. Калі параметр не ўказаны, то файлы захоўваюцца бестэрмінова, да выдалення ўручную. Для выдалення праз прамежак часу павінен прыняць значэнне:
  timeout. У гэтым выпадку неабходна перадаць яшчэ два параметра:
     storage_period_timeout_value - лічбавае значэнне прамежку, праз які выдаліць файлы, цэлае значэнне
     storage_period_timeout_unit - адзінка вымярэння прамежку. Можа прымаць значэнне "m" (хвіліны), "h" (гадзіны), "d" (дні).
  Альбо, для ўказання дакладнага часу выдалення, трэба перадаць час у фармаце unix time у storage_period_timeout_timestamp. Калі перададзены storage_period_timeout_value і email_timeout_timestamp, то прыярытэт будзе ў апошняга.

• page_id

  Парадавы нумар ліста (лічба або радок), калі ў дакуменце ёсць некалькі лістаў. Можна перадаць адзін нумар (першы ліст - 0), або нумары (праз коску) лістаў, якія трэба выкарыстоўваць для стварэння файла.

• result

  Вызначае ў якім выглядзе вяртаць вынік. Можа прымать значэнні:

  • Значэнне адсутнічае. Будзе вернута JSON-радок з вынікам запыту (глядзі ніжэй)
  • link. Пры паспяховым запыце будзе вернута радок, якая змяшчае спасылку на створаны файл (калі ў запыце было стварэнне некалькіх файлаў, то спасылку на першы). Для атрымання самога файла трэба звернуцца па ўказанай спасылцы. На падрыхтоўку саміх файлаў патрабуецца час - ад 1 да 5 секунд на кожны файл. Да таго, як файл будзе створаны, запыт па гэтым адрасе будзе вяртаць памылку 404. Калі запыт не прывёў да стварэння файла, то будзе вернута JSON радок з памылкай (глядзі ніжэй).
  • file. Пры паспяховым запыце будзе вернуты сам гатовы файл (калі ў запыце было стварэнне некалькіх файлаў, то толькі першы). Так як стварэнне файла зойме 1-5 секунд, то вяртанне адбудзецца толькі пасля таго, як файл будзе створаны. Пры вялікай колькасці запытаў да API час стварэння файла будзе павялічаны. Калі файл не будзе падрыхтаваны за 30 секунд, то API верне памылку 404 (хаця сам запыт на стварэнне файла ў канчатковым выніку будзе выкананы). Калі запыт не прывёў да стварэння файла, то будзе вернута JSON радок з памылкай (глядзі ніжэй). Калі чакаецца, што запытаў да API будзе больш, чым 1 запыт у 5 секунд, то не варта выкарыстоўваць гэты параметр.

Вынік

У рэшце рэшт сервер верне JSON-радок, якая прыме наступныя магчымыя значэнні:

• result

  Вынік запыту. Можа прымать наступныя значэнні:
  error - памылка запыту. Файлы не створаны.
  success - паспяховы запыт на стварэнне файлаў. У залежнасці ад сцэнара выкарыстання API можна паведаміць аб паспяховым стварэнні файлаў або вывесці форму атрымання файлаў.

• create_id

  ID генерацыі. Толькі пры паспяховым выкананні запыту. Можа спатрэбіцца для іншых запытаў да API.

• files

  Масіў, які змяшчае ID створаных файлаў. Толькі пры паспяховым выкананні запыту. Для атрымання самога файла ў фармаце JPG неабходна звярнуцца да https://dimaker.app/getfile/{ID}/. Для загрузкі PDF файла трэба дадаць да адрасу pdf/. API вяртае ID файла адразу ж, аднак на падрыхтоўку саміх файлаў патрабуецца час - ад 1 да 5 секунд на кожны файл. Да таго, як файл будзе створана, запыт да https://dimaker.app/getfile/{ID}/ будзе вяртаць памылку 404.

• url

  URL радок для вываду віджэта спампоўкі файлаў. Толькі пры паспяховым выкананні запыту. Неабходна стварыць Iframe з указаным URL. Проста пераход па URL не дасць выніку. Дамен сайта, на якім адбываецца атрымання файла, павінен быць карэктна ўказаны ў наладах API.
  Стварэнне кожнага файла займае 1 секунду + некалькі секунд на апрацоўку ўсёй групы. Адразу ж пасля адпраўкі запыту можна адкрываць Iframe з указанымі URL. Калі стварэнне файлаў яшчэ не завершана, то будзе выведзена адпаведнае паведамленне. Як толькі файлы будуць гатовыя, іх будзе прапанавана спампаваць.
  Можна вывесці віджэт спампоўкі ў дыялогавым акне над старонкай. Для гэтага трэба стварыць Iframe з наступнымі дадатковымі стылямі: position:fixed; width:100%; height:100%; top:0; bottom:0; right:0; left:0; z-index:10000; background: rgb(0 0 0 / 72%); Да радка адрасу трэба дадаць ?view=modal. І размясціць гэты iframe у body.

• error_text

  Толькі пры памылцы. Тэкставае апісанне памылкі. Магчымыя памылкі: няправільны Secure токен, маска для замены, ID дакумента, ID шаблону ліста, ID тэчкі ў Дыск, альбо ўнутраная памылка сервера.

Прыклад атрыманых дадзеных пры паспяховым запыце:
{
"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"
]
}

Стварэнне некалькіх файлаў у адным запыце

У адным запыце можна адправіць запыт на стварэнне некалькіх файлаў з розных дакументаў. З дапамогай такога запыту можна стварыць некалькі файлаў, напрыклад, выкарыстоўваючы шаблоны на рускай і англійскай мовах. Адправіўшы адзін запыт, сервер створыць неабходную колькасць файлаў.

Каб адправіць такі запыт, зменная doc_id павінна быць масівам (імя зменнай - doc_id[]). У такім выпадку ў адным запыце можа быць некалькі зменных doc_id[] - для стварэння некалькіх файлаў. Іншыя зменныя, такія як mail_id, email_send, folder_id таксама могуць быць адпраўлены ў выглядзе масіваў, каб кожны з файлаў быў адпраўлены з пэўным шаблонам, у пэўны час або захаваны ў пэўнай тэчцы. Калі ў гэтым няма неабходнасці, то масівам павінна быць толькі поле doc_id.

Напрыклад, неабходна стварыць два файла з розных дакументаў і пакласці іх у розныя тэчкі на Дыску. Для гэтага неабходна адправіць дзве зменныя doc_id[] і дзве зменныя folder_id[] (у тым жа парадку). Акрамя таго, калі ёсць задача адправіць іх адным лістом, то трэба ўказаць адзін mail_id, а ў email_send[] спачатку ўказаць "manual", а затым "oncreate". У гэтым выпадку спачатку будзе створаны адзін файл, потым - другі. І толькі пасля стварэння другога адбудзецца адпраўка з указаным у mail_id лістом.

Адпраўляць сабе файл пасля стварэння

Файл будзе адпраўлены на электронную пошту акаўнта адразу ж пасля таго, як будзе створаны. У полі «Шаблон ліста» можна выбраць, які шаблон выкарыстоўваць для адпраўкі. Папярэдне ў Шаблонах лістоў можна стварыць асобны шаблон для адпраўкі лістоў на электронную пошту акаўнта. Калі ў тэксце ліста напісаць зменную %data, то ў гэтае месца будуць дададзены ўсе дадзеныя файла ў выглядзе табліцы.

Выдаленне файлаў

Для выдалення файлаў неабходна адправіць POST-DATA, POST-JSON або GET запыты на адрас
https://dimaker.app/api/v1/drive/files/delete/
з указанымі ніжэй дадзенымі.
Кадзіроўка запыту - UTF-8. Абавязковыя палі пазначаны зорачкай.

• secure*

  Токен (радок, 36 сімвалаў)

• file_id

  ID файла (радок, 36 сімвалаў), які будзе выдалены. ID файла вяртаецца ў масіве files пры стварэнні праз API. Файл не павінен быць у кошыку.

  АЛЬБО

• file_ids

  Масіў ID файлаў (радок, 36 сімвалаў), якія будуць выдалены, калі патрабуецца выдаліць некалькі файлаў у адным запыце.

  АЛЬБО

• creater_id

  ID генерацыі (радок, 36 сімвалаў), калі файл быў створаны праз API. ID генерацыі можна перадаць замест file_id або file_ids. У гэтым выпадку будуць выдалены ўсе файлы з гэтым ID генерацыі. ID генерацыі вяртаецца ў полі create_id пры стварэнні файлаў праз API.

  delete_forever

  Выдаляць ці файл канчаткова, без перамяшчэння ў кошык. Па-змаўчанні файл перамяшчаецца ў кошык. Можа прымать значэнні:

  • 0 - перамясціць у кошык (па-змаўчанні)
  • 1 - выдаліць канчаткова

  Файлы з кошыка выдаляюцца аўтаматычна праз 60 дзён пасля перамяшчэння ў кошык.

Прыклад

Прыклад карэктнага запыту на выдаленне файлаў:
{
"secure":"b4caf05b-6757-4d9c-b4bc-1924a9b31796",
"file_id":"369dc61e-40c2-46c0-81f4-e31ca8c33cc2"
}

Вынік

У рэшце рэшт сервер верне JSON-радок, якая прыме наступныя магчымыя значэнні:

• result

  Вынік запыту. Можа прымать наступныя значэнні:
  error - памылка запыту. Файлы не выдалены.
  success - паспяховы запыт на выдаленне файлаў.

• files

  Масіў, які змяшчае ID выдаленых файлаў. Толькі пры паспяховым выкананні запыту.

• error_text

  Толькі пры памылцы. Тэкставае апісанне памылкі. Магчымыя памылкі: няправільны Secure токен, ID файла, ID генерацыі, альбо ўнутраная памылка сервера.

Прыклад атрыманых дадзеных пры паспяховым запыце:
{
"result":"success",
"files":["369dc61e-40c2-46c0-81f4-e31ca8c33cc2"]
}

---

Іншыя інтэграцыі