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 символів), які будуть видалені, якщо потрібно видалити кілька файлів в одному запиті.
АБО
create_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"]
}