API

Die Dokumente wurden automatisch mit maschinellem Lernen erstellt.

Mit der DiMaker-API können Dateien mit persönlichen Daten erstellt und bei Bedarf den Empfängern bereitgestellt werden. Anfragen an die API können sowohl von einem anderen Server als auch von einem Browser über CORS-Anfragen erfolgen.

Wo soll man beginnen

Im Bereich "Integration" - "API-Tokens" müssen Sie ein Secure-Token für Anfragen erhalten und dessen Verwendung zulassen. Darüber hinaus muss ein Dokument erstellt werden, das Variablen für persönliche Daten sowie eine E-Mail-Vorlage für den Versand und einen Ordner auf dem Drive für die fertigen Dateien enthält.

Erstellung von Dateien

Um Dateien zu erstellen, müssen Sie POST-DATA-, POST-JSON- oder GET-Anfragen an die Adresse schicken
https://dimaker.app/api/v1/create/
mit den unten angegebenen Daten.
Die Codierung der Anfrage ist UTF-8. Pflichtfelder sind mit einem Sternchen markiert.

  • secure*

    Token (Zeichenkette, 36 Zeichen)

  • doc_id*

    Dokument-ID (Zeichenkette, 36 Zeichen), das zur Erstellung der Datei verwendet wird. Die ID kann in der Adressleiste abgerufen werden, wenn das Dokument geöffnet ist. Das Dokument darf sich nicht im Papierkorb befinden, kann jedoch in jedem beliebigen Ordner in Dokumenten abgelegt sein.

  • mask*

    JSON-Zeichenkette, die alle zu ersetzenden Variablen als Schlüssel (Variable) - Wert (Text zur Ersetzung) enthält. Kann Daten für die Erstellung mehrerer Dateien ohne Mengenbegrenzung enthalten.
    Beispiel für eine Datei:
    [{"%name": "Ivanov", "%punkte":"100"}]
    Beispiel für mehrere Dateien:
    [{"%name": "Ivanov", "%punkte":"100"}, {"%name": "Petrov", "%punkte":"200"}, {"%name": "Sidorov", "%punkte":"300"}]
    Zur Angabe der E-Mail-Adresse verwenden Sie bitte %email, für den Dateinamen %filename. Um die erstellten Dateien an mehrere E-Mail-Adressen zu senden, geben Sie diese durch Kommata getrennt an. Der Status der Zustellung auf dem Drive wird bei der ersten Adresse angezeigt.
    Nur doppelte Anführungszeichen sollten entsprechend dem Standard verwendet werden. Wenn der Wert des Schlüssels Anführungszeichen enthält, müssen diese maskiert werden.

    Zur Übertragung eines Bildes in einen Bildblock kann entweder ein direkter Link (http:// oder https://) oder ein in Base64 kodiertes Bild verwendet werden. Im zweiten Fall muss die Zeichenkette mit "data:image/" beginnen.

    Alternative Methode
    Wenn es nicht möglich ist, eine JSON-Zeichenkette zu senden, können die Ersetzungszeichenfolgen als Anfragefelder gesendet werden. Jede Ersetzungsvariable muss mit dem Präfix mask_ beginnen, z.B. mask_name, und den Wert für die Ersetzung enthalten. In diesem Fall wird die Variable nach dem Präfix im Dokument gesucht. Zum Beispiel entspricht das Feld mask_name der Variable %name. Zur Angabe der E-Mail-Adresse in diesem Fall muss mask_email verwendet werden, und der Dateiname mask_filename.

  • mail_id

    ID der E-Mail-Vorlage (Zeichenkette, 36 Zeichen) für den Versand per E-Mail. Die ID kann in der Adressleiste abgerufen werden, wenn die Vorlage geöffnet ist. Wenn die Variable nicht übergeben wird, wird keine E-Mail gesendet.

  • email_send

    Zeigt die Zeit an, zu der das E-Mail mit der Datei gesendet werden soll. Es kann folgende Werte annehmen:
    onfinish - Senden Sie alle E-Mails nach der Erstellung aller Dateien (standardmäßig)
    oncreate - Senden Sie E-Mails sofort nach der Erstellung der Datei. Bei der Erstellung einer Datei sind onfinish und oncreate identisch.
    timeout - Senden Sie E-Mails nach einem Zeitintervall. In diesem Fall müssen zwei weitere Parameter übergeben werden:
    email_timeout_value - numerischer Wert des Intervalls, nach dem die E-Mails gesendet werden sollen, ganzzahliger Wert
    email_timeout_unit - Maßeinheit des Intervalls. Es kann den Wert "m" (Minuten), "h" (Stunden), "d" (Tage) annehmen.
    Alternativ, um eine genaue Versandzeit anzugeben, muss die Zeit im Unix-Format in email_timeout_timestamp übermittelt werden. Wenn sowohl email_timeout_value als auch email_timeout_timestamp übergeben werden, hat letzteres Vorrang.

  • folder_id

    ID des Ordners auf dem Drive (Zeichenkette, 36 Zeichen) zur Speicherung der Dateien. Wenn der Ordner nicht existiert, wird er automatisch bei der Erstellung der ersten Datei erstellt.

  • storage_period

    Speicherzeit der Dateien auf dem Drive. Wenn der Parameter nicht angegeben ist, werden die Dateien unbegrenzt aufbewahrt, bis sie manuell gelöscht werden. Um sie nach einem Zeitintervall zu löschen, muss der Wert sein:
    timeout. In diesem Fall müssen zwei weitere Parameter übermittelt werden:
       storage_period_timeout_value - numerischer Wert des Intervalls, nach dem die Dateien gelöscht werden sollen, ganzzahliger Wert
       storage_period_timeout_unit - Maßeinheit des Intervalls. Es kann den Wert "m" (Minuten), "h" (Stunden), "d" (Tage) annehmen.
    Alternativ, um eine genaue Löschzeit anzugeben, muss die Zeit im Unix-Format in storage_period_timeout_timestamp übermittelt werden. Wenn sowohl storage_period_timeout_value als auch email_timeout_timestamp übergeben werden, hat letzteres Vorrang.

  • page_id

    Reihenfolgenummer des Blattes (Zahl oder Zeichenkette), wenn das Dokument mehrere Blätter enthält. Sie können eine Nummer (erstes Blatt - 0) oder Zahlen (durch Komma getrennt) von Blättern angeben, die zur Erstellung der Datei verwendet werden sollen.

  • result

    Bestimmt, wie das Ergebnis zurückgegeben werden soll. Es kann folgende Werte annehmen:

    • Wert fehlt. Es wird eine JSON-Zeichenkette mit dem Ergebnis der Anfrage zurückgegeben (siehe unten)
    • link. Bei einer erfolgreichen Anfrage wird eine Zeichenkette mit einem Link zur erstellten Datei zurückgegeben (wenn bei der Anfrage mehrere Dateien erstellt wurden, dann der Link zur ersten). Um die Datei selbst abzurufen, müssen Sie den angegebenen Link abrufen. Die Erstellung der eigentlichen Dateien dauert 1 bis 5 Sekunden pro Datei. Bis die Datei erstellt ist, zeigt die Abfrage zu dieser Adresse einen 404-Fehler an. Wenn die Anfrage nicht zur Erstellung einer Datei geführt hat, wird eine JSON-Zeichenkette mit einem Fehler zurückgegeben (siehe unten).
    • file. Bei einer erfolgreichen Anfrage wird die fertige Datei selbst zurückgegeben (wenn bei der Anfrage mehrere Dateien erstellt wurden, dann nur die erste). Da die Erstellung der Datei 1-5 Sekunden dauert, erfolgt die Rückgabe erst nach Erstellung der Datei. Bei einer großen Anzahl von Anfragen an die API wird die Erstellungszeit der Datei erhöht. Wenn die Datei nicht innerhalb von 30 Sekunden erstellt wird, gibt die API einen 404-Fehler zurück (obwohl die Anfrage zur Erstellung der Datei letztendlich ausgeführt wird). Wenn die Anfrage nicht zur Erstellung einer Datei geführt hat, wird eine JSON-Zeichenkette mit einem Fehler zurückgegeben (siehe unten). Wenn erwartet wird, dass die Anfragen an die API mehr als eine Anfrage alle 5 Sekunden übersteigen, sollte dieser Parameter nicht verwendet werden.

Ergebnis

Als Ergebnis gibt der Server eine JSON-Zeichenkette zurück, die die folgenden möglichen Werte annehmen kann:

  • result

    Ergebnis der Anfrage. Es kann folgende Werte annehmen:
    error - Fehler in der Anfrage. Dateien wurden nicht erstellt.
    success - erfolgreiche Anfrage zur Erstellung der Dateien. Je nach Nutzungsszenario der API kann die erfolgreiche Erstellung der Dateien gemeldet oder ein Formular zur Abrufung der Dateien angezeigt werden.

  • create_id

    Generierungs-ID. Nur bei erfolgreicher Ausführung der Anfrage. Kann für weitere Anfragen an die API nützlich sein.

  • files

    Array, das die IDs der erstellten Dateien enthält. Nur bei erfolgreicher Ausführung der Anfrage. Um die Datei selbst im JPG-Format abzurufen, muss es unter https://dimaker.app/getfile/{ID}/ abgerufen werden. Zum Herunterladen der PDF-Datei einfach pdf/ zur Adresse hinzufügen. Die API gibt die Datei-ID sofort zurück, aber die Erstellung der Dateien selbst dauert 1 bis 5 Sekunden pro Datei. Bis die Datei erstellt wird, zeigt die Anfrage an https://dimaker.app/getfile/{ID}/ einen 404-Fehler an.

  • url

    URL-Zeichenkette zur Ausgabe des Download-Widgets für Dateien. Nur bei erfolgreicher Ausführung der Anfrage. Ein Iframe mit der angegebenen URL muss erstellt werden. Ein einfacher Übergang zum URL führt zu keinem Ergebnis. Die Domain der Website, auf der der Dateizugriff erfolgt, muss korrekt in den API-Einstellungen angegeben sein.
    Die Erstellung jeder Datei dauert 1 Sekunde + einige Sekunden für die Verarbeitung der gesamten Gruppe. Unmittelbar nach dem Senden der Anfrage können Sie ein Iframe mit der angegebenen URL öffnen. Wenn die Erstellung der Dateien noch nicht abgeschlossen ist, wird eine entsprechende Nachricht angezeigt. Sobald die Dateien fertig sind, wird angeboten, sie herunterzuladen.
    Das Download-Widget kann in einem Dialogfenster über der Seite angezeigt werden. Dazu muss ein Iframe mit den folgenden zusätzlichen Stilen 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%); Am Ende der Adressleiste muss ?view=modal hinzugefügt werden. Und dieses Iframe im body platzieren.

  • error_text

    Nur bei einem Fehler. Textbeschreibung des Fehlers. Mögliche Fehler: ungültiges Secure-Token, Masken für die Ersetzung, Dokument-ID, E-Mail-Vorlage-ID, Ordnere-ID im Drive, oder interner Serverfehler.

