
This add-on is operated by Sivije
Build templates with HTML and use a simple REST API to generate PDF documents
PDFMonkey
Last updated August 11, 2020
The PDFMonkey add-on is currently in beta.
Table of Contents
PDFMonkey is an add-on for providing easy, API-based generation of PDF documents. You can generate any document your business needs, including invoices, contracts, reports, and flyers.
PDFMonkey is accessible through a REST API and provides integration options for a variety of languages. Examples are included for Ruby and cURL.
Provisioning the add-on
PDFMonkey can be attached to a Heroku application via the CLI:
A list of all plans available can be found here.
$ heroku addons:create pdfmonkey
-----> Adding pdfmonkey to immense-journey-80008... done, v42 (free)
Once PDFMonkey is provisioned, a PDFMONKEY_PRIVATE_KEY
config var is added to your app. It contains the private key you use to call the PDFMonkey REST API. You can confirm this value using the heroku config:get
command:
$ heroku config:get PDFMONKEY_PRIVATE_KEY
6e51345c7cdee7ad0f1566ce
Local environment setup
After provisioning the add-on, you need to replicate its config vars locally so your development environment can operate against the service.
Use the heroku local
command to run your app locally. This command reads config vars from your app’s .env
file. To view all of your app’s config vars, type heroku config
. Use the following command to add the PDFMONKEY_PRIVATE_KEY
value retrieved from heroku config to add to your .env
file:
$ heroku config -s | grep PDFMONKEY_PRIVATE_KEY >> .env
$ more .env
Credentials and other sensitive configuration values should not be committed to source control. In Git, exclude the .env
file with: echo .env >> .gitignore
.
For more information, see the Heroku Local article.
Using with Ruby
Ruby applications can add the following entry to their Gemfile
to include the pdfmonkey gem:
gem 'pdfmonkey'
Then update application dependencies with bundler:
$ bundle install
Before generating a document, you need to get a Template ID from the PDFMonkey Dashboard. Once you have it you can use the gem.
Synchronous generation
If you want your application’s logic to wait for document generation to complete before continuing, use the generate!
method. This method initiates a document generation and waits for it to succeed or fail before returning.
tempalte_id = 'YOUR_TEMPLATE_ID'
data = { name: 'John Doe' }
document = Pdfmonkey::Document.generate!(template_id, data)
document.status # => 'success'
document.download_url # => 'https://…'
A document’s download URL is valid for 30 seconds only. After that, you need to use the document.reload!
method to obtain a new download URL.
Asynchronous generation
If you want to generate documents asynchronously, PDFMonkey provides webhooks that notify you when document generation succeeds or fails.
To initiate an asynchronous document generation, use the generate
method:
tempalte_id = 'b13ebd75-d290-409b-9cac-8f597ae3e785'
data = { name: 'John Doe' }
document = Pdfmonkey::Document.generate(template_id, data)
document.status # => 'pending'
document.download_url # => nil
If you’ve specified a webhook URL, PDFMonkey sends it a POST request with a Content-Type: application/json
header when generation completes or fails. The body of this request has the following structure:
{
"document": {
"id": "4204eff8-3126-4ec7-a5f9-aa8ed5b8517b",
"status": "success",
"app_id": "d9ec8249-65ae-4d50-8aee-7c12c1f9683a",
"document_template_id": "b13ebd75-d290-409b-9cac-8f597ae3e785",
"payload": "{\"name\":\"John Doe\"}",
"checksum": "6dc8942e10f93b1e22d4b18bdf04e2f3",
"download_url": "https://….pdf",
"preview_url": null,
"meta": null,
"created_at": "2018-12-04T20:28:35.072+01:00",
"updated_at": "2018-12-04T20:28:38.899+01:00"
}
}
You can then create a Document
object from this JSON payload with the following command:
document = Pdfmonkey::Document.new(params[:document])
A document’s download URL is valid for 30 seconds only. After that, you need to use the document.reload!
method to obtain a new download URL.
Using with cURL
If you want to use the PDFMonkey API in a language for which no integration exist yet, you can use requests like the ones that follow.
Creating a document with a POST request
$ curl https://api.pdfmonkey.io/api/v1/documents \
-X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_PDFMONKEY_PRIVATE_KEY' \
-d '{
"document": {
"document_template_id": "YOUR_TEMPLATE_ID",
"payload": "{\"name\":\"John Doe\"}",
"status": "pending"
}
}'
Expected JSON result:
{
"document": {
"id": "4204eff8-3126-4ec7-a5f9-aa8ed5b8517b",
"status": "pending",
"app_id": "d9ec8249-65ae-4d50-8aee-7c12c1f9683a",
"document_template_id": "b13ebd75-d290-409b-9cac-8f597ae3e785",
"payload": "{\"name\":\"John Doe\"}",
"checksum": "6dc8942e10f93b1e22d4b18bdf04e2f3",
"download_url": null,
"preview_url": null,
"meta": null,
"created_at": "2018-12-04T20:28:35.072+01:00",
"updated_at": "2018-12-04T20:28:38.899+01:00"
}
}
Fetching a document with a GET request
$ curl https://api.pdfmonkey.io/api/v1/documents/4204eff8-3126-4ec7-a5f9-aa8ed5b8517b \
-H 'Authorization: Bearer YOUR_PDFMONKEY_PRIVATE_KEY'
Expected JSON result:
{
"document": {
"id": "4204eff8-3126-4ec7-a5f9-aa8ed5b8517b",
"status": "success",
"app_id": "d9ec8249-65ae-4d50-8aee-7c12c1f9683a",
"document_template_id": "b13ebd75-d290-409b-9cac-8f597ae3e785",
"payload": "{\"name\":\"John Doe\"}",
"checksum": "6dc8942e10f93b1e22d4b18bdf04e2f3",
"download_url": "https://….pdf",
"preview_url": null,
"meta": null,
"created_at": "2018-12-04T20:28:35.072+01:00",
"updated_at": "2018-12-04T20:28:38.899+01:00"
}
}
Dashboard
The PDFMonkey dashboard allows you to create, edit, and delete your templates. You can also use it to generate documents manually if necessary.
The dashboard can be accessed via the CLI:
$ heroku addons:open pdfmonkey
Opening pdfmonkey for immense-journey-80008...
or by visiting the Heroku Dashboard and selecting the application in question. Select PDFMonkey from the Add-ons menu.
Migrating between plans
Use the heroku addons:upgrade
command to migrate to a new plan.
$ heroku addons:upgrade pdfmonkey:nano-monkey
-----> Upgrading pdfmonkey:nano-monkey to immense-journey-80008... done, v42 ($6/mo)
Your plan has been updated to: pdfmonkey:nano-monkey
Removing the add-on
PDFMonkey can be removed via the CLI.
This will destroy all associated data and cannot be undone!
$ heroku addons:destroy pdfmonkey
-----> Removing pdfmonkey from immense-journey-80008... done, v43 (free)
Support
All PDFMonkey support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome at support@pdfmonkey.io.