Package: byroapi
REST API service for filling in and (visually) signing PDF documents.The administrator provides form templates (PDF documents with blank fields) and
configuration (YAML) describing fields that shall be filled on each PDF document.The user then POSTs JSON request to the REST API endpoint. The JSON contains
template id and values for the fields defined in the configuration of the
particular template.
The service uses the data in the JSON to write over a template PDF with the data
(text fields or images) and either returns API response with the filled PDF
document, or can send this document as email attachment to a specified address.Features and limitationsCan add strings over any PDF (doesn’t require PDF form fields)But, also doesn’t yet support PDF form fields ;)Can add images with transparent mask (=signatures)Supports multi-page documentsDoes not yet support real cryptographic signatures.Installation$pipinstallbyroapiConfigurationFor the usual operation, byroapi requires following:configuration file (YAML) - contains entire configuration including template
definitionstemplate files - for each supported PDF form, a “blank” template file is
required on which the field contents and signatures are overlaid. These
template files may be multiple for the same form - e.g. bianco signed forms
for each user, differentiated by filename.other assets - image files, additional fonts etc.Template files and other assets can be stored in any path referenced in the
configuration file.Configuration fileByroapi usesOnacolconfiguration, so any configuration parameter described
below can be configured either in the YAML file or through CLI option
or environment variable.This documentation only describes the YAML configuration method.To create a configuration file template, use following command:$ byroapi --get-config-template your_config.yamlTypical example configuration with some template looks as follows:general:log_level:INFO# Logging level [DEBUG, INFO, WARNING, ERROR, CRITICAL]templating:# This section contains all configuration regarding PDF processingfonts:# List of additional TTF fonts to be used in PDF processing-name:Arialpath:fonts/arial.ttftemplates:# List of defined templates-id:MyFormtemplate:# Template sourcepath:templates/myform_filespath_value_substitution:#value:user_idpattern:'myform_{0}_signed.pdf'field_defaults:# Default settings for each form field elementstring:custom:-property:Fontvalues:["Arial",12]fields:# PDF form field definitions-name:date_fromcoords:x:42y:174.5type:string-name:date_tocoords:x:75y:174.5type:string-name:date_approvedcoords:x:57y:132.25type:string-name:sign_approverdefault:signature2.pngcoords:x:143y:87height:25type:imageemail:# Configuration for email (can be used for sending processed PDF forms)smpt:# SMTP settings as defined in YagMail: https://github.com/kootenpv/yagmail/blob/f24af871c670c29f30c34ef2a4ab5abc3b17d005/yagmail/sender.py#L22 , if you set the user, you will not be able to use the "from" field in the "result:email" part of the API request.host:smtp.myserver.comport:25smtp_skip_login:truesmtp_ssl:truesmtp_starttls:truerest_api:# Configuration of the REST API endpointaddr:0.0.0.0port:8080Now, let’s discuss main parts of this.templatingsection contains all definitions regarding the supported
PDF form templates.
In the sectiontemplating:fontsyou can list additional fonts that can be
used in the PDF processing. Only TrueType fonts are supported for now.
Thenameparameter is used in the consequent references to the font in the
form field configurations.The sectiontemplating:templatesthen includes list of all supported PDF
form templates. In this example, we support only one PDF form, called “MyForm”.Template definitionEach form template configuration then defines further configuration.idparameter defines ID that is used to select the particular form in the REST API
call (see the API section).Thetemplateparameter defines which PDF file should be used as the “blank”
form to write the data over. There are two ways to select a PDF file:If only one PDF blank is used for all possible data contents, then thetemplate:pathparameter should provide path to a PDF file with the blank
form.If the PDF blank should be different for different data contents, then thetemplate:pathparameter should be a path to a folder that contains files
named in thetemplate:path_value_substitution:pattern(the pattern format
is the same as the Pythonstr.format()). The values in the pattern will
be substituted by parameter defined intemplate:path_value_substitution:valueSo in our example, let’s say the API call should include parameteruser_idwith valueuser33444. Then, as the blank PDF form, filetemplates/myform_files/'myform_user33444_signed.pdf'will be used.Form field elementsEach form template consists of several fields that are filled in. Byroapi
currently supports three field types:string- draws text string on a given coordinates.image- puts an image (from an image file) on a given coordinats.page_break- switches to the next page in case of a multi-page document.Each of these fields can have further custom configurations. This configuration
can be done per-template (so this configuration is a default within a given
template) in thefield_defaultssection.In the given example, we configure thestringfields with default font
Arial, size 12 pts. This will be applied to the eachstringelement within
the “MyForm” template.Then, the individual fields are defined in thefieldssection. Each field
must containnameandtypeidentifiers. Thenameidentifiers is
matched against the data provided in the REST API call.Field can also have adefaultvalue. That value is used if no value for
given field is provided in the API call.Fields are processed in the order they are defined in the configuration.
Therefore, to fill a multi-page document, the field typepage_breakis used
to switch the pages. (fortype: page_breakfields, thenamedoesn’t
matter but must be present, other fields do not have to be present and do
not matter).Bothstringandimagecan have acustomproperty configuration that
overloads the default configuration. The contents of thecustomis a list of
properties that match thereportlabsetXXX() method calls using patternset{property}(*{values}).Graphical fields also have thecoordsconfiguration property withxandycoordinates in millimeters from the bottom-left corner of the page (seereportlabfor details).Email settingsDepending on the API call paramters, one can request byroapi to send the
result of the PDF processing to a selected email address(es). For this, SMTP
is used, with configuration inemail:smtp. Each parameter of this section
should match theYagmailsender config.There are two ways how to configure the sender. If you use a SMTP server without
login process (usually an internal service), you don’t use theuservalue in
theemail:smtpand you can use it to emulate any sender address using thefromparameter in the API call (see below).If you SMTP server requires a login, thenuserparameter inemail:smtpmust be set and thefromparameter in the api call will be ignored if
present.REST API structureThe byroapi REST API provides two endpoints:POST/api/v1/form- for providing the form filling data and retrieving
processed PDF file.PUT/api/v2/template/{template_id}/{var}- for updating the PDF blank files for each template/api/v1/formIs a POST endpoint accepting JSON payload with following structure:{"template":"template_id","form_data":{"field_name":"field_value",...},"result":{"download":true,"email":{"from":{"some@email.com":"Some Guy Name"},"to":{"recipient1@email.com":"Recipient One","recipient2@email.com":"Recipient Two"},"cc":{...},"subject":"","contents":"","attachments":""}}}Thetemplatevalue shall match someidin the template configuration.The sectionform_datathen contains key-value collection where key matches
field names for and values are data to be filled into the form fields.Theresultsection then contains information about how to handle the result
of the PDF processing. Ifresult:downloadis set to true, the PDF file will
be included in the REST response to the API call (otherwise, just status code
200 is returned in case of sucessful processing).Ifresult: emailsection (optional) is populated, then the PDF file will be
attached to an email and sent to the selected address.result:email:fromneeds to be filled only in case SMTP server doesn’t use login (see theEmail settings). The other parameters are matching theYagmailsend()
options. Only one attachment file is supported. If no file-name is defined,
a default file name will be used.To continue with the example configuration from theConfiguration filesection
, the template “MyForm” can be processed with following JSON request:{"template":"MyForm","form_data":{"date_from":"2022/01/13","date_to":"2022/01/14","date_approved":"2022/01/12","user_id":"user33444"},"result":{"download":true,"email":"to":{"some.guy@email.com":"Some Guy"},"subject":"My form processed","contents":"My form is provided in attachment.","attachments":"my_form_user33444.pdf"}}/api/v1/templateThis PUT endpoint can be used for updates of the PDF “blank” files, especially in
case they use the path value substitution.
The use case is singular - a new or updated PDF “blank” for a given variable
value used in substitution can uploaded to the byroapi:$ curl -T new_template.pdf http://host:port/api/v1/template/{template_id}/{substitution_variable}For example “MyForm” used above, “user33444” can update the PDF blank like
this:$ curl -T user33444_updated_blank.pdf http://host:port/api/v1/template/MyForm/user33444This will update the existing platform in the substitution path, or add the new
one if none exists.UsageByroapi provides a simple CLI. To run as a server:$ byroapi --config your_config.yamlTo process PDF from CLI:$ byroapi --config your_config.yaml --fill-form your_form.yaml --output your_form_output.pdfIn this case, theyour_form.yamlshould be a YAML file with contents matching
the/api/v1/formJSON payload (only thetemplateandform_dataitems
matter).