Beispiel der zurückgegebenen Daten bei einer erfolgreichen 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"
]
}

Erstellen mehrerer Dateien in einer Anfrage

In einer Anfrage können mehrere Dateien aus verschiedenen Dokumenten erstellt werden. Mit einer solchen Anfrage können mehrere Dateien erstellt werden, z.B. mit Vorlagen in deutscher und englischer Sprache. Nach dem Absenden einer Anfrage erzeugt der Server die erforderliche Anzahl von Dateien.

Um eine solche Anfrage zu senden, muss die Variable doc_id ein Array sein (Variablenname - doc_id[]). In diesem Fall kann eine Anfrage mehrere doc_id[]-Variablen enthalten - um mehrere Dateien zu erstellen. Andere Variablen wie mail_id, email_send, folder_id können ebenfalls in Form von Arrays gesendet werden, sodass jede Datei in einem bestimmten Template zu einer bestimmten Zeit gesendet oder in einem bestimmten Ordner gespeichert wird. Wenn dies nicht erforderlich ist, sollte nur das Feld doc_id als Array angelegt sein.

Beispiel: Zwei Dateien aus verschiedenen Dokumenten sollen erstellt und in verschiedene Ordner auf dem Drive abgelegt werden. Dazu müssen zwei doc_id[]-Variablen und zwei folder_id[]-Variablen (in derselben Reihenfolge) gesendet werden. Wenn die Dateien außerdem mit einer einzigen E-Mail gesendet werden sollen, muss ein mail_id angegeben werden, und in email_send[] sollte zuerst "manual" und dann "oncreate" angegeben werden. In diesem Fall wird zunächst eine Datei erstellt, dann die zweite. Und erst nach der Erstellung der zweiten Datei wird der Versand zusammen mit der in mail_id angegebenen E-Mail durchgeführt.

