 API

Using the DiMaker API, you can create files with personal data and distribute them to recipients as needed. API calls can originate from another server or from a browser via CORS request.

Getting Started

In the "Integration" - "API Tokens" section, obtain a Secure token for requests and authorize its usage. Additionally, create a document containing variables for personal data, an email template for mailings, and a folder in Disk for finished files.

Creating Files

To create files, send POST-DATA, POST-JSON, or GET requests to the address
https://dimaker.app/api/v1/create/
with the data specified below.
Request encoding is UTF-8. Mandatory fields are marked with an asterisk.

• secure*

  Token (string, 36 characters)

• doc_id*

  Document ID (string, 36 characters) used for file creation. The ID can be obtained from the address bar when the document is open. The document should not be in the trash, but can reside in any folder within Documents.

• mask*

  JSON string containing all variables for replacement as key (variable) - value (replacement text). Can include data for creating multiple files (no limit on quantity).
  Example for a single file:
  [{"%name": "Ivanov", "%points":"100"}]
  Example for multiple files:
  [{"%name": "Ivanov", "%points":"100"}, {"%name": "Petrov", "%points":"200"}, {"%name": "Sidorov", "%points":"300"}]
  To specify an email address, use %email; for file name, use %filename. To send created files to multiple email addresses, list them separated by commas. The sending status on Disk will display the first address.
  Only double quotation marks are allowed according to the standard. If the value of the key contains quotes, they should be escaped.

  To insert an image into an image block, use either a direct link (http:// or https://) or a Base64 encoded image. In the latter case, the string must start with "data:image/".

  Alternative Method
  If sending a JSON string is not feasible, replacement strings can be sent as request fields. Each replacement variable should start with the prefix mask_, for example mask_name, and contain the value to be replaced. In the document, the variable will be searched for after the prefix. For instance, mask_name corresponds to %name. To specify an email address in this case, use mask_email; for file name, use mask_filename.

• mail_id

  Email template ID (string, 36 characters) for sending emails. The ID can be obtained from the address bar when the template is open. If the variable is not provided, no email will be sent.

• email_send

  Time to send the email with the file. Can take the following values:
  onfinish - Send all emails after all files are created (default)
  oncreate - Send emails immediately after file creation. For single file creation, onfinish and oncreate are the same.
  timeout - Send emails after a time interval. In this case, two additional parameters must be provided:
  email_timeout_value - numerical value of the interval, indicating when to send emails, integer
  email_timeout_unit - unit of the interval. Can be "m" (minutes), "h" (hours), "d" (days).
  Alternatively, to specify an exact send time, provide the time in unix time format in email_timeout_timestamp. If both email_timeout_value and email_timeout_timestamp are provided, the latter takes precedence.

• folder_id

  Disk folder ID (string, 36 characters) for saving files. If the folder does not exist, it will be automatically created when the first file is created.

• storage_period

  Duration for file storage on Disk. If not specified, files are stored indefinitely until manually deleted. To delete after a time interval, set the value to:
  timeout. In this case, two additional parameters must be provided:
     storage_period_timeout_value - numerical value of the interval specifying when to delete files, integer
     storage_period_timeout_unit - unit of the interval. Can be "m" (minutes), "h" (hours), "d" (days).
  Alternatively, to specify an exact deletion time, provide the time in unix time format in storage_period_timeout_timestamp. If both storage_period_timeout_value and email_timeout_timestamp are provided, the latter takes precedence.

• page_id

  Sheet number (number or string), if the document has multiple sheets. You can provide a single number (first sheet - 0), or a list of sheet numbers (comma-separated) used for file creation.

• result

  Determines the format of the returned result. Can take the following values:

  • No value. A JSON string with the request result will be returned (see below)
  • link. On a successful request, a string containing a link to the created file will be returned (if multiple files were created in the request, the link to the first one). To access the file, follow the provided link. Preparing the files takes time - 1 to 5 seconds per file. Before the file is created, the request to this address returns a 404 error. If the request did not result in file creation, a JSON string with an error is returned (see below).
  • file. On a successful request, the ready-to-use file will be returned (if multiple files were created in the request, only the first one). Since file creation takes 1-5 seconds, the return occurs only after the file is created. With a high volume of API requests, the file creation time may be extended. If the file is not ready within 30 seconds, the API returns a 404 error (although the file creation request will eventually be processed). If the request did not result in file creation, a JSON string with an error is returned (see below). If more than 1 request is expected per 5 seconds to the API, this option should not be used.

Result

The server will return a JSON string with possible values:

• result

  Request result. Can take the following values:
  error - request error. Files not created.
  success - successful file creation request. Depending on the API usage scenario, you can notify of successful file creation or display a form to obtain files.

• create_id

  Generation ID. Only for successful requests. May be useful for other API requests.

• files

  An array containing the IDs of created files. Only for successful requests. To obtain the actual file in JPG format, access https://dimaker.app/getfile/{ID}/. To download a PDF file, add pdf/ to the address. The API returns the file ID immediately, but preparing the files takes time - 1 to 5 seconds per file. Before the file is created, the request to https://dimaker.app/getfile/{ID}/ returns a 404 error.

• url

  URL string for the file download widget. Only for successful requests. Create an Iframe with the specified URL. Simply navigating to the URL yields no result. The domain of the site where the file is received must be correctly specified in the API settings.
  Each file creation takes 1 second + a few seconds to process the entire group. Immediately after sending the request, the Iframe with the specified URL can be opened. If file creation is not yet completed, an appropriate message will be displayed. Once the files are ready, they will be offered for download.
  A download widget can be displayed in a modal dialog on top of the page. For this, create an Iframe with the following additional styles: position:fixed; width:100%; height:100%; top:0; bottom:0; right:0; left:0; z-index:10000; background: rgb(0 0 0 / 72%); Append ?view=modal to the URL. Place this iframe in the body.

• error_text

  Only on error. Textual error description. Possible errors: incorrect Secure token, replacement mask, document ID, email template ID, Disk folder ID, or internal server error.

Example of returned data for a successful request:
{
"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"
]
}

