Ruby SDK

Dernière mise à jour le 23 mars 2026

Nous fournissons un SDK Ruby pour se connecter à PDFMonkey. Ce gem est le moyen le plus rapide d’utiliser notre API avec Ruby.

GitHub : https://github.com/pdfmonkey/pdfmonkey-ruby

Installation

Ajoutez cette ligne au Gemfile de votre application :

gem 'pdfmonkey'

Puis exécutez :

$ bundle

Ou installez-le directement :

$ gem install pdfmonkey

Utilisation

Configuration de l’authentification

Utilisation de la variable d’environnement par défaut

PDFMonkey recherche la variable d’environnement PDFMONKEY_PRIVATE_KEY. Cette variable doit contenir votre clé privée obtenue sur https://dashboard.pdfmonkey.io/account.

PDFMONKEY_PRIVATE_KEY=j39ckj4…

Configuration manuelle des identifiants

Vous pouvez configurer vos identifiants explicitement dans votre application :

Pdfmonkey.configure do |config|
  config.private_key = 'j39ckj4…'
end

Identifiants par requête

La configuration est globale. Si vous avez besoin d’identifiants par requête (par ex. en multi-tenant), utilisez with_adapter :

config = Pdfmonkey::Configuration.new
config.private_key = 'tenant-specific-key'

adapter = Pdfmonkey::Adapter.new(config: config)

Pdfmonkey.with_adapter(adapter) do
  Pdfmonkey::Document.generate!(
    document_template_id: 'b13ebd75-…',
    payload: { name: 'John Doe' }
  )
end

Toutes les opérations à l’intérieur du bloc utilisent l’adapter fourni. Les appels en dehors du bloc continuent d’utiliser la configuration globale.

Documents

Génération synchrone

Si vous souhaitez attendre la fin de la génération d’un document avant de poursuivre votre flux de travail, utilisez la méthode generate!. Elle envoie une demande de génération et attend le succès ou l’échec avant de vous donner une réponse.

document = Pdfmonkey::Document.generate!(
  document_template_id: 'b13ebd75-d290-409b-9cac-8f597ae3e785',
  payload: { name: 'John Doe' }
)

document.status       # => 'success'
document.download_url # => 'https://…'

L’URL de téléchargement est temporaire

L’URL de téléchargement d’un document n’est valide que pendant 1 heure. Passé ce délai, rechargez le document pour en obtenir une nouvelle :

document.reload!

Génération asynchrone

PDFMonkey a été conçu avec un flux de travail asynchrone en tête. Il fournit des webhooks pour vous informer du succès ou de l’échec de la génération d’un document.

Pour tirer parti de ce comportement et continuer à travailler pendant la génération de votre document, utilisez la méthode generate :

document = Pdfmonkey::Document.generate(
  document_template_id: 'b13ebd75-d290-409b-9cac-8f597ae3e785',
  payload: { name: 'John Doe' }
)

document.status       # => 'pending'
document.download_url # => nil

Si vous avez configuré une URL de webhook, elle sera appelée avec votre document une fois la génération terminée. Vous pouvez la simuler pour vos tests avec la commande cURL suivante :

curl <url de votre application> \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
        "document": {
          "id": "76bebeb9-9eb1-481a-bc3c-faf43dc3ac81",
          "app_id": "d9ec8249-65ae-4d50-8aee-7c12c1f9683a",
          "created_at": "2020-01-02T03:04:05.000+01:00",
          "document_template_id": "f7fbe2b4-a57c-46ee-8422-5ae8cc37daac",
          "meta": "{\"_filename\":\"my-doc.pdf\"}",
          "output_type": "pdf",
          "status": "success",
          "updated_at": "2020-01-02T03:04:15.000+01:00",
          "xml_data": null,
          "payload": "{\"name\": \"John Doe\"}",
          "download_url": "https://example.com/76bebeb9-9eb1-481a-bc3c-faf43dc3ac81.pdf",
          "checksum": "ac0c2b6bcc77e2b01dc6ca6a9f656b2d",
          "failure_cause": null,
          "filename": "my-doc.pdf",
          "generation_logs": [],
          "preview_url": "https://preview.pdfmonkey.io/pdf/web/viewer.html?file=…",
          "public_share_link": "https://example.com/76bebeb9-9eb1-481a-bc3c-faf43dc3ac81.pdf"
        }
      }'

Documents brouillons

Vous pouvez créer un document brouillon qui ne sera pas mis en file d’attente pour la génération.

