Documentation

1Concept général de la gestion des documents

Nous pouvons également gérer des documents pour vous et les envoyer à vos clients. Il existe plusieurs raisons pour lesquelles vous souhaiteriez utiliser cette fonctionnalité :

  1. Si votre application ne dispose d’aucune fonctionnalité pour créer des documents PDF, vous pouvez simplement utiliser la nôtre et vous n’avez plus à vous en soucier.

  2. Si votre application ne peut pas envoyer les documents PDF par e-mail aux clients.

  3. Nous avons constaté que la gestion des documents et surtout leur adaptation est souvent un véritable casse-tête. Nous vous proposons donc un moyen simple et pratique d’adapter vos documents à votre modèle.

  4. Certains processeurs de paiement ont des exigences très spécifiques concernant l’apparence ainsi que les informations de paiement qui doivent faire partie du document. Pour de nombreux paniers d’achat, adapter la génération des documents ne peut se faire sans écraser des fichiers centraux.

Note
La gestion des documents peut être configurée dans la configuration du connecteur. Pour la désactiver, rendez-vous sur Space > Paiement > Configuration > Connecteurs.

2Processus de rendu

Lorsque nous effectuons le rendu du document, nous le rendons d’abord au format HTML puis le convertissons en PDF et l’envoyons au client.

3Créer des modèles de document

En général, vous avez deux options. Soit vous créez vos propres modèles de document pour les factures, bons de livraison, etc. Soit vous commencez à écraser les fichiers existants. Cependant, dans ce cas, vous ne pouvez utiliser qu’une seule version active pour les différents modèles. En d’autres termes, vous ne pouvez alors avoir qu’un modèle de facture spécifique, un modèle de bon de livraison, etc.

Cependant, si vous souhaitez internationaliser ou attribuer un modèle différent à un connecteur spécifique, vous devez commencer à créer des modèles. Des modèles peuvent être créés pour toutes sortes de types de document différents sous Space > Personnaliser > Modèles de documents. Si vous cliquez sur créer un document, il vous sera demandé quel type de document vous souhaitez créer. En fonction du type, vous pouvez définir des entités supplémentaires. Sélectionnez dans l’éditeur de ressources le fichier de modèle qui doit être utilisé. Une fois le modèle créé, vous pouvez choisir de l’utiliser pour des connecteurs, etc.

Notification d'abonnement Slack
Figure 1. Créez un modèle de document dans votre Space sous Space > Personnaliser > Modèles de documents.

4Personnalisation

Pour rendre la communication avec vos clients plus personnelle, vous souhaiterez peut-être personnaliser les modèles de vos documents (par exemple en ajoutant un logo ou le style graphique de votre entreprise). Vous pouvez facilement le faire soit en téléchargeant votre modèle, soit en en créant un nouveau dans les ressources.

Les modèles sont écrits dans le langage twig. Vous trouverez ci-dessous quelques informations générales sur la manière dont vous pouvez personnaliser vos documents. Une documentation plus détaillée sur la manière d’utiliser twig est disponible dans notre documentation twig.

4.1Structure des ressources

Toutes les ressources liées à l’apparence des documents se trouvent dans le dossier document de l’éditeur de ressources :

  • css-folder: Contient tous les fichiers CSS utilisés pour styliser vos modèles. Nous utilisons un langage .twig spécifique pour styliser les documents.

  • fonts-folder: Dans le dossier fonts, vous pouvez stocker les polices spécifiques que vous souhaitez appliquer à vos documents (veillez à en préciser l’utilisation dans le fichier CSS).

  • images-folder: Contient les images des documents, y compris le PDF d’arrière-plan. Le PDF d’arrière-plan contient l’arrière-plan statique de votre document. Les autres éléments sont imprimés par-dessus ce PDF. L’arrière-plan utilisé est également spécifié dans le fichier CSS.

  • template-folder: Le dossier template contient le modèle .twig des documents.

Note
Si vous téléchargez des fichiers, vous acceptez explicitement que vous possédez les droits de propriété intellectuelle nécessaires pour partager les fichiers avec nous. Nous vous garantissons que les ressources ne sont accessibles qu’aux utilisateurs qui ont accès à votre Space.

4.2Options de style spécifiques aux documents

Vous trouverez ici quelques informations générales utiles sur la manière de styliser vos documents. Une documentation plus détaillée sur la manière d’utiliser twig est disponible dans notre documentation twig.

4.2.1Utiliser des polices personnalisées dans les documents

Il est possible d’utiliser des polices spécifiques dans vos modèles. Pour ce faire, téléchargez vos fichiers .ttf dans le dossier des polices et assurez-vous d’inclure les fichiers dans le CSS.

Voici un exemple :

@font-face {
    font-family: "OpenSans";
    font-weight: normal;
    src: url('resource:/document/fonts/OpenSans-Regular.ttf');
    -fs-pdf-font-embed: embed;
    -fs-pdf-font-encoding: Identity-H;
}

4.2.2Modifier le modèle d’arrière-plan du document

Lors de la création du document, nous imprimons le contenu dynamique par-dessus le document d’arrière-plan qui est défini dans le fichier /documents/css/base.css de votre Space. Le modèle est utilisé pour tous les documents.

@page {
	background-image: url('resource:/document/images/document-background.pdf');
	padding: 0;

	/* Border of the Document */
	margin:  30mm 10mm 20mm 10mm;
	size: A4;
}

Afin d’adapter le document à vos besoins, vous pouvez soit modifier le chemin ici, soit écraser le fichier sous /document/images/document-background.pdf par votre propre modèle de document. Il est également possible d’avoir un modèle différent pour la première page et toutes les pages suivantes. Pour ce faire, vous devez ajouter le sélecteur @page:first à votre fichier base.css.

@page {
	background-image: url('resource:/document/images/document-background.pdf');
	padding: 0;

	/* Border of the Document */
	margin:  30mm 10mm 20mm 10mm;
	size: A4;
}

@page:first {
	background-image: url('resource:/document/images/first-document-background.pdf');
}

Cela utilisera le document-background.pdf pour les pages suivantes et le first-document-background.pdf pour la première page.

4.2.3Utiliser des variables dans les modèles

Vous pouvez utiliser des variables dans vos fichiers de modèle. Toutes les variables disponibles dans le contexte respectif sont affichées dans l’éditeur de ressources dans l’onglet inférieur, y compris une description des variables. Vous pouvez utiliser la syntaxe twig pour interpréter ces variables. Une documentation plus détaillée sur la manière d’utiliser twig est disponible dans notre documentation twig.

Notification d'abonnement Slack
Figure 2. Les variables disponibles dans le contexte sont affichées dans la barre inférieure de l’éditeur de ressources.