API
By using the DiMaker API, you can create files with personal data and send them to recipients when necessary. Requests to the API can be made from either another server or browser via CORS requests.
Getting Started
In the "Integration" - "API Tokens" section, you need to obtain a Secure token for requests, and authorize the use of this token. Additionally, you need to create a document containing variables for personal data, a template for email communications, and a folder in the Drive for storing created files.
Creating Files
To create files, you need to send POST-DATA, POST-JSON, or GET requests to the address
https://dimaker.app/api/v1/create/
with the specified data below.
Request encoding - UTF-8. Required fields are marked with an asterisk.
-
secure*
Token (string, 36 characters)
-
doc_id*
Document ID (string, 36 characters) to be used for file creation. ID can be obtained from the address bar when the document is open. The document should not be in the trash, but can be located in any Document folder.
-
mask*
JSON string containing all variables for replacement in the format key (variable) - value (text for replacement). It can contain data for creating multiple files (without limitations on quantity).
Example for a single file:
[{"%name": "John", "%score":"100"}]
Example for multiple files:
[{"%name": "John", "%score":"100"}, {"%name": "Jane", "%score":"200"}, {"%name": "Alice", "%score":"300"}]
To specify an email address, use %email, for filename - %filename. To send created files to multiple email addresses, separate them by comma. The sending status in Drive will be displayed based on the first address.
Double quotes should be used in accordance with the standard. If a key's value contains quotes, they should be escaped.To pass an image to an image block, you can use either a direct link (http:// or https://) or a Base64 encoded image. In the second case, the string should start with "data:image/".
Alternative Method
If it is not possible to send a JSON string, 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 for replacement. In this case, the document will search for variables following the prefix. For instance, the mask_name field corresponds to the %name variable. To specify an email address in this case, use mask_email, for filename - mask_filename. -
mail_id
Email template ID (string, 36 characters) for sending via email. ID can be obtained from the address bar when the template is open. If the variable is not passed, the email will not be sent.
-
email_send
Time to send the email with the file. Possible values:
onfinish - Send all emails after creating all files (default)
oncreate - Send emails immediately after creating the file. When creating one file, onfinish and oncreate are identical.
timeout - Send emails after a time interval. In this case, two additional parameters need to be passed:
email_timeout_value - numerical value of the interval for sending emails, integer value
email_timeout_unit - unit of the interval. Can be "m" (minutes), "h" (hours), "d" (days).
Alternatively, to specify the exact sending time, pass the time in Unix time format in email_timeout_timestamp. If both timeout and email_timeout_timestamp are passed, priority will be given to the latter. -
folder_id
Drive folder ID (string, 36 characters) for saving files. If the folder does not exist, it will be created automatically upon creating the first file.
-
page_id
Sequential number of the sheet (number or string) if the document has multiple sheets. You can pass one number (first sheet - 0), or numbers (comma separated) of sheets to be used for file creation.
-
result
Determines the format to return the result. Possible values:
- Missing Value. A JSON string with the request result will be returned
- link. Upon successful request, a string containing a link to the created file (if multiple files were created, the link to the first one) will be returned. To access the file itself, use the provided link. It takes approximately 1 to 5 seconds to prepare the actual files. Before the file is created, requests to this address will return a 404 error. If the request did not lead to file creation, a JSON string with an error will be returned.
- file. Upon successful request, the completed file will be returned (if multiple files were created, only the first one). Since file creation takes 1-5 seconds, return will occur only after the file is created. With a large number of API requests, the file creation time will increase. If the file is not prepared within 30 seconds, the API will return a 404 error (even though the request to create the file will eventually be executed). If it is expected that there will be more API requests than 1 request in 5 seconds, this parameter should not be used.
Result
As a result, the server will return a JSON string with the following possible values:
-
result
The result of the operation. Can take the following values:
error - operation error. Files are not created.
success - successful operation to create files. Depending on the API usage scenario, you can report the successful creation of files or display a form to get the files. -
create_id
Generation ID. Only in case of successful operation. Can be useful for other API operations.
-
files
An array containing IDs of the created files. Only in case of successful operation. To obtain the actual JPG file, you need to access https://dimaker.app/getfile/{ID}/. To download a PDF file, you need to append pdf/ to the URL. The API returns the file ID immediately, but it takes time to prepare the actual files - from 1 to 5 seconds per file. Before the file is created, accessing https://dimaker.app/getfile/{ID}/ will return a 404 error.
-
url
URL string for displaying the file download widget. Only in case of successful operation. You need to create an Iframe with the specified URL. Simply accessing the URL won't give you the result. The domain of the website where the file is being retrieved must be correctly specified in the API settings.
Creating each file takes 1 second + several seconds to process the entire group. Immediately after sending the request, you can open an Iframe with the specified URL. If the file creation is not yet complete, a corresponding message will be displayed. Once the files are ready, they will be available for download.
You can display the download widget in a modal dialog over the page. To do this, you need to 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%); Add ?view=modal to the URL and place this iframe in the body. -
error_text
Only in case of an error. Text description of the error. Possible errors: incorrect Secure token, replacement mask, document ID, letter template ID, Folder ID in Drive, or internal server error.
Example of returned data in case of a successful operation:
{
"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 One 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 Russian and English. By sending one request, the server will create the required number of files.
To send such a request, the variable doc_id must be an array (variable name - doc_id[]). In this case, there can be several variables doc_id[] in one request - to create multiple files. Other variables, such as mail_id, email_send, folder_id, can also be sent as arrays to send each of the files to a specific template, at a specific time, or saved in a specific folder. If this is not needed, then only the doc_id field should be an array.
For example, you need to create two files from different documents and place them in different folders on the Drive. To do this, you need to send two variables doc_id[] and two variables folder_id[] (in the same order). Also, if the task is to send them in one email, you need to specify one mail_id, and in email_send[] at first specify "manual", then "oncreate". In this case, the first file will be created, then - the second. And only after the creation of the second, the email specified in mail_id will be sent.
Sending Yourself a File After Creation
The file will be sent to the email of the account immediately after it is created. In the "Email Template" field, you can choose which template to use for sending. Beforehand in Email Templates you can create a separate template for sending emails to the account email. If you write the %data variable in the email text, then all file data will be added to this place as a table.
Deleting Files
To delete files, you need to send POST-DATA, POST-JSON, or GET requests to the address
https://dimaker.app/api/v1/drive/files/delete/
with the data specified below.
The request encoding is UTF-8. Required 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 when created via API. The file must not be in the trash.
OR
-
file_ids
Array of file IDs (string, 36 characters) to be deleted if multiple files need to be deleted in one request.
OR
creater_id
Generation ID (string, 36 characters) if the file was created via API. The generation ID can be passed instead of file_id or file_ids. In this case, all files with this generation ID will be deleted. The generation ID is returned in the create_id field when creating files via API.
delete_forever
Whether to delete the file permanently, without moving it to the trash. By default, the file is moved to the trash. Can take values:
- 0 - move to trash (default)
- 1 - delete permanently
Files in the trash are automatically deleted 60 days after moving to the trash.
Example
An example of a correct request to delete files:
{
"secure":"b4caf05b-6757-4d9c-b4bc-1924a9b31796",
"file_id":"369dc61e-40c2-46c0-81f4-e31ca8c33cc2"
}
Result
The server will return a JSON string with the following possible values:
-
result
The result of the request. It can have the following values:
error - request error. Files were not deleted.
success - successful request to delete files. -
files
An array containing the IDs of the deleted files. Only when the request is successful.
-
error_text
Only in case of an error. Textual description of the error. 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"]
}