C’est utile pour intégrer un aperçu via preview_url avant de déclencher la génération. C’est ce que nous faisons dans le tableau de bord PDFMonkey pour vous montrer un aperçu de votre document avant de le générer, en utilisant une iframe.
draft = Pdfmonkey::Document.create_draft(
  document_template_id: 'b13ebd75-d290-409b-9cac-8f597ae3e785',
  payload: { name: 'John Doe' }
)
draft.status      # => 'draft'
draft.preview_url # => 'https://…'

# Quand vous êtes prêt, déclenchez la génération et attendez la fin :
draft.generate!
draft.status       # => 'success'
draft.download_url # => 'https://…'

# Ou déclenchez la génération sans attendre :
draft.generate
draft.status # => 'pending'

Joindre des métadonnées

En plus du payload du document, vous pouvez ajouter des métadonnées lors de la génération. Passez l’argument meta: aux méthodes generate! et generate :

meta = {
  _filename: 'john-doe-contract.pdf',
  client_id: '123xxx123'
}

document = Pdfmonkey::Document.generate!(
  document_template_id: template_id,
  payload: payload,
  meta: meta
)
document.meta
# => '{"_filename":"john-doe-contract.pdf","client_id":"123xxx123"}'

document = Pdfmonkey::Document.generate(
  document_template_id: template_id,
  payload: payload,
  meta: meta
)
document.meta
# => '{"_filename":"john-doe-contract.pdf","client_id":"123xxx123"}'

Génération d’images

La génération d’images suit le même flux API que la génération de PDF. L’attribut output_type du template indique s’il produit une sortie 'pdf' ou 'image'. Les options spécifiques aux images sont passées via le paramètre meta :

doc = Pdfmonkey::Document.generate!(
  document_template_id: template_id,
  payload: payload,
  meta: {
    _type: 'png',       # webp (défaut), png ou jpg
    _width: 800,        # pixels
    _height: 600,       # pixels
    _quality: 80        # webp uniquement, défaut 100
  }
)
doc.download_url # => URL vers l’image générée

Mettre à jour un document

document.update!(status: 'pending')

Lister les documents

cards = Pdfmonkey::Document.list_cards(page: 1, status: 'success')

cards.each do |card|
  puts card.id
  puts card.status
end

cards.current_page # => 1
cards.total_pages  # => 5

# Naviguer entre les pages
next_cards = cards.next_page
prev_cards = cards.prev_page

Vous pouvez filtrer par document_template_id:, status:, workspace_id: et updated_since:.

Récupérer un document

Préférez `fetch_card` à `fetch`

Récupérer un document complet inclut son payload, ce qui peut représenter un volume important selon les données fournies. Nous recommandons fortement d’utiliser uniquement fetch_card sauf si vous avez une raison spécifique de récupérer le document complet.

Vous pouvez récupérer un document existant avec .fetch (ou son alias explicite .fetch_full) :

document = Pdfmonkey::Document.fetch('76bebeb9-9eb1-481a-bc3c-faf43dc3ac81')

Pour récupérer uniquement la représentation légère (recommandé) :

card = Pdfmonkey::Document.fetch_card('76bebeb9-9eb1-481a-bc3c-faf43dc3ac81')

Supprimer un document

Vous pouvez supprimer un document existant avec la méthode .delete :

Pdfmonkey::Document.delete('76bebeb9-9eb1-481a-bc3c-faf43dc3ac81')
#=> true

Vous pouvez également appeler la méthode #delete! sur une instance de document :

document.delete!
#=> true

Gestion des erreurs

Les erreurs API et les erreurs réseau lèvent des exceptions :

begin
  document = Pdfmonkey::Document.generate(
    document_template_id: template_id,
    payload: data
  )
rescue Pdfmonkey::ApiError => e
  e.message     # => "Document template must exist"
  e.errors      # => ["Document template must exist"]
  e.status_code # => 422
rescue Pdfmonkey::ConnectionError => e
  e.message # => "Failed to open TCP connection to api.pdfmonkey.io:443 ..."
end

Lors de l’utilisation de generate!, une exception supplémentaire peut être levée si le statut du document est 'error' ou 'failure' :

begin
  document = Pdfmonkey::Document.generate!(
    document_template_id: template_id,
    payload: data
  )
rescue Pdfmonkey::GenerationError => e
  e.message  # => "Document generation failed: Template error"
  e.document # => #<Pdfmonkey::Document …> (le document en échec)
end

