Générer un document via notre API
Bibliothèques
À ce jour, nous mettons à disposition les bibliothèques suivantes :
Authentification
Pour générer une document via l’API, vous aurez besoin d’une CLÉ d’API.
Visitez la page Mon compte grâce au menu en haut à droite.
Affichez votre CLÉ D’API en cliquant sur le lien Afficher la valeur en dessous du champ CLÉ SECRÈTE et copiez-la.
Vous pouvez utiliser cette clé pour authentifier vos appels d’API :
# Méthode 1 : Utilisez la variable d’environment PDFMONKEY_PRIVATE_KEY.
# Aucun code nécessaire.
# Méthode 2 : Réglez la clef privée manuellement
# (ce code sera généralement dans un initializer)
Pdfmonkey.configure do |config|
config.private_key = '[CLÉ D’API]'
end
curl 'https://api.pdfmonkey.io/api/v1/documents' \
-H 'Authorization: Bearer [CLÉ D’API]'
Récupérez l’ID de votre modèle
Chaque modèle a un ID unique que vous pouvez copier dans la page Modèles :
Vous pouvez maintenant générer un document !
Générer un document
Voici un exemple de code permettant de générer un document :
template_id = '[ID MODÈLE]'
data = { nom: 'Jeanne Machin' }
# Attendez automatiquement la génération avec `generate!`
document = Pdfmonkey::Document.generate!(template_id, data)
document.status
#=> "success"
# Ou attendez manuellement avec `generate`
document = Pdfmonkey::Document.generate(template_id, data)
until document.done?
puts 'Pause pour 1s…'
sleep 1
document.reload!
end
document.status
#=> "success"
# IMPORTANT !
# Le statut "pending" indique à PDFMonkey que la génération doit être lancée dès la création du document.
# N’oubliez pas de l’ajouter !
curl 'https://api.pdfmonkey.io/api/v1/documents' \
-H 'Authorization: Bearer [CLÉ D’API]' \
-H 'Content-Type: application/json' \
-d '{
"document": {
"document_template_id": "[ID MODÈLE]",
"payload": "{ \"nom\": \"Jeanne Machin\" }",
"status": "pending"
}
}'
Veillez à bien remplacer [CLÉ D’API] et [ID MODÈLE] par les valeurs correspondantes.
L’objet Document
Voici le document que vous aurez en retour :
#<Pdfmonkey::Document
id="d2f2de44-9de7-4dd8-90f4-bee5e99c9984"
status="generating"
app_id="e87c71ac-06c2-473c-a49b-98794a340255"
checksum="7ddb1dc96435ec5f58b31db23b43cfcf"
created_at="2042-01-02T01:23:45.678+02:00"
document_template_id="[ID MODÈLE]"
download_url="https://..."
errors=nil
meta=nil
payload="{\"nom\":\"Jeanne Machin\"}"
preview_url="https://..."
updated_at="2042-01-02T01:23:46.012+02:00">
{
"document" : {
"id": "d2f2de44-9de7-4dd8-90f4-bee5e99c9984",
"status": "generating",
"app_id": "e87c71ac-06c2-473c-a49b-98794a340255",
"checksum": "7ddb1dc96435ec5f58b31db23b43cfcf",
"created_at": "2042-01-02T01:23:45.678+02:00",
"document_template_id": "[ID MODÈLE]",
"download_url": "https://...",
"errors": null,
"meta": null,
"payload": "{\"nom\":\"Jeanne Machin\"}",
"preview_url": "https://...",
"updated_at": "2042-01-02T01:23:46.012+02:00"
}
}
Statuts
Voici la liste exhaustive des statuts possibles :
- draft
- Le document peut être prévisualisé et modifié
- pending
- Le document a été ajouté à la file d’attente de génération
- generating
- Le document est en cours de génération
- success
- Le document a été généré et peut maintenant être télécharger
- failure
- La génération a échoué
Attendre la génération
Pour vérifier si la génération d’un document est terminée, appelez de nouveau l’API :
# Rafraîchit les données du document.
document.reload!
document.status
# => "generating"
# Vous pouvez rafraîchir le document jusqu’à obtenir un statut "success" ou "failure"
# indiquant que la génératin est terminée.
until document.done?
document.reload!
end
document.status
# => "success"
curl 'https://api.pdfmonkey.io/api/v1/documents/d2f2de44-9de7-4dd8-90f4-bee5e99c9984' \
-H 'Authorization: Bearer [CLÉ D’API]'
# Vous obtiendrez le même contenu.
# Recommencez jusqu'à obtenir le statut "success" ou "failure".
Lorsque le document est généré, il contient une propriété download_url
.
Cette URL est valide pour 30 secondes, une fois ce délai passé vous devrez appeler de nouveau l’API pour en obtenir une nouvelle.
Suivez l’URL contenue dans download_url
pour télécharger votre document. Et voilà !
Personnaliser le nom du fichier généré
Lorsque vous générez un Document grâce à l’API, vous avez la possibilité de personnaliser le nom du fichier généré. Cela peut être particulièrement utile lorsque vous souhaitez envoyer ce Document par email ou le sauvegarder dans Dropbox par exemple.
Pour ce faire, ajoutez la propriété _filename
aux meta
données du Document :
template_id = '[TEMPLATE ID]'
data = { name: 'Jeanne Machin' }
meta = { _filename: 'pdf-de-jeanne-machin.pdf' }
# Le paramètre meta a été ajouté dans la v0.4.0 de la gem pdfmonkey
document = Pdfmonkey::Document.generate!(template_id, data, meta)
curl 'https://api.pdfmonkey.io/api/v1/documents' \
-H 'Authorization: Bearer [API KEY]' \
-H 'Content-Type: application/json' \
-d '{
"document": {
"document_template_id": "[TEMPLATE ID]",
"meta": "{ \"_filename\": \"pdf-de-jeanne-machin.pdf\" }",
"payload": "{ \"name\": \"Jeanne Machin\" }",
"status": "pending"
}
}'