Selbst eine Datei nach der Erstellung senden

Die Datei wird sofort nach der Erstellung an die E-Mail des Kontos gesendet. Im Feld „E-Mail-Vorlage“ kann ausgewählt werden, welche Vorlage für den Versand verwendet werden soll. In den E-Mail-Vorlagen kann vorab eine separate Vorlage zum Versenden von E-Mails an das Konto erstellt werden. Wenn im Text der Nachricht die Variable %data eingefügt wird, werden an dieser Stelle alle Dateidaten als Tabelle hinzugefügt.

Dateien löschen

Um Dateien zu löschen, müssen POST-DATA-, POST-JSON- oder GET-Anfragen an die Adresse gesendet werden
https://dimaker.app/api/v1/drive/files/delete/
mit den unten angegebenen Daten.
Die Codierung der Anfrage ist UTF-8. Pflichtfelder sind mit einem Sternchen markiert.

  • secure*

    Token (Zeichenkette, 36 Zeichen)

  • file_id

    Datei-ID (Zeichenkette, 36 Zeichen), die gelöscht wird. Die Datei-ID wird im Array files bei der Erstellung über die API zurückgegeben. Die Datei darf sich nicht im Papierkorb befinden.

    ODER

  • file_ids

    Array von Datei-IDs (Zeichenkette, 36 Zeichen), die gelöscht werden, wenn mehrere Dateien in einer Anfrage gelöscht werden sollen.

    ODER

  • creater_id

    Generierungs-ID (Zeichenkette, 36 Zeichen), wenn die Datei über die API erstellt wurde. Die Generierungs-ID kann anstelle von file_id oder file_ids übermittelt werden. In diesem Fall werden alle Dateien mit dieser Generierungs-ID gelöscht. Die Generierungs-ID wird beim Erstellen von Dateien über die API im Feld create_id zurückgegeben.

    delete_forever

    Datei endgültig löschen, ohne sie in den Papierkorb zu verschieben. Standardmäßig wird die Datei in den Papierkorb verschoben. Es kann die folgenden Werte annehmen:

    • 0 - in den Papierkorb verschieben (standardmäßig)
    • 1 - endgültig löschen

    Dateien werden automatisch 60 Tage nach der Verschiebung in den Papierkorb aus dem Papierkorb gelöscht.