Toutes les classes d’exception héritent de Pdfmonkey::Error, ce qui permet de les intercepter de manière générale :

begin
  document = Pdfmonkey::Document.generate!(
    document_template_id: template_id,
    payload: data
  )
rescue Pdfmonkey::Error => e
  puts "Une erreur est survenue : #{e.message}"
end

Templates

Récupérer un template

Les templates complets peuvent être volumineux

Récupérer un template complet inclut son body et ses paramètres, qui peuvent être volumineux. Utilisez list_cards quand vous n’avez besoin que des métadonnées.
template = Pdfmonkey::Template.fetch('b13ebd75-d290-409b-9cac-8f597ae3e785')
template.identifier # => 'my-invoice'
template.body       # => '<h1>Invoice</h1>…'  (version publiée)
template.body_draft # => '<h1>Invoice v2</h1>…'  (version brouillon)

Vous pouvez aussi utiliser l’alias explicite .fetch_full :

template = Pdfmonkey::Template.fetch_full('b13ebd75-d290-409b-9cac-8f597ae3e785')

Créer un template

Lors de la création d’un template, les attributs comme body, scss_style, settings, sample_data et pdf_engine_id sont automatiquement écrits dans leurs équivalents brouillons (body_draft, scss_style_draft, etc.) :

template = Pdfmonkey::Template.create(
  identifier: 'my-invoice',
  body: '<h1>Invoice</h1>'
)
template.body_draft # => '<h1>Invoice</h1>'

Mettre à jour un template

Comme create, update! écrit dans les champs brouillons :

template.update!(body: '<h1>Updated Invoice</h1>')
template.body_draft # => '<h1>Updated Invoice</h1>'

Publier un template

Une fois satisfait du brouillon, publiez-le pour copier tous les champs brouillons vers leurs équivalents publiés :

template.publish!
template.body # => '<h1>Updated Invoice</h1>'

Lister les templates

cards = Pdfmonkey::Template.list_cards(workspace_id: 'f4ab650c-…')

Supprimer un template

Pdfmonkey::Template.delete('b13ebd75-…')
# ou
template.delete!

Template Folders

# Lister les dossiers
folders = Pdfmonkey::TemplateFolder.list

# Créer un dossier
folder = Pdfmonkey::TemplateFolder.create(identifier: 'invoices')

# Récupérer un dossier
folder = Pdfmonkey::TemplateFolder.fetch('folder-id')

# Mettre à jour un dossier
folder.update!(identifier: 'receipts')

# Supprimer un dossier
Pdfmonkey::TemplateFolder.delete('folder-id')
# ou
folder.delete!

Pour créer un template dans un dossier spécifique, passez le template_folder_id :

folder = Pdfmonkey::TemplateFolder.create(identifier: 'invoices')

template = Pdfmonkey::Template.create(
  identifier: 'monthly-invoice',
  body: '<h1>Invoice</h1>',
  template_folder_id: folder.id
)

Snippets

Les snippets sont des composants HTML réutilisables qui peuvent être inclus dans les templates.

# Lister les snippets
snippets = Pdfmonkey::Snippet.list

# Créer un snippet
snippet = Pdfmonkey::Snippet.create(
  identifier: 'header',
  code: '<div class="header">…</div>',
  workspace_id: 'f4ab650c-…'
)

# Récupérer un snippet
snippet = Pdfmonkey::Snippet.fetch('snippet-id')

# Mettre à jour un snippet
snippet.update!(code: '<div class="header">Updated</div>')

# Supprimer un snippet
Pdfmonkey::Snippet.delete('snippet-id')
# ou
snippet.delete!

Workspaces

Les workspaces sont des ressources en lecture seule. Ils peuvent être listés et récupérés, mais pas créés, mis à jour ou supprimés via l’API.

# Lister les workspaces
workspaces = Pdfmonkey::Workspace.list_cards

workspaces.each do |workspace|
  puts workspace.identifier
end

# Récupérer un workspace
workspace = Pdfmonkey::Workspace.fetch('workspace-id')
workspace.identifier # => 'my-app'

Webhooks

Les webhooks vous permettent de recevoir des notifications lorsque des documents sont générés.

# Créer un webhook pour tous les templates d’un workspace
webhook = Pdfmonkey::Webhook.create(
  url: 'https://example.com/webhooks/pdfmonkey',
  event: 'document.generation.completed',
  workspace_id: 'f4ab650c-…'
)

