Intégration Zapier : automatiser la génération de documents

L’intégration PDFMonkey pour Zapier vous permet de générer, récupérer et gérer des documents directement depuis vos Zaps. Si vous découvrez l’intégration, commencez par la section Premiers pas ci-dessous pour un tutoriel complet de bout en bout.

Premiers pas

Avant de commencer, assurez-vous d’avoir un compte PDFMonkey et un modèle publié. Consultez De zéro à votre premier document pour les instructions de configuration.

Écrire votre premier modèle

Dans l’onglet HTML de votre modèle, insérez le code suivant :

<p class="greeting">Hello {{name}}!</p>
<p>Your favorite number is {{favoriteNumber}}.</p>

Dans l’onglet CSS, insérez le code suivant :

.greeting {
  color: #6D28D9;
  font-size: 24px;
}

Et enfin dans l’onglet Test data, insérez ceci :

{
  "name": "Peter Parker",
  "favoriteNumber": 8
}

Cliquez sur Save pour voir l’aperçu se mettre à jour, puis cliquez sur Publish pour rendre le modèle disponible pour la génération.

Générer votre premier document

Maintenant que votre modèle est terminé, rendez-vous sur Zapier.

Pour ce guide, nous allons définir un Zap déclenché par la soumission d’un formulaire Tally, générer un document avec PDFMonkey puis l’envoyer par email.

Le formulaire Tally

Nous utiliserons le formulaire Tally suivant comme source d’information dans notre Zap :

Configurer votre Zap

Commencez par créer un nouveau Zap. Comme trigger, nous utiliserons l’événement New Response de Tally :

Nous procédons ensuite au remplissage du formulaire et vérifions qu’il est correctement connecté dans Zapier :

Appeler PDFMonkey

Maintenant que nous avons des données avec lesquelles travailler, nous allons configurer notre action PDFMonkey.

Sélectionnez l’application PDFMonkey et choisissez l’action Generate Document.

Vous pouvez ensuite associer les données du formulaire aux variables de votre document. Assurez-vous d’utiliser les mêmes noms que ceux utilisés lors de l’écriture du modèle.

Nous sommes maintenant prêts à tester la génération du document.

Envoyer le document par email

Maintenant que notre document est généré, envoyons-le par email.

Ajoutez une nouvelle action et sélectionnez l’application Email by Zapier, puis choisissez l’action Send Outbound Email.

Nous pouvons maintenant utiliser l’URL de téléchargement de notre document comme pièce jointe de l’email. Zapier télécharge automatiquement le fichier et le joint.

Vous pouvez maintenant tester cette dernière action et vous devriez recevoir un email avec le document en pièce jointe.

Félicitations ! Vous avez généré votre tout premier document PDFMonkey avec Zapier !

Générer un document

L’action Generate Document crée un document à partir de l’un de vos modèles PDFMonkey. Vous sélectionnez un modèle, associez vos champs de données, et PDFMonkey génère le document. L’action renvoie une URL de téléchargement utilisable dans les étapes suivantes du Zap.

Pour un guide pas à pas de votre premier Zap, consultez la section Premiers pas ci-dessus.

Payload JSON avancé

Par défaut, l’intégration fournit un champ de mapping simple pour définir ce qui est envoyé à PDFMonkey. Dans la plupart des cas, le mapping simple est suffisant, mais il existe des situations où vous devez structurer vos données différemment. L’option Use a custom JSON structure bascule du mapping simple vers une zone de texte où vous pouvez insérer votre propre JSON avec des propriétés imbriquées :

Nom de fichier personnalisé

Vous pouvez spécifier un nom personnalisé pour le fichier généré. Cela est utile si vous prévoyez de stocker le document dans un service comme Drive ou Dropbox.

Vous pouvez utiliser des parties dynamiques pour construire le nom de fichier, mais gardez ces restrictions à l’esprit :

• Le nom de fichier ne doit contenir aucun slash / ni backslash \
• Les caractères non latins doivent être évités car ils peuvent être corrompus lors de l’enregistrement du fichier

Les noms courts basés sur des dates ou des identifiants fonctionnent généralement le mieux.

Métadonnées

Lorsque vous générez un document, vous pouvez y joindre des métadonnées. Les métadonnées ne sont pas disponibles dans le modèle et ne peuvent pas influencer le contenu du document ; elles y sont simplement attachées.

Un cas d’utilisation courant est la réception du document via un webhook et l’utilisation de ses métadonnées pour le router ou le traiter différemment.

Lignes de détail

Si vous générez une facture ou un devis, vous devrez probablement gérer des lignes de détail. Zapier offre un moyen d’accéder à ces éléments si le trigger que vous utilisez les prend en charge.

Prenons l’exemple d’une facture Stripe. Les éléments de la facture sont disponibles via une collection Line Items. Pour envoyer ces éléments de manière compréhensible pour PDFMonkey, définissez Add Line Items sur Yes.

Cela ouvre une section où vous spécifiez à quoi ressemble un seul élément. Par exemple, considérons une facture Stripe avec ces éléments :

Délicieuse gaufre          3.50€      x12      = 42.00€
Donut parfaitement rond    4.99€      x5       = 24.95€
TOTAL                                            66.95€

Le TOTAL doit être envoyé comme donnée de base du document, tandis que le nom, le prix unitaire, la quantité et le montant total de chaque élément doivent être envoyés comme lignes de détail depuis Zapier :

Utiliser les lignes de détail dans votre modèle

Lorsque Zapier envoie les lignes de détail à PDFMonkey, elles sont accessibles via une variable spéciale lineItems. Dans l’exemple ci-dessus, le payload ressemblerait à ceci :