Beispiel

Beispiel einer korrekten Anfrage zum Löschen von Dateien:
{
"secure":"b4caf05b-6757-4d9c-b4bc-1924a9b31796",
"file_id":"369dc61e-40c2-46c0-81f4-e31ca8c33cc2"
}

Ergebnis

Als Ergebnis gibt der Server eine JSON-Zeichenkette zurück, die die folgenden möglichen Werte annehmen kann:

  • result

    Ergebnis der Anfrage. Es kann folgende Werte annehmen:
    error - Fehler in der Anfrage. Dateien wurden nicht gelöscht.
    success - erfolgreiche Anfrage zum Löschen der Dateien.

  • files

    Array, das die IDs der gelöschten Dateien enthält. Nur bei erfolgreicher Ausführung der Anfrage.

  • error_text

    Nur bei einem Fehler. Textbeschreibung des Fehlers. Mögliche Fehler: ungültiges Secure-Token, Datei-ID, Generierungs-ID, oder interner Serverfehler.

Beispiel der zurückgegebenen Daten bei einer erfolgreichen Anfrage:
{
"result":"success",
"files":["369dc61e-40c2-46c0-81f4-e31ca8c33cc2"]
}


Weitere Integrationen

Sind Sie bereit für Start?

Öffnen Web-App öffnen