Générer un document via notre API

# Bibliothèques

À ce jour, nous mettons à disposition les bibliothèques suivantes :

• Ruby

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

• Ruby
• cURL

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

• Ruby
• cURL

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"
        }
      }'

# L’objet Document

Voici le document que vous aurez en retour :

• Ruby
• cURL

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

• Ruby
• cURL

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

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 :

• Ruby
• cURL

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"
        }
      }'

Générer un document dans votre Dashboard Webhooks