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-строка, що містить всі змінні для заміни у вигляді ключ (змінна) - значення (текст для заміни). Може містити дані для створення декількох файлів (без обмежень на кількість).
Приклад для одного файлу:
[{"%фіо": "Іванов", "%бали":"100"}]
Приклад для декількох файлів:
[{"%фіо": "Іванов", "%бали":"100"}, {"%фіо": "Петров", "%бали":"200"}, {"%фіо": "Сидоров", "%бали":"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_value - одиниця виміру проміжку. Може приймати значення "m" (хвилини), "h" (години), "d" (дні).
Або, для вказання точного часу відправки, необхідно передати час у форматі unix time в email_timeout_timestamp. Якщо передано timeout і email_timeout_timestamp, то пріоритет буде у останньої. -
folder_id
ID папки в Диску (строка, 36 символів) збереження файлів. Якщо папки немає, то вона буде створена автоматично при створенні першого файлу.
-
page_id
Порядковий номер аркуша (число або строка), якщо в документі є декілька аркушів. Можна передати один номер ( перший аркуш - 0), або номера (через кому) аркушів, які необхідно використовувати для створення файлу.
-
result
Визначає у якому вигляді повертати результат. Може приймати значення:
- Значення відсутнє. Буде повернена JSON-строка з результатом звернення (див. нижче)
- link. При успішному зверненні буде повернена строка, що містить посилання на створений файл (якщо в зверненні було створення декількох файлів, то посилання на перший). Для отримання самого файлу необхідно звернутись за вказаним посиланням. На підготовку самих файлів потрібен час - від 1 до 5 секунд на кожен файл. Поки файл не буде створений, звернення за цією адресою буде виводити помилку 404. Якщо звернення не призвело до створення файлу, буде повернена JSON строка з помилкою (див. нижче).
- file. При успішному зверненні буде повернений сам готовий файл (якщо в зверненні було створення декількох файлів, то лише перший). Оскільки створення файлу займає 1-5 секунд, то повернення відбудеться лише після того, як файл буде створений. При великій кількості звернень до API час створення файлу буде збільшено. Якщо файл не буде підготовлений за 30 секунд, то API поверне помилку 404 (хоча звернення до створення файлу в кінцевому підсумку буде виконано). Якщо очікується, що звернень до 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"]
}