{
  "lineItems": [
    {
      "product": "Delicious waffle",
      "quantity": "12",
      "unitPrice": "3.50",
      "totalAmount": "42.00"
    },
    {
      "product": "Perfectly round donut",
      "quantity": "5",
      "unitPrice": "4.99",
      "totalAmount": "24.95"
    }
  ]
}

Vous pouvez parcourir le tableau lineItems pour afficher le contenu de chaque élément individuellement :

{% for item in lineItems %}
  <p>{{item.product}} at {{item.unitPrice}}€ x{{item.quantity}} = {{item.totalAmount}}€</p>
{% endfor %}

Ce qui produit le HTML suivant :

<p>Delicious waffle at 3.50€ x12 = 42.00€</p>
<p>Perfectly round donut at 4.99€ x5 = 24.95€</p>

Vous voudrez probablement construire une ligne de tableau pour chaque élément, mais cela vous donne une bonne idée de la marche à suivre. Consultez Conditions et boucles pour d’autres techniques de boucles Liquid.

Trigger Document Generated

Le trigger Document Generated déclenche votre Zap chaque fois qu’un document termine sa génération (atteint le statut success). Cela est utile pour automatiser les tâches post-génération comme le stockage du fichier dans Dropbox, l’envoi par email ou l’enregistrement dans une feuille de calcul.

Vous pouvez choisir de déclencher votre Zap pour :

• N’importe quel modèle de votre workspace
• Un seul modèle
• Plusieurs modèles spécifiques

Assurez-vous d’avoir au moins un document généré avant de tester votre trigger dans Zapier.

Vous pouvez ensuite utiliser le fichier généré pour le stocker, l’envoyer par email ou être notifié d’une manière ou d’une autre.

Récupérer et supprimer des documents

Récupérer un document

L’action Retrieve Document récupère un document précédemment généré par son identifiant. Utilisez-la lorsque vous devez accéder aux détails d’un document ou à son URL de téléchargement dans une étape ultérieure de votre Zap ; par exemple, après un délai ou dans un workflow séparé de celui qui l’a généré.

Supprimer un document

L’action Delete Document supprime un seul document de PDFMonkey. Utilisez-la pour nettoyer les documents après les avoir traités ; par exemple, après avoir téléchargé et stocké le fichier ailleurs. Consultez Rétention et suppression pour en savoir plus sur la gestion du cycle de vie des documents.

Résolution de problèmes

URL de téléchargement expirée

Si vous obtenez une erreur d’URL de téléchargement expirée lors de la construction de votre Zap, rechargez l’enregistrement d’exemple dans votre trigger.

L’URL de téléchargement n’est valide que pendant 1 heure. Vous devez actualiser les documents dans Zapier pour obtenir une nouvelle URL. Cliquez sur le bouton Load More dans la section Test de votre trigger :

Réponses 422

Cette erreur survient généralement lorsque vous utilisez l’option JSON personnalisé et que des valeurs nécessitent un échappement avant d’être envoyées à PDFMonkey.

Valeurs contenant des guillemets doubles

Considérons le JSON personnalisé suivant :

{
  "user": {
    "name": "(Dynamic Field From Zapier)"
  }
}

Si la valeur dans Dynamic Field From Zapier contient des guillemets, le JSON résultant est cassé. Prenons Peter "Spiderman" Parker comme exemple :

{
  "user": {
    "name": "Peter "Spiderman" Parker"
  }
}

Ce n’est pas du JSON valide. Ce dont vous avez besoin, c’est d’échapper les guillemets doubles :

{
  "user": {
    "name": "Peter \"Spiderman\" Parker"
  }
}

Valeurs contenant des sauts de ligne

Le JSON ne prend pas en charge les valeurs contenant des sauts de ligne bruts :

{
  "userBio": "Once upon a time,
They lived happily ever after."
}

Échappez les sauts de ligne en les remplaçant par une balise <br /> ou en utilisant la représentation textuelle \n :

{
  "userBio": "Once upon a time,\nThey lived happily ever after."
}

Solution

Si vous ne pouvez pas échapper les valeurs avant qu’elles n’arrivent dans Zapier, ajoutez une action Code by Zapier avant d’appeler PDFMonkey.

Supposons que vos données contiennent à la fois des sauts de ligne et des guillemets doubles :

Vous devez échapper les valeurs pour Trigger App User Bio et Trigger App User Full Name. Commencez par ajouter une action Code by Zapier à votre Zap et sélectionnez Run Javascript :

Donnez à vos champs des noms qui permettent de les identifier facilement dans les étapes suivantes :

Ajoutez maintenant le code qui échappe les valeurs :

let data = Object.assign({}, inputData);

for (let key in data) {
  if (typeof(data[key]) === "string" && data[key].length > 0) {
    data[key] = data[key].replace(/\r?\n/g, '<br>').replace(/\t/g, " ").replace(/"/g, '\\\"');
  }
}

output = [data];

Cela vous donne les mêmes champs en sortie mais avec leurs valeurs correctement échappées :

Vous pouvez maintenant utiliser ces valeurs lors de la construction de votre payload PDFMonkey :

Notez que nous avons utilisé les champs de l’étape Code by Zapier, et non ceux du trigger directement.

Étapes suivantes

• De zéro à votre premier document : créer votre compte PDFMonkey et votre premier modèle
• Définir les données dynamiques : structurer le payload JSON pour vos modèles
• Statuts des documents : comprendre le cycle de vie d’un document généré
• Webhooks : recevoir des notifications en temps réel à la fin de la génération
• Découvrir d’autres intégrations : Make, n8n, Workato