Creating Multiple Files in a Single Request

In one request, you can send a request to create multiple files from different documents. With such a request, you can create several files, for example, using templates in both Russian and English. By sending a single request, the server will create the necessary number of files.

To send such a request, the doc_id variable must be an array (variable name - doc_id[]). In this case, one request may contain multiple doc_id[] variables for creating several files. Other variables, such as mail_id, email_send, folder_id, can also be sent as arrays, so each file is sent with a specific template, at a specific time, or saved in a specific folder. If there is no such necessity, only the doc_id field should be an array.

For example, to create two files from different documents and place them in different Disk folders, two doc_id[] variables and two folder_id[] variables (in the same order) should be sent. Moreover, if there is a task to send them in a single email, specify one mail_id, and in email_send[], first indicate "manual", then "oncreate". In this scenario first one file will be created, then the other. Only after creating the second, mail with the specified mail_id will be sent.

Send File to Yourself After Creation

The file will be sent to the account's email immediately after creation. In the "Email Template" field, you can choose which template to use for sending. You can create a separate template for sending emails to the account's email address in Email Templates. If you include the %data variable in the email text, the file data will be added as a table at that position.

Deleting Files

To delete files, send POST-DATA, POST-JSON, or GET requests to the address
https://dimaker.app/api/v1/drive/files/delete/
with the data specified below.
Request encoding is UTF-8. Mandatory fields are marked with an asterisk.

• secure*

  Token (string, 36 characters)

• file_id

  File ID (string, 36 characters) to be deleted. The file ID is returned in the files array upon creation through the API. The file should not be in the trash.

  OR

• file_ids

  An array of file IDs (string, 36 characters) to be deleted when multiple files need to be removed in one request.

  OR

• creater_id

  Generation ID (string, 36 characters) if the file was created via API. The generation ID can be used instead of file_id or file_ids, resulting in all files with the specified generation ID being deleted. The generation ID is returned in the create_id field when files are created via the API.

  delete_forever

  Specifies whether the file should be permanently deleted without moving to the trash. By default, the file is moved to the trash. The value can be:

  • 0 - move to trash (default)
  • 1 - permanently delete

  Files in the trash are automatically deleted 60 days after being moved there.

Example

Example of a correct request for file deletion:
{
"secure":"b4caf05b-6757-4d9c-b4bc-1924a9b31796",
"file_id":"369dc61e-40c2-46c0-81f4-e31ca8c33cc2"
}

Result

The server will return a JSON string with possible values:

• result

  Request result. Can take the following values:
  error - request error. Files not deleted.
  success - successful request for file deletion.

• files

  An array containing the IDs of deleted files. Only for successful requests.

• error_text

  Only on error. Textual error description. Possible errors: incorrect Secure token, file ID, generation ID, or internal server error.

Example of returned data for a successful request:
{
"result":"success",
"files":["369dc61e-40c2-46c0-81f4-e31ca8c33cc2"]
}

---

Other Integrations