API
En utilisant l'API DiMaker, vous pouvez créer des fichiers avec les données personnelles et les distribuer aux destinataires si nécessaire. Les requêtes vers l'API peuvent être faites aussi bien depuis un autre serveur que depuis le navigateur via une requête CORS.
Comment commencer
Dans la section « Intégration » - « Jetons API », vous devez obtenir un jeton Secure pour les requêtes et autoriser son utilisation. En outre, vous devez créer un document contenant les variables pour les données personnelles, ainsi qu'un modèle d'email pour les envois par mail et un dossier dans le Disque pour les fichiers finis.
Création de fichiers
Pour créer des fichiers, vous devez envoyer des requêtes POST-DATA, POST-JSON ou GET à l'adresse
https://dimaker.app/api/v1/create/
avec les données indiquées ci-dessous.
L'encodage des requêtes est UTF-8. Les champs obligatoires sont marqués d'un astérisque.
-
secure*
Jeton (chaîne de caractères, 36 caractères)
-
doc_id*
ID du document (chaîne de caractères, 36 caractères) à utiliser pour créer le fichier. L'ID peut être obtenu dans la barre d'adresse lorsque le document est ouvert. Le document ne doit pas être dans la corbeille, mais peut être placé dans n'importe quel dossier de Documents.
-
mask*
Chaîne JSON contenant toutes les variables à remplacer sous forme de clé (variable) - valeur (texte de remplacement). Peut contenir des données pour créer plusieurs fichiers (sans limitation de quantité).
Exemple pour un fichier:
[{"%name": "Ivanov", "%points":"100"}]
Exemple pour plusieurs fichiers:
[{"%name": "Ivanov", "%points":"100"}, {"%name": "Petrov", "%points":"200"}, {"%name": "Sidorov", "%points":"300"}]
Pour indiquer une adresse email, utilisez %email, pour le nom de fichier - %filename. Pour envoyer des fichiers créés à plusieurs adresses email, énumérez-les par une virgule. Le statut d'envoi dans le Disque sera affiché pour la première adresse.
Vous ne pouvez utiliser que des guillemets doubles conformément à la norme. Si la valeur de la clé contient des guillemets, ils doivent être échappés.Pour passer une image dans un bloc avec image, vous pouvez utiliser soit un lien direct (http:// ou https://), soit une image encodée en Base64. Dans ce dernier cas, la chaîne devrait commencer par "data:image/".
Méthode alternative
Si vous ne pouvez pas envoyer une chaîne JSON, les chaînes à remplacer peuvent être envoyées sous forme de champs de requête. Chaque variable à remplacer doit commencer par le préfixe mask_, par exemple mask_name et contenir la valeur à remplacer. Le document recherchera la variable après le préfixe. Par exemple, le champ mask_name correspond à la variable %name. Pour indiquer une adresse email dans ce cas, utilisez mask_email, et pour le nom de fichier - mask_filename. -
mail_id
ID du modèle d'email (chaîne de caractères, 36 caractères) pour le mailing. L'ID peut être obtenu dans la barre d'adresse lorsque le modèle est ouvert. Si la variable n'est pas transmise, alors l'email ne sera pas envoyé.
-
email_send
Heure d'envoi de l'email avec le fichier. Peut prendre les valeurs suivantes:
onfinish - Envoyer tous les emails après la création de tous les fichiers (par défaut)
oncreate - Envoyer les emails immédiatement après la création du fichier. Lors de la création d'un seul fichier, onfinish et oncreate sont identiques.
timeout - Envoyer les emails après un certain intervalle de temps. Dans ce cas, vous devez transmettre deux paramètres supplémentaires:
email_timeout_value - valeur numérique de l'intervalle après lequel envoyer les emails, valeur entière
email_timeout_unit - unité de mesure de l'intervalle. Peut prendre les valeurs "m" (minutes), "h" (heures), "d" (jours).
Ou, pour indiquer un temps d'envoi précis, vous devez transmettre l'heure sous forme d'horodatage Unix dans email_timeout_timestamp. Si email_timeout_value et email_timeout_timestamp sont transmis, le dernier a la priorité. -
folder_id
ID du dossier dans le Disque (chaîne de caractères, 36 caractères) pour enregistrer les fichiers. Si le dossier n'existe pas, il sera créé automatiquement lors de la création du premier fichier.
-
storage_period
Durée de conservation des fichiers dans le Disque. Si le paramètre n'est pas spécifié, les fichiers sont conservés indéfiniment, jusqu'à la suppression manuelle. Pour une suppression après un intervalle de temps, le paramètre doit prendre la valeur:
timeout. Dans ce cas, deux paramètres supplémentaires doivent être transmis:
storage_period_timeout_value - valeur numérique de l'intervalle après lequel supprimer les fichiers, valeur entière
storage_period_timeout_unit - unité de mesure de l'intervalle. Peut prendre les valeurs "m" (minutes), "h" (heures), "d" (jours).
Ou, pour indiquer un temps de suppression précis, vous devez transmettre l'heure sous forme d'horodatage Unix dans storage_period_timeout_timestamp. Si storage_period_timeout_value et storage_period_timeout_timestamp sont transmis, le dernier a la priorité. -
page_id
Numéro de la page (nombre ou chaîne), s'il y a plusieurs pages dans le document. Vous pouvez transmettre un numéro unique (première page - 0), ou des numéros de pages (séparés par des virgules) à utiliser pour créer le fichier.
-
result
Détermine sous quelle forme retourner le résultat. Peut prendre les valeurs:
- Absence de valeur. Une chaîne JSON avec le résultat de la requête sera retournée (voir ci-dessous)
- link. En cas de requête réussie, une chaîne contenant un lien vers le fichier créé sera retournée (en cas de création de plusieurs fichiers, un lien vers le premier). Pour obtenir le fichier lui-même, vous devez vous rendre à l'adresse indiquée. La préparation des fichiers prend du temps - de 1 à 5 secondes pour chaque fichier. Avant que le fichier ne soit créé, toute requête à cette adresse retourne une erreur 404. Si la requête n'a pas abouti à la création d'un fichier, une chaîne JSON avec une erreur sera retournée (voir ci-dessous).
- file. En cas de requête réussie, le fichier fini lui-même sera retourné (en cas de création de plusieurs fichiers, seulement le premier). Comme la création du fichier prend 1-5 secondes, le retour se fera uniquement après la création du fichier. Avec un nombre élevé de requêtes à l'API, le temps de création du fichier sera prolongé. Si le fichier n'est pas préparé dans les 30 secondes, l'API retournera une erreur 404 (bien que la requête de création finira par être exécutée). Si la requête n'a pas abouti à la création d'un fichier, une chaîne JSON avec une erreur sera retournée (voir ci-dessous). Si davantage de requêtes à l'API sont attendues, soit plus d'une requête toutes les 5 secondes, évitez ce paramètre.
Résultat
En résultat, le serveur renverra une chaîne JSON, prenant les valeurs suivantes possibles :
-
result
Résultat de la requête. Peut prendre les valeurs suivantes:
error - échec de la requête. Fichiers non créés.
success - requête réussie pour la création des fichiers. Selon le scénario d'utilisation de l'API, vous pouvez informer de la création réussie des fichiers ou afficher un formulaire de réception de fichiers. -
create_id
ID de création. Seulement en cas d'exécution réussie de la requête. Peut être utile pour d'autres requêtes vers l'API.
-
files
Tableau contenant les ID des fichiers créés. Seulement en cas d'exécution réussie de la requête. Pour obtenir le fichier lui-même au format JPG, vous devez accéder à https://dimaker.app/getfile/{ID}/. Pour télécharger le fichier PDF, ajoutez pdf/ à l'adresse. L'API renvoie l'ID du fichier immédiatement, cependant, la préparation des fichiers prend du temps - de 1 à 5 secondes pour chaque fichier. Jusqu'à ce que le fichier soit créé, la requête à https://dimaker.app/getfile/{ID}/ retournera une erreur 404.
-
url
URL de la chaîne pour afficher le widget de téléchargement des fichiers. Seulement en cas d'exécution réussie de la requête. Vous devez créer un Iframe avec l'URL indiqué. Aller simplement à l'URL ne donnera pas de résultat. Le domaine du site où le fichier est récupéré doit être correctement spécifié dans les paramètres de l'API.
La création de chaque fichier prend 1 seconde + quelques secondes pour le traitement de l'ensemble du groupe. Immédiatement après l'envoi de la requête, vous pouvez ouvrir l'Iframe avec les URL indiqués. Si la création des fichiers n'est pas encore terminée, un message correspondant sera affiché. Dès que les fichiers seront prêts, ils seront proposés au téléchargement.
Vous pouvez afficher le widget de téléchargement dans une boîte de dialogue en haut de la page. Pour cela, vous devez créer un Iframe avec les styles supplémentaires suivants: position:fixed; width:100%; height:100%; top:0; bottom:0; right:0; left:0; z-index:10000; background: rgb(0 0 0 / 72%); Ajoutez ?view=modal à la barre d'adresse. Et placez cet iframe dans le corps. -
error_text
En cas d'erreur uniquement. Description textuelle de l'erreur. Erreurs possibles: Secure token incorrect, masque pour remplacement, ID de document, ID de modèle d'email, ID de dossier dans le Disque, ou erreur interne du serveur.
Exemple de données retournées en cas de requête réussie:
{
"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"
]
}
Création de plusieurs fichiers en une seule requête
Dans une seule requête, vous pouvez demander la création de plusieurs fichiers à partir de documents différents. Avec une telle requête, vous pouvez créer plusieurs fichiers, par exemple en utilisant des modèles en russe et en anglais. En envoyant une seule requête, le serveur créera le nombre requis de fichiers.
Pour envoyer une telle requête, la variable doc_id doit être un tableau (nom de la variable - doc_id[]). Dans ce cas, une requête peut contenir plusieurs variables doc_id[] - pour créer plusieurs fichiers. D'autres variables telles que mail_id, email_send, folder_id peuvent également être envoyées sous forme de tableaux, pour que chaque fichier soit envoyé avec un modèle spécifique, à un moment particulier ou enregistré dans un dossier particulier. Si cela n'est pas nécessaire, le champ doc_id seul doit être un tableau.
Par exemple, il est nécessaire de créer deux fichiers à partir de documents différents et de les placer dans différents dossiers sur le Disque. Pour cela, vous devez envoyer deux variables doc_id[] et deux variables folder_id[] (dans le même ordre). De plus, si vous souhaitez les envoyer par un seul email, vous devez indiquer un seul mail_id, et dans email_send[] d'abord indiquer "manual", puis "oncreate". Ainsi, un fichier sera d'abord créé, puis le second. Et seulement après la création du second sera envoyé avec l'email spécifié dans mail_id.
Envoyer un fichier à vous-même après création
Le fichier sera envoyé à l'email du compte immédiatement après sa création. Dans le champ « Modèle d'email », choisissez le modèle à utiliser pour l'envoi. Créez un modèle séparé dans Modèles d'email pour les envois par email au compte. Si vous insérez la variable %data dans le corps de l'e-mail, toutes les données du fichier seront ajoutées à cet emplacement sous forme de tableau.
Suppression de fichiers
Pour supprimer des fichiers, vous devez envoyer des requêtes POST-DATA, POST-JSON ou GET à l'adresse
https://dimaker.app/api/v1/drive/files/delete/
avec les données indiquées ci-dessous.
L'encodage des requêtes est UTF-8. Les champs obligatoires sont marqués d'un astérisque.
-
secure*
Jeton (chaîne de caractères, 36 caractères)
-
file_id
ID du fichier (chaîne de caractères, 36 caractères) à supprimer. L'ID du fichier est retourné dans le tableau files lors de la création via l'API. Le fichier ne doit pas être dans la corbeille.
OU
-
file_ids
Tableau d'ID de fichiers (chaîne de caractères, 36 caractères) à supprimer, si vous avez besoin de supprimer plusieurs fichiers dans une requête.
OU
creater_id
ID de création (chaîne de caractères, 36 caractères) si le fichier a été créé via l'API. L'ID de création peut être transmis à la place de file_id ou file_ids. Dans ce cas, tous les fichiers correspondant à cet ID de création seront supprimés. L'ID de création est retourné dans le champ create_id lors de la création de fichiers via l'API.
delete_forever
Supprimer définitivement le fichier, sans le déplacer vers la corbeille. Par défaut, le fichier est déplacé dans la corbeille. Peut prendre les valeurs:
- 0 - déplacer dans la corbeille (par défaut)
- 1 - supprimer définitivement
Les fichiers du corbeille sont supprimés automatiquement 60 jours après le déplacement dans le corbeille.
Exemple
Exemple de requête correcte pour la suppression de fichiers:
{
"secure":"b4caf05b-6757-4d9c-b4bc-1924a9b31796",
"file_id":"369dc61e-40c2-46c0-81f4-e31ca8c33cc2"
}
Résultat
En résultat, le serveur renverra une chaîne JSON, prenant les valeurs suivantes possibles :
-
result
Résultat de la requête. Peut prendre les valeurs suivantes:
error - échec de la requête. Fichiers non supprimés.
success - requête réussie pour la suppression de fichiers. -
files
Tableau contenant les ID des fichiers supprimés. Seulement en cas d'exécution réussie de la requête.
-
error_text
En cas d'erreur uniquement. Description textuelle de l'erreur. Erreurs possibles: Secure token incorrect, ID du fichier, ID de création, ou erreur interne du serveur.
Exemple de données retournées en cas de requête réussie:
{
"result":"success",
"files":["369dc61e-40c2-46c0-81f4-e31ca8c33cc2"]
}