API
Використовуючи API DiMaker можна створювати файли з персональними даними та за необхідності віддавати їх отримувачам. Запроси до API можуть відбуватися як з іншого сервера, так і з браузера через CORS запит.
З чого почати
У розділі «Інтеграція» - «Токени API» необхідно отримати Secure токен для запитів і дозволити його використання. Крім того, потрібно створити документ, що містить змінні для персональних даних, а також шаблон листа для розсилки по електронній пошті і папку в Диску для готових файлів.
Створення файлів
Для створення файлів необхідно відправляти Data-POST або 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
Час, коли відправляти
Результат
У результаті сервер поверне 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, то в це місце будуть додані всі дані файлу у вигляді таблиці.
Інші інтеграції
-