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, ajouté 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"
        }
      }'