API
За допомогою API DiMaker можна створювати файли з персональними даними та, за потреби, передавати їх отримувачам. Запити до API можуть відправлятися як з іншого сервера, так і з браузера за допомогою CORS-запитів.
З чого почати
У розділі «Інтеграція» - «Токени API» потрібно отримати Secure токен для запитів і дозволити його використання. Крім цього, необхідно створити документ, що містить змінні для персональних даних, а також шаблон листа для розсилки електронною поштою і папку в Диску для готових файлів.
Створення файлів
Для створення файлів потрібно надсилати POST-DATA, POST- або GET-запити на адресу
https://dimaker.app/api/v1/create/
із зазначеними нижче даними.
Кодування запиту – UTF-8. Обов'язкові поля позначені зірочкою.
-
secure*
Токен (строка, 36 символів)
-
doc_id*
ID документа (строка, 36 символів), який буде використано для створення файлу. ID можна отримати в адресному рядку, коли документ відкрито. Документ не повинен бути в кошику, але може зберігатися в будь-якій папці Документів.
-
mask*
-рядок, що містить усі змінні для заміни у вигляді ключ (змінна) - значення (текст для заміни). Може містити дані для створення кількох файлів (без обмежень на кількість).
Приклад для одного файлу:
[{"%name": "Іванов", "%бали":"100"}]
Приклад для кількох файлів:
[{"%name": "Іванов", "%бали":"100"}, {"%name": "Петров", "%бали":"200"}, {"%name": "Сидоров", "%бали":"300"}]
Для вказання електронної пошти використовуйте %email, для імені файлу – %filename. Для відправлення створених файлів на кілька адрес електронної пошти їх потрібно перелічити через кому. У цьому випадку статус відправлення в Диску буде відображатися за першим адресом.
Використовувати потрібно лише подвійні лапки згідно зі стандартом. Якщо значення ключа містить лапки, вони повинні бути екрановані.Для передачі зображення в блок із картинкою можна використовувати або пряме посилання (http:// або https://), або закодоване в Base64 зображення. У другому випадку рядок має починатися з "data:image/".
Альтернативний метод
Якщо немає можливості передати -рядок, то дані для заміни можна передати як окремі поля запиту. Кожна змінна повинна починатися з префікса 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. Якщо передані параметри timeout і email_timeout_timestamp, то пріоритет буде у останнього. -
folder_id
ID папки в Диску (строка, 36 символів), для збереження файлів. Якщо папки немає, вона створиться автоматично при створенні першого файлу.
-
page_id
Номер сторінки (число або рядок), якщо в документі кілька сторінок. Можна передати один номер (перша сторінка - 0), або номери (через кому) сторінок, які потрібно використовувати для створення файлу.
-
result
Визначає, у якому вигляді повертати результат. Може приймати значення:
- Значення відсутнє. Повернеться -рядок із результатом запиту (див. нижче)
- link. У разі успішного запиту повернеться рядок із посиланням на створений файл (якщо запит стосувався створення кількох файлів, то посилання на перший). Для отримання самого файлу потрібно звернутися за вказаним посиланням. На підготовку файлів потрібно від 1 до 5 секунд. Поки файл не буде створено, запит на цю адресу повертатиме помилку 404. Якщо запит не призвів до створення файлу, повернеться -рядок із помилкою.
- file. У разі успішного запиту повернеться готовий файл (якщо запит стосувався створення кількох файлів, то тільки перший). Оскільки створення файлу займає 1-5 секунд, повернення відбудеться лише після створення файлу. За великої кількості запитів час створення файлу може збільшитися. Якщо файл не буде готовий за 30 секунд, API поверне помилку 404 (хоча сам запит на створення файлу буде виконаний). Якщо очікується, що запитів буде більше ніж 1 на 5 секунд, не слід використовувати цей параметр.