API
Using the DiMaker API, you can create files with personal data and send them to recipients. API requests can be made from another server or from the browser using CORS requests.
Getting started
In the "Integration" - "API Tokens" section, you need to obtain a secure token for requests and allow the use of this token. In addition, you need to create a document containing variables for personal data, as well as an email template for email distribution and a folder in the Drive to store the created files.
Creating files
To create files, you need to send POST or GET requests to the address
https://dimaker.app/api/v1/create/
with the data specified below. Request encoding - UTF-8. Required fields are marked with an asterisk.
-
secure*
Token (string, 36 characters)
-
doc_id*
Document ID (string, 36 characters) that will be used to create the file. You can get the ID from the address bar when the document is open. The document must not be in the trash but can be in any Documents folder.
-
mask*
JSON string containing all variables for replacement in the form of key (variable) - value (text to replace). The string can contain data for creating multiple files (without restriction on the number).
Example for one file:
[{"%full name": "Ivanov", "%points":"100"}]
Example for multiple files:
[{"%full name": "Ivanov", "%points":"100"}, {"%full name": "Petrov", "%points":"200"}, {"%full name": "Sidorov", "%points":"300"}]
To specify the email address use %email, for the file name - %filename. To send the created files to multiple email addresses, list them separated by commas. In this case, the sending status in Drive will be displayed for the first email address.
Only double quotes can be used in accordance with the standard. If the value of the key contains quotes, they must be escaped.You can use either a direct link (http:// or https://) or a Base64 encoded image to insert an image into the image block.
Alternative method
If it is not possible to send a JSON string, replacement strings can be sent as request fields. Each replacement variable must start with the mask_ prefix, for example, mask_name and contain the value of the replacement. The variable will be searched in the document after the prefix. For example, the mask_name corresponds to the variable %name. To specify the email address in this case, use mask_email, and for the file name - mask_filename. -
mail_id
Email template ID (string, 36 characters) for email distribution. You can get the ID from the address bar when the template is open. If the variable is not passed, the email will not be sent.
-
email_send
The time when to send the email with the file. Can accept the following 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 period of time. In this case, two more parameters must be passed:
email_timeout_value - numerical value of the period at which to send emails, integer value
email_timeout_value - unit of measurement of the period. Can take the value "m" (minutes), "h" (hours), "d" (days).
Alternatively, to specify the exact time of sending, you need to pass the time in unix time format in email_timeout_timestamp. If timeout and email_timeout_timestamp are passed, the priority will be given to the latter. -
folder_id
ID of the folder in Drive (string, 36 characters) to save the files. If the folder does not exist, it will be automatically created when the first file is created.
-
page_id
Ordinal number of the sheet (number or string) if the document has multiple sheets. You can pass one number (the first sheet is 0), or numbers (separated by commas) of sheets that you want to use to create the file.
-
result
Determines how to return the result. Can take the values:
- The value is missing. A JSON string with the request result will be returned (see below)
- link. If the request is successful, a string containing a link to the created file will be returned (if several files were created in the request, a link to the first one will be returned). To retrieve the file itself, you need to go to the specified link. It takes 1 to 5 seconds to prepare the files themselves. Until the file is created, the request to this address will return a 404 error. If the request does not lead to the creation of the file, a JSON string with an error will be returned (see below).
- file. If the request is successful, the finished file will be returned (only the first one if several files were created). Since creating a
Ergebnis
Als Ergebnis wird der Server einen JSON-String zurückgeben, der mögliche Werte annimmt:
-
result
Das Ergebnis der Anfrage, das folgende Werte annehmen kann:
error - Fehler bei der Anfrage. Dateien wurden nicht erstellt.
success - erfolgreiche Anfrage zum Erstellen von Dateien. Abhängig von der Verwendung des API können Sie den erfolgreichen Dateierstellungsprozess melden oder ein Formular zum Abrufen der Dateien anzeigen. -
create_id
Generierte ID. Nur bei erfolgreicher Anfrage. Kann für andere API-Anfragen nützlich sein.
-
files
Ein Array, das die IDs der zu erstellenden Dateien enthält. Nur bei erfolgreicher Anfrage. Um die Datei im JPG-Format zu erhalten, ist ein Abruf über https://dimaker.app/getfile/{ID}/ erforderlich. Um die PDF-Datei herunterzuladen, muss dem Link pdf/ hinzugefügt werden. Das API gibt die ID der Datei sofort zurück, aber das Erstellen der Dateien selbst dauert etwa 1 bis 5 Sekunden pro Datei. Bis zur Erstellung der Datei gibt es am Link https://dimaker.app/getfile/{ID}/ eine 404-Fehlermeldung zurück.
-
url
URL-String zur Anzeige des Download-Widgets. Nur bei erfolgreicher Anfrage. Ein Iframe mit der angegebenen URL muss erstellt werden. Nur das Klicken auf den Link führt nicht zum Ergebnis. Die Domain der Website, auf der die Datei erhalten wird, muss in den API-Einstellungen korrekt angegeben sein.
Das Erstellen jeder Datei dauert 1 Sekunde plus einige Sekunden für die Verarbeitung der gesamten Gruppe. Direkt nach Absendung der Anfrage können Sie das Iframe mit der angegebenen URL öffnen. Wenn die Datei noch nicht erstellt wurde, wird eine entsprechende Meldung ausgegeben. Sobald die Dateien fertig sind, können sie heruntergeladen werden.
Sie können das Download-Widget in einem Dialogfeld über der Seite anzeigen. Hierfür muss das Iframe mit den folgenden zusätzlichen Styles erstellt werden: position:fixed; width:100%; height:100%; top:0; bottom:0; right:0; left:0; z-index:10000; background: rgb(0 0 0 / 72%); Der Adressleiste muss ?view=modal hinzugefügt werden. Und dieses Iframe muss im Body platziert werden. -
error_text
Nur im Fehlerfall. Textbeschreibung des Fehlers. Mögliche Fehler: inkorrektes Secure-Token, Maske für die Ersetzung, Dokumenten-ID, Vorlagenbrief-ID, Ordner-ID im Laufwerk oder interner Serverfehler.
Beispiel für zurückgegebene Daten bei erfolgreicher Anfrage:
{
"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"
]
}Erstellung mehrerer Dateien in einem Auftrag
In einem Auftrag können mehrere Dateien aus verschiedenen Dokumenten erstellt werden. Mit einem solchen Auftrag können mehrere Dateien erstellt werden, beispielsweise unter Verwendung von Vorlagen auf Russisch und Englisch. Wenn Sie einen Auftrag senden, erstellt der Server die erforderliche Anzahl von Dateien.
Um einen solchen Auftrag zu senden, muss die Variable doc_id ein Array sein (Variablenname - doc_id[]). In diesem Fall können mehrere doc_id[] -Variablen in einem Auftrag vorhanden sein, um mehrere Dateien zu erstellen. Andere Variablen wie mail_id, email_send und folder_id können ebenfalls als Arrays gesendet werden, um jedes der Dateien in bestimmten Vorlagen, zu einem bestimmten Zeitpunkt oder in einem bestimmten Ordner zu speichern. Wenn dies nicht erforderlich ist, sollte nur das doc_id-Feld als Array vorhanden sein.
Zum Beispiel müssen zwei Dateien aus verschiedenen Dokumenten erstellt und in verschiedenen Ordnern auf Drive abgelegt werden. Hierfür müssen zwei doc_id[] -Variablen und zwei folder_id[] -Variablen (in derselben Reihenfolge) gesendet werden. Wenn außerdem die Aufgabe besteht, sie in einer E-Mail zu senden, muss eine mail_id angegeben werden. Im email_send[] -Feld muss zunächst "manual" und dann "oncreate" angegeben werden. In diesem Fall wird zuerst eine Datei erstellt und dann die zweite. Erst nach Erstellung der zweiten Datei wird die E-Mail mit der in mail_id angegebenen Nachricht gesendet.
Senden von Dateien an sich selbst nach der Erstellung
Die Datei wird unmittelbar nach der Erstellung an die E-Mail-Adresse des Kontos gesendet. Im Feld "E-Mail-Template" können Sie auswählen, welche Vorlage für den Versand verwendet werden soll. Vorher können Sie im E-Mail-Vorlagen einen separaten Template für den Versand von E-Mails an die E-Mail-Adresse des Kontos erstellen. Wenn Sie in der E-Mail-Textvariable %data schreiben, werden alle Daten der Datei in Form einer Tabelle an dieser Stelle hinzugefügt.
Other integrations
-