# Intégration Zapier : générer des 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](#getting-started) ci-dessous pour un tutoriel complet de bout en bout.

## Premiers pas {#getting-started}

<iframe width="100%" height="400" src="https://www.youtube.com/embed/yLMBYxehDMg" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen></iframe>

Avant de commencer, assurez-vous d’avoir un compte PDFMonkey et un modèle publié. Consultez [De zéro à votre premier document](../premiers-pas/de-zero-a-votre-premier-document.md) pour les instructions de configuration.

### Écrire votre premier modèle

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

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

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

```css
.greeting {
  color: #6d28d9;
  font-size: 24px;
}
```

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

```json
{
  "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.

> [!WARNING]
> **Publiez toujours votre modèle !**
>
> Oublier de publier votre modèle est une erreur fréquente, surtout lorsque vous alternez entre Zapier et PDFMonkey. Si les documents générés ne correspondent pas à votre modèle, vérifiez toujours que vous l’avez bien publié.


### 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](https://tally.so/), 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 :

![Formulaire Tally utilisé comme trigger du Zap](../img/zapier-guide-select-pdfmonkey.webp)

#### Configurer votre Zap

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

![Création d’un nouveau Zap avec un trigger Tally](../img/zapier-guide-create-document.webp)

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

![Sélection du modèle PDFMonkey](../img/zapier-guide-select-template.webp)

![Connexion de votre compte PDFMonkey](../img/zapier-guide-connect-account.webp)

#### 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**.

![Mapping des champs dans l’action PDFMonkey](../img/zapier-guide-map-fields.webp)

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.

![Test de l’action PDFMonkey](../img/zapier-guide-test-action.webp)

> [!NOTE]
> **Nommage des variables**
>
> Si vous vous demandez comment écrire des noms corrects pour qu’ils fonctionnent dans PDFMonkey, nous fournissons [une liste de formats de noms de variables corrects/incorrects](../modeles-code/definir-des-donnees-dynamiques.md#naming-your-variables).


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

![Document créé avec succès](../img/zapier-guide-document-created.webp)

![Téléchargement du document généré](../img/zapier-guide-download-pdf.webp)

#### 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**.

![Configuration de l’action d’envoi d’email](../img/zapier-guide-send-email.webp)

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.

![Le Zap complet du trigger à l’email](../img/zapier-guide-final-zap.webp)

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 {#generate-a-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](../generation-de-documents/url-de-telechargement.md) utilisable dans les étapes suivantes du Zap.

Pour un guide pas à pas de votre premier Zap, consultez la section [Premiers pas](#getting-started) ci-dessus.

### Payload JSON avancé {#advanced-json}

> [!WARNING]
> **Attention !**
>
> Un grand pouvoir implique parfois de grands problèmes. Ne passez au JSON avancé que si vous savez ce que vous faites et savez comment échapper correctement vos données.
> 
> Consultez la section [Résolution de problèmes](#troubleshooting) pour plus d’informations.


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 :

![Option de payload JSON personnalisé dans l’action PDFMonkey Zapier](../img/zapier-custom-json-payload.webp)

### Nom de fichier personnalisé {#custom-filename}

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.

> [!TIP]
> Pour plus de détails sur les options de nom de fichier (y compris la définition via l’API), consultez [Nom de fichier personnalisé](../generation-de-documents/nom-de-fichier-personnalise.md).


### Métadonnées {#metadata}

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](../generation-de-documents/webhooks.md) et l’utilisation de ses métadonnées pour le router ou le traiter différemment.

![Champs de métadonnées dans l’action PDFMonkey Zapier](../img/zapier-metadata-fields.webp)

### Lignes de détail {#line-items}

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 :

![Mapping des lignes de détail dans l’action PDFMonkey Zapier](../img/zapier-line-items-mapping.webp)

> [!TIP]
> **Mapping ou JSON**
>
> Le champ pour définir les données d’une ligne de détail utilise le même formulaire que les données principales. Si vous utilisez le [JSON avancé](#advanced-json) pour les données principales, le payload de la ligne de détail est également défini en JSON avancé.


#### 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 :

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

> [!NOTE]
> **Uniquement des chaînes de caractères**
>
> Si vous observez attentivement le payload ci-dessus, seules des chaînes de caractères sont envoyées. Zapier ne différencie pas le texte et les nombres.
> 
> Heureusement, Liquid (le langage de template que nous utilisons) est suffisamment intelligent pour convertir ces valeurs en nombres lorsque vous effectuez des calculs. Gardez simplement cela à l’esprit si vous rencontrez des problèmes avec les nombres. Consultez [Comment faire des calculs](../modeles-code/comment-faire-des-calculs.md) pour des astuces arithmétiques.


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

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

Ce qui produit le HTML suivant :

```html title="HTML"
<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](../modeles-code/conditions-et-boucles.md) pour d’autres techniques de boucles Liquid.

## Trigger Document Generated {#document-generated-trigger}

Le trigger **Document Generated** déclenche votre Zap chaque fois qu’un document termine sa génération (atteint le [statut](../generation-de-documents/statuts-des-documents.md) `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.

![Sélection de l’événement Document Generated dans Zapier](../img/zapier-trigger-select-event.webp)

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

![Connexion de votre compte PDFMonkey dans le trigger](../img/zapier-trigger-connect-account.webp)

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

![Sélection du modèle sur lequel déclencher](../img/zapier-trigger-select-template.webp)

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.

> [!NOTE]
> **Exploiter les métadonnées**
>
> Le document exposé par le trigger ne contient pas votre payload. Si vous avez besoin d’informations dans les actions suivantes, nous recommandons de [joindre des métadonnées](#metadata) au document.
> 
> C’est ce que nous avons fait avec les informations Tally dans cet exemple.


![Résultat du test montrant la sortie du trigger](../img/zapier-trigger-test-result.webp)

## Retrouver et supprimer des documents {#retrieve-and-delete}

### Retrouver un document {#récupérer-un-document}

La recherche **Find Document** récupère un document précédemment généré à partir de son identifiant (**Document ID**). Utilisez-la lorsque vous devez accéder aux détails d’un document ou à son [URL de téléchargement](../generation-de-documents/url-de-telechargement.md) 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](../generation-de-documents/conservation-et-suppression.md) pour en savoir plus sur la gestion du cycle de vie des documents.

## Résolution de problèmes {#troubleshooting}

### URL de téléchargement expirée {#download-url-expired}

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](../generation-de-documents/url-de-telechargement.md) 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 :

![Actualisation des champs du trigger pour obtenir une nouvelle URL de téléchargement](../img/zapier-refresh-trigger-fields.webp)

> [!NOTE]
> **Sortie de génération**
>
> Cette astuce ne s’applique qu’au trigger. Pour la sortie d’une action Generate Document, vous devez générer un nouveau document pour obtenir des données fraîches et une URL de téléchargement valide.


> [!TIP]
> Si vos Zaps échouent parce que l’URL a expiré avant qu’une étape ultérieure ne s’exécute, consultez [L’URL de téléchargement renvoie une erreur 403](../depannage/l-url-de-telechargement-renvoie-403.md) pour des solutions.


### Réponses 422 {#422-responses}

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 :

```json5 title="Custom JSON"
{
  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 :

```json title="JSON invalide"
{
  "user": {
    "name": "Peter "Spiderman" Parker"
  }
}
```

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

```json title="JSON valide"
{
  "user": {
    "name": "Peter \"Spiderman\" Parker"
  }
}
```

> [!NOTE]
> **Attributs HTML**
>
> Si vous envoyez du HTML, cela arrive fréquemment car les attributs utilisent presque toujours des guillemets doubles (par ex., `<div class="test">`).


#### Valeurs contenant des sauts de ligne

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

```json title="JSON invalide"
{
  "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` :

```json title="JSON valide"
{
  "userBio": "Once upon a time,\nThey lived happily ever after."
}
```

#### Solution {#escaping-solution}

> [!NOTE]
> **Avez-vous vraiment besoin du JSON personnalisé ?**
>
> La première question à vous poser est de savoir si vous avez vraiment besoin du JSON personnalisé. Dans la plupart des cas, l’approche par mapping simple est suffisante et gère l’échappement automatiquement.


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 :

| Élément                        | Valeur                                                                                                                                                                                   |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Trigger App User Bio**       | <p>This is the bio of the user.</p><p>It’s a free form text that the user can edit so it can contain line breaks.</p><p><br />It could even be split in a few paragraphs... why not?</p> |
| **Trigger App User Name**      | Peter Parker                                                                                                                                                                             |
| **Trigger App User Full Name** | Peter "Spiderman" Parker                                                                                                                                                                 |

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** :

![Ajout d’une action Code by Zapier avec les données brutes en entrée](../img/zapier-error-422-raw-body.webp)

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

![Nommage des champs d’entrée dans Code by Zapier](../img/zapier-error-422-json-format.webp)

Ajoutez maintenant le code qui échappe les valeurs :

```javascript title="Code by Zapier"
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 :

![La sortie échappée de Code by Zapier](../img/zapier-error-422-custom-request.webp)

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

![Utilisation des valeurs échappées dans l’action PDFMonkey](../img/zapier-error-422-fixed-payload.webp)

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

## Étapes suivantes {#next-steps}

- [De zéro à votre premier document](../premiers-pas/de-zero-a-votre-premier-document.md) : créer votre compte PDFMonkey et votre premier modèle
- [Définir les données dynamiques](../modeles-code/definir-des-donnees-dynamiques.md) : structurer le payload JSON pour vos modèles
- [Statuts des documents](../generation-de-documents/statuts-des-documents.md) : comprendre le cycle de vie d’un document généré
- [Webhooks](../generation-de-documents/webhooks.md) : recevoir des notifications en temps réel à la fin de la génération
- Découvrir d’autres intégrations : [Make](./make.md), [n8n](./n8n.md), [Workato](./workato.md)
