Documentation
About ?
Why ?
There's no API for producing PDF documents based on the well-known programming concept of separating data from view.
The concept is simple. WebForgePDF integrates data into an HTML/Twig template, which defines the structure. Then, it styles the whole thing using CSS.
In background, it use an headless browser to produce pretty document with full advanced CSS support.
Use the playground
We strongly recommend using the playground to test the capabilities of WebForgePDF and to develop your own template.
Remember to export your query as a JSON object so you can use it directly in your program.
Please note that PDF documents produced by the Sandbox contain watermarks, are limited to 50 pages, and are not prioritized by our server. This means they take longer to generate than documents created using the API.
About API
WebForgePDF can only be used via HTTP calls and through the WebForgePDF platform RapidAPI.
The platform handles monetization and security. If you would like direct, privileged access to the API without going through RapidAPI, please contact us.
Request
The service is only available in POST.
Body
The request body contains all the data needed to create the PDF in JSON format.
Below is an example of a minimal body to generate an empty PDF.
{
"data": {},
"template": "",
"style": "",
"landscape": "0", /* optional */
"paperWidth": "210",
"paperHeight": "297",
"marginTop": "10",
"marginBottom": "10",
"marginLeft": "10",
"marginRight": "10",
"frameworkCSS": "none",
"unit": "mm",
"author": "", /* optional */
"copyright": "", /* optional */
"subject": "", /* optional */
"title": "", /* optional */
"keywords": "" /* optional */
}Caution: style and template property values must be escaped to avoid invalidating the JSON.
However, this does not apply to the data property, which must be a JSON object or array.
Headers
Remember to include authorization tokens; otherwise, you risk receiving a 401 Unauthorized error.
Response
In case of success
If all goes well, the server will return the PDF as a response with an HTTP code of 200 and a content type of application/pdf, with the binary content of the PDF in the body of the response.
In case of failure
If the data passed as parameters is invalid, or if there is a problem interpreting the template, the application will return a response in JSON format with an HTTP code of 400.
The debugging information is contained in the errors property, as shown in the example below :
{
"errors": {
"paperWidth": {
"range": "The provided value must be between `1` and `100000`, inclusively"
},
"marginLeft": {
"lessThanField": "The provided value must be less than the one of field `paperWidth`"
},
"marginRight": {
"lessThanField": "The provided value must be less than the one of field `paperWidth`"
}
},
"code": 400
}In case of timeout
Although WebForgePDF is very fast, be careful what you ask it to produce. Using too many external resources can considerably slow down generation time and lead to a timeout.
About Data
WebForgePDF treats data as a resource for creating PDF documents. Depending on the data format, you can use it in one of three modes.
Mode no Data
The data may be empty or null. In this case, WebForgePDF will produce a standard PDF document from the provided HTML template and CSS style.
Mode Simple object
If the data is a simple JSON object, PDFactor applies the HTML template only once.
Mode Array of object
The real advantage of this tool is that, when the data is an array of JSON objects, PDFactor will apply an HTML template to each object in the collection, with a page break separating them.
About Template
The template defines how elements are structured within a PDF document.
It is based on HTML, the markup language, and the famous rendering engine. Twig for data handling.
Document properties
WebForgePDF can produce PDF documents of any size and in any unit of measurement (mm, cm, in, pt, px, pc).
The inner margins are also configurable. However, bear in mind that some printers impose minimum margin requirements.
Some Exif data can be defined: Title, Subject, Keywords (separated by commas), Author and Copyright.
HTML
The WebForgePDF engine supports all HTML tags, but there's no need to encapsulate your code in an html or body tag.
For security reasons, however, iframe cannot be used and will not be interpreted by the WebForgePDF engine.
medias
Most image-based media are supported (GIF, JPG, PNG, SVG, ....).
Although it is possible to integrate them directly from an external URL, this slows down the rendering process.
You can also use the base64 encapsulation method in the src attribute.
It's also possible to embed SVG code directly in HTML.
Twig
The Twig template engine is used to integrate and manipulate data within templates.
Feel free to consult our examples and the Twig documentation to learn more about how the engine works.
For security or contextual reasons, some template inclusion features have been disabled. See below for details on the available features.
filters/modifiers authorized
abs, batch, capitalize, column, convert_encoding, country_name, currency_name, currency_symbol, data_uri, date, date_modify, default, escape, first, format, format_currency, format_date, format_datetime, format_number, format_time, join, json_encode, keys, language_name, last, length, locale_name, lower, merge, nl2br, number_format, plural, raw, replace, reverse, round, shuffle, singular, slice, slug, sort, split, striptags, timezone_name, title, trim, u, upper, url_encode.
tags authorized
apply, autoescape, do, guard, for, if, set, types, verbatim, with.
functions/methods authorized
cycle, date, enum_cases, html_classes, max, min, random, range, country_timezones, country_names, currency_names, language_names, locale_names, script_names, timezone_names.
Bar Code
The Twig barCode(toEncode, type) function creates barcodes from the data in the Data section.
WebForgePDF supports many barcode formats, but beware: some require specific formatting of the encoded data. Failure to do so may result in generation errors.
Below is a list of the supported barcodes :
CODABAR, CODE_11, CODE_32, CODE_39, CODE_39_CHECKSUM, CODE_39_EXTENDED, CODE_39_EXTENDED_CHECKSUM, CODE_93, STANDARD_2OF5, STANDARD_2OF5_CHECKSUM, INTERLEAVED_25, INTERLEAVED_25_CHECKSUM, CODE_128, CODE_128_A, CODE_128_B, CODE_128_C, EAN_8, EAN_13, UPC_A, UPC_E, UPC_EXTENSION_2, UPC_EXTENSION_5, MSI, MSI_CHECKSUM, POSTNET, PLANET, RMS4CC, KIX, INTELLIGENT_MAIL_BARCODE, PHARMACODE, TELEPEN, TELEPEN_NUMERIC
Example :
{{ barCode(toEncode, "CODE_128") }}To optimize rendering, barcodes are generated in SVG format and integrated directly into the HTML code. To adjust the size, simply modify the parent container using CSS rules.
Don't forget to consult the example codabars from our playground.
Other
Javascript
For security reasons, JavaScript is disabled and will not be interpreted by the WebForgePDF engine.
Page break
You can force a page break in WebForgePDF by using the following HTML code :
<div class="page-separator"></div>About Style
WebForgePDF uses CSS technology to style HTML tags in PDF documents.
Because the tool uses a headless browser for rendering, it can support most Level 3 CSS features.
Inline CSS
Use the style property to define your own CSS rules.
If you're using a CSS framework, the rules will be applied "on top" of the framework to allow for easy oerriding.
External fonts and Google Fonts
Both external and Google fonts can be integrated into PDF documents.
To accomplish this, use the integration method via the @import tag, placing it directly in your CSS.
@import url('https://fonts.googleapis.com/css2?family=Rubik:ital,wght@0,300..900;1,300..900&display=swap');
p { font-family: "Rubik", sans-serif; font-optical-sizing: auto; font-weight: 400; font-style: normal; }CSS Framework
CSS is great, but with a framework, it's even better!
To help you style your HTML, you can also integrate one of the famous CSS frameworks to complement your inline CSS :
Bootstrap 5.3.6, Bulma 1.0.4, Foundation 6.9.0, Milligram 1.4.1, Pure 3.0.0, UIkit 3.23.10.