 API

Avec l'API DiMaker, vous pouvez générer des fichiers contenant des données personnelles et, si nécessaire, les transmettre aux destinataires. Les requêtes vers l'API peuvent être effectuées à partir d'un autre serveur ou directement depuis le navigateur via CORS.

Premiers pas

Dans la section « Intégration » - « Jetons API », vous devez obtenir un jeton sécurisé (Secure token) pour vos requêtes et autoriser son utilisation. De plus, il est nécessaire de créer un document contenant des variables pour les données personnelles, un modèle d'e-mail pour les envois et un dossier sur le disque pour les fichiers finis.

Création de fichiers

Pour créer des fichiers, vous devez envoyer une requête POST-DATA, POST- ou GET à l'adresse
https://dimaker.app/api/v1/create/
avec les données ci-dessous.
L'encodage des requêtes doit être UTF-8. Les champs obligatoires sont marqués d'un astérisque.

• secure*

  Jeton (chaîne, 36 caractères)

• doc_id*

  ID du document (chaîne, 36 caractères) utilisé pour créer le fichier. L'ID peut être extrait de la barre d'adresse lorsque le document est ouvert. Le document ne doit pas se trouver dans la corbeille mais peut être dans n'importe quel dossier de vos documents.

• mask*

  Chaîne contenant toutes les variables à remplacer sous la forme clé (variable) - valeur (texte de substitution). Elle peut contenir les données nécessaires à la création de plusieurs fichiers (sans limite de quantité).
  Exemple pour un fichier unique:
  [{"%name": "Dupont", "%score":"100"}]
  Exemple pour plusieurs fichiers:
  [{"%name": "Dupont", "%score":"100"}, {"%name": "Martin", "%score":"200"}, {"%name": "Durand", "%score":"300"}]
  Pour spécifier une adresse e-mail, utilisez %email, et pour le nom du fichier %filename. Pour envoyer les fichiers créés à plusieurs adresses e-mail, indiquez-les séparées par des virgules. Dans ce cas, le statut de l'envoi sur le disque sera indiqué pour la première adresse.
  Utilisez uniquement des guillemets doubles conformément à la norme. Si la valeur d'une clé contient des guillemets, ils doivent être échappés.

  Pour insérer une image dans un bloc, vous pouvez utiliser soit un lien direct (http:// ou https://), soit une image encodée en Base64. Dans ce dernier cas, la chaîne doit commencer par "data:image/".

  Méthode alternative
  Si l'envoi d'une chaîne n'est pas possible, les variables à remplacer peuvent être envoyées comme champs de la requête. Chaque variable à remplacer doit avoir le préfixe mask_, par exemple mask_name, et contenir la valeur de remplacement correspondante. Dans le document, la variable sera recherchée comme suit: après le préfixe. Par exemple, le champ mask_name correspond à la variable %name. Pour spécifier une adresse e-mail dans ce cas, utilisez mask_email, et pour le nom du fichier mask_filename.

• mail_id

  ID du modèle de mail (chaîne, 36 caractères) utilisé pour l'envoi par e-mail. L'ID peut être extrait de la barre d’adresse lorsque le modèle est ouvert. Si la variable n'est pas fournie, aucun e-mail ne sera envoyé.

• email_send

  Moment où envoyer l'e-mail avec le fichier. Les valeurs possibles sont :
  onfinish - Envoyer tous les mails après la création de tous les fichiers (valeur par défaut)
  oncreate - Envoyer les e-mails immédiatement après la création de chaque fichier. Lorsque seul un fichier est créé, onfinish et oncreate sont identiques.
  timeout - Envoyer les e-mails après un délai. Dans ce cas, vous devez également fournir deux paramètres :
  email_timeout_value - Nombre entier correspondant au délai (ex. 10)
  email_timeout_unit - Unité de mesure du délai (m = minutes, h = heures, d = jours).
  Alternativement, pour préciser une heure exacte, vous pouvez fournir un timestamp UNIX dans email_timeout_timestamp. Si timeout et email_timeout_timestamp sont fournis, ce dernier sera prioritaire.

• folder_id

  ID du dossier de stockage sur le disque (chaine, 36 caractères). Si le dossier n'existe pas, il sera automatiquement créé lors de la création du premier fichier.

• page_id

  Numéro de page (entier ou chaîne) à utiliser si le document contient plusieurs pages. Vous pouvez fournir un seul numéro (première page = 0) ou plusieurs numéros séparés par des virgules pour spécifier les pages à utiliser.

• result

  Détermine le format du retour. Valeurs possibles :

  • Aucune valeur. Une chaîne contenant le retour de la requête sera fournie (voir ci-dessous).
  • link. En cas de requête réussie, un lien vers le fichier créé sera renvoyé (si plusieurs fichiers sont créés, le lien mènera au premier). Vous pourrez utiliser ce lien pour récupérer le fichier. La préparation des fichiers prend entre 1 et 5 secondes chacun. Avant la création du fichier, toute requête à ce lien renverra une erreur 404. Si la requête ne génère aucun fichier, une chaîne avec une erreur sera renvoyée (voir ci-dessous).
  • file. En cas de requête réussie, le fichier créé sera directement renvoyé (si plusieurs fichiers sont créés, ce sera le premier). Comme la création prend 1-5 secondes par fichier, le retour aura lieu une fois le fichier totalement prêt. Si la charge sur l'API est élevée, le délai peut augmenter. Si la création dépasse 30 secondes, l'API renverra une erreur 404. Il est déconseillé d'utiliser ce paramètre s'il y a plus d'une requête API tous les 5 secondes.

Résultat

Le serveur retournera une chaîne avec les valeurs suivantes :

• result

  Résultat de la requête. Valeurs possibles :
  error - Erreur dans la requête. Aucun fichier n'a été créé.
  success - La requête a abouti, les fichiers ont été créés. Vous pouvez alors en informer vos utilisateurs ou afficher le fichier à télécharger.

• create_id

  ID de création. Disponible uniquement en cas de succès. Utile pour futures requêtes à l'API.

• files

  Tableau contenant des ID des fichiers créés. Disponible uniquement en cas de succès. Pour récupérer un fichier en format JPG, rendez-vous sur l'URL https://dimaker.app/getfile/{ID}/. Pour obtenir le fichier en PDF, ajoutez pdf/ à l'URL. L'API retourne l'ID immédiatement, mais la préparation des fichiers prend 1 à 5 secondes. Tant que le fichier n'est pas prêt, une requête vers https://dimaker.app/getfile/{ID} renverra une erreur 404.

• url

  URL du widget de téléchargement des fichiers. Disponible uniquement en cas de succès. Vous devez utiliser cet URL dans un Iframe. Un simple clic sur le lien ne suffit pas. Le domaine du site sur lequel les fichiers sont téléchargés doit être correctement configuré dans les paramètres API.
  L'activation de chaque fichier prend environ 1 seconde + quelques secondes pour le traitement du groupe. Vous pouvez ouvrir l'Iframe avec l'URL dès que la commande est envoyée. Si la création des fichiers est encore en cours, un message de patience sera affiché. Une fois prêts, le téléchargement sera proposé.
  Pour intégrer un widget de téléchargement dans une fenêtre modale, créez 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" à l'URL et placez cet Iframe dans le body de votre page.

• error_text

  En cas d'erreur uniquement. Description de l'erreur, qui peut être : Jeton sécurisé incorrect, masque invalide, ID du document, ID du modèle de mail, ID du dossier ou une erreur interne du serveur.

Exemple de réponse en cas de succès:
{
"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éer plusieurs fichiers en une seule requête

Il est possible de générer plusieurs fichiers à partir de différents documents en une seule requête. Par exemple, cela peut servir à créer des fichiers utilisant des modèles en russe et en anglais. À partir d'une seule requête, le serveur génère autant de fichiers que nécessaire.

Pour envoyer une telle requête, la variable doc_id doit être un tableau (nom de la variable : doc_id[]). Ainsi, plusieurs variables doc_id[] peuvent être fournies dans une requête pour créer plusieurs fichiers. D'autres variables comme mail_id, email_send, folder_id peuvent aussi être envoyées sous forme de tableau pour lier chaque fichier à un modèle d’e-mail spécifique, un calendrier d’envoi ou un dossier. Si besoin, seul le champ doc_id devrait être sous forme de tableau.

Exemple : créer deux fichiers à partir de documents différents et les enregistrer dans des dossiers séparés sur le disque. Vous devrez envoyer les variables doc_id[] et folder_id[] (dans le même ordre). Si ces fichiers doivent être envoyés ensemble dans un seul e-mail, spécifiez un seul mail_id, et pour email_send[], indiquez d'abord « manual », puis « oncreate ». Dans ce cas, le premier fichier sera créé, ensuite le second, et l’envoi aura lieu une fois les deux fichiers générés.

S'envoyer le fichier après création

Le fichier sera envoyé à l’adresse e-mail liée à votre compte dès qu’il aura été généré. Dans la section « Modèle de courrier », vous pouvez choisir quel modèle utiliser pour l’envoi. Un modèle spécifique peut également être créé sous Modèles d'e-mails pour les courriers internes.
Dans le texte d’email, utilisez la variable %data pour insérer toutes les informations relatives au fichier sous forme de tableau.

Suppression des fichiers

Pour supprimer des fichiers, envoyez une requête POST-DATA, POST- ou GET à l’adresse
https://dimaker.app/api/v1/drive/files/delete/
avec les données ci-dessous.
L’encodage des requêtes doit être UTF-8. Les champs obligatoires sont marqués par un astérisque.

• secure*

  Jeton (chaîne, 36 caractères)

• file_id

  ID du fichier (chaîne, 36 caractères) à supprimer. L’ID 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 contenant les IDs des fichiers (chaîne, 36 caractères) à supprimer si plusieurs fichiers doivent être supprimés en une seule requête.

  OU

• creater_id

  ID de création (chaîne, 36 caractères) si le fichier a été généré via l’API. Cet ID peut être fourni à la place de file_id ou file_ids. Dans ce cas, tous les fichiers liés à cet ID seront supprimés. L’ID de création est retourné dans le champ create_id lors de la génération des fichiers via l’API.

• delete_forever

  Savoir si le fichier doit être supprimé définitivement sans passer par la corbeille. Par défaut, le fichier est déplacé dans la corbeille. Valeurs possibles :

  • 0 - Déplacement dans la corbeille (par défaut)
  • 1 - Suppression définitive

  Les fichiers dans la corbeille sont automatiquement supprimés au bout de 60 jours.

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 retour, le serveur renverra une chaîne avec les valeurs suivantes :

• result

  Résultat de la requête. Valeurs possibles :
  error - Erreur dans la requête. Les fichiers n'ont pas été supprimés.
  success - Requête réussie et fichiers supprimés.

• files

  Tableau contenant les IDs des fichiers supprimés. Disponible uniquement en cas de succès.

• error_text

  En cas d'erreur uniquement. Description de l'erreur, qui peut être : Jeton incorrect, ID du fichier, ID de création ou une erreur interne serveur.

Exemple de réponse en cas de succès :
{
"result":"success",
"files":["369dc61e-40c2-46c0-81f4-e31ca8c33cc2"]
}

Autres intégrations