# Restreindre optionnellement à certains templates
webhook = Pdfmonkey::Webhook.create(
  url: 'https://example.com/webhooks/pdfmonkey',
  event: 'document.generation.completed',
  workspace_id: 'f4ab650c-…',
  document_template_ids: ['tpl-1', 'tpl-2']
)

# Vous pouvez aussi spécifier un canal personnalisé pour le routage
webhook = Pdfmonkey::Webhook.create(
  url: 'https://example.com/webhooks/pdfmonkey',
  event: 'document.generation.completed',
  workspace_id: 'f4ab650c-…',
  custom_channel: 'invoices'
)

# Supprimer un webhook
Pdfmonkey::Webhook.delete('webhook-id')
# ou
webhook.delete!

Engines

Lister les moteurs de rendu PDF disponibles :

engines = Pdfmonkey::Engine.list

engines.each do |engine|
  puts "#{engine.name} (déprécié : #{engine.deprecated_on || 'non'})"
end

Vous pouvez utiliser un moteur lors de la création d’un template :

engines = Pdfmonkey::Engine.list
v4 = engines.find { |e| e.name == 'v4' }

template = Pdfmonkey::Template.create(
  identifier: 'my-template',
  body: '<h1>Hello</h1>',
  pdf_engine_id: v4.id
)

Utilisateur courant

Récupérer les informations de l’utilisateur authentifié :

user = Pdfmonkey::CurrentUser.fetch

user.email               # => 'user@example.com'
user.current_plan        # => 'pro'
user.available_documents # => 1000

Pagination

Toutes les méthodes de liste retournent des objets Pdfmonkey::Collection qui supportent la pagination :

collection = Pdfmonkey::Document.list_cards(page: 1)

collection.current_page     # => 1
collection.total_pages      # => 5
collection.next_page_number # => 2
collection.prev_page_number # => nil

# Naviguer vers la page suivante/précédente
next_page = collection.next_page  # => Collection ou nil
prev_page = collection.prev_page  # => Collection ou nil
Les collections sont Enumerable. Les méthodes comme .each, .map et .select opèrent sur les éléments de la page courante uniquement — elles ne récupèrent pas automatiquement les pages suivantes.
# Toutes ces méthodes agissent sur les éléments de la page courante
collection.each { |item| puts item.id }
collection.map(&:status)
collection.select { |item| item.status == 'success' }

# Pour traiter toutes les pages, naviguez manuellement
page = Pdfmonkey::Template.list_cards(page: 1)
while page
  page.each { |item| process(item) }
  page = page.next_page
end

Sérialisation

Toutes les ressources supportent to_json et to_h :

document.to_json # => '{"document":{"id":"…","status":"success",…}}'
document.to_h    # => {id: "…", status: "success", errors: nil, …}
to_json encapsule les attributs sous la clé membre API de la ressource, omet les valeurs nil et supprime l’attribut errors (destiné aux requêtes API). Utilisez to_h quand vous avez besoin du hash complet des attributs pour le logging ou la mise en cache.

Questions fréquentes

Comment installer le SDK Ruby PDFMonkey ?
Ajoutez gem 'pdfmonkey' à votre Gemfile et exécutez bundle install, ou exécutez directement gem install pdfmonkey. Définissez votre clé API via la variable d’environnement PDFMONKEY_PRIVATE_KEY ou configurez-la dans un initializer.
Quelle est la différence entre generate! et generate dans le gem Ruby PDFMonkey ?
generate! est synchrone — il bloque jusqu’à ce que le document atteigne le statut success ou failure, puis renvoie le document avec une URL de téléchargement. generate est asynchrone — il renvoie immédiatement avec un statut pending, et vous gérez le résultat via des webhooks.
Peut-on utiliser des clés API par requête avec le SDK Ruby PDFMonkey ?
Oui. Créez une Pdfmonkey::Configuration avec une clé spécifique au tenant, encapsulez-la dans un Adapter et passez-la à Pdfmonkey.with_adapter. Toutes les opérations à l’intérieur du bloc utilisent cet adapter tandis que les appels en dehors continuent d’utiliser la configuration globale.
Comment gérer les erreurs dans le SDK Ruby PDFMonkey ?
Interceptez Pdfmonkey::ApiError pour les erreurs API (inclut status_code et errors), Pdfmonkey::ConnectionError pour les problèmes réseau, ou Pdfmonkey::GenerationError lors de l’utilisation de generate! quand le document échoue. Toutes héritent de Pdfmonkey::Error pour une interception globale.
Navigation