Templates
Profifact uses templates (sjablonen in Dutch) to render PDF representations of invoices, offers and reminders. The Profifact UI provides a layout editor for templates, but clients are free to modify their templates through other means. This article describes how clients can retrieve their templates, create new templates and update existing templates.
Index
Introduction
Whenever Profifact generates a PDF copy of an invoice, offer or reminder, it uses a template constructed by the client or provided by Profifact to determine how the layout of the document should be. Clients can create and modify templates using the layout editor in the Profifact UI. Because invoices, offers and reminders are similar but not the same, there are currently three types of templates:
- INVOICE
- The template is intended for rendering PDF copies of invoices.
- OFFER
- The template is intended for rendering PDF copies of offers.
- REMINDER
- The template is intended for rendering PDF copies of reminders.
Clients can create any number of templates of any of these types. Each template has a name
that is unique for its type (i.e. two templates cannot have the same name and the same type)
and clients have exactly one template of each type that is marked as default. The default
template is used if a client does not explicitly specify a template ID when creating an
invoice, an offer or a reminder. Profifact assigns one template of each type all named
Standaard to new clients.
Raw templates are JSON-encoded data structures that consist of a page object and one or
more blocks. Each block is positioned somewhere on the page and has a set of properties that
determine how its contents are rendered. The /templates
resource provides access to template objects that encapsulate raw templates along with some
metadata.
Like client addresses and customer addresses, templates may change over time. A client may for example change its logo or branding. If a template is in use by one or more non-concept invoices, offers or reminders, a modified version of the template must not overwrite the existing version because that would cause the documents based on the original version to be rendered differently. Profifact ensures that documents are always rendered exactly the same and therefore does not allow templates to be overwritten. Instead, whenever a template is in use, a new version of the template is created and the old version is marked as archived. The existing non-concept documents created by the client keep refering to the old version of the template and all concept documents are set to refer to the new version.
Retrieving multiple templates
Clients can retrieve multiple templates by sending an HTTP GET request to /templates. Authentication is required and only templates owned by the client are returned. Clients do not usually have very many templates and therefore all templates belonging to the client are returned.Unlike an HTTP GET request for a particular template (see retrieving a template), when retrieving multiple templates only metadata is returned. The template property of each item is not included in the results. This signicantly reduces the amount of data that needs to be transferred from the service to the client.
Request
HTTP GET requests to /templates may include any of the following GET parameters:
- order
- A comma separated set of field names specifying the sort order of the matching items. A minus sign preceeding a field name indicates descending sort order.
Examples
// Retrieve all templates owned by the client:
GET /templates HTTP/1.1
// Sort templates by type, being a default template and name:
GET /templates?order=type,default,name HTTP/1.1
Response
The Profifact server may send any of the status codes defined in response status codes in response to an incoming request. For a valid request HTTP status 200 OK is returned and the response body contains a data structure with the members defined in the table below. See the section on data types for an explanation of property data types.
| Name | Type | Description |
|---|---|---|
| count | int | Specifies the number of items returned. |
| total | int | Specifies the total number of matching items. |
| offset | int | Specifies the offset of the first returned item in the collection of all matching items. |
| items | array | The array of the template objects selected for being returned based on the request. |
| id | int | The unique ID of the template assigned by Profifact. |
| archived | bool | Indicates whether the template is an archived version (i.e. not the current version). HTTP GET requests to the /templates resource return only the non-archived versions of the templates owned by the client. |
| default | bool | Indicates whether the template is the default template for its type. |
| name | string | The name of the template. Template names are unique per template type. |
| type | string | The type of the template as defined in the introduction. |
Retrieving a template
Clients can retrieve a single template by sending an HTTP GET request to /templates/RESOURCE_ID where RESOURCE_ID is a unique identifier of the requested template. Both archived and non-archived templates can be retrieved. RESOURCE_ID may also be a template type as defined in the introduction in which case the default non-archived template of that type is returned.Request
Currently, no additional GET parameters are supported for requests to /templates/RESOURCE_ID.
Examples
// Retrieve a particular template:
GET /templates/97992 HTTP/1.1
// Retrieve the latest version of the default invoice template:
GET /templates/invoice HTTP/1.1
// Retrieve the latest version of the default offer template:
GET /templates/offer HTTP/1.1
// Retrieve the latest version of the default reminder template:
GET /templates/reminder HTTP/1.1
Response
The Profifact server may send any of the status codes defined in response status codes in response to an incoming request. For a valid request HTTP status 200 OK is returned and the response body contains a template object whose members are shown in the following table. See the section on data types for an explanation of property data types.
| Name | Type | Description |
|---|---|---|
| id | int | The unique ID of the template assigned by Profifact. |
| archived | bool | Indicates whether the template is an archived version (i.e. not the current version). HTTP GET requests to /templates/RESOURCE_ID can be used to retrieve both archived and non-archived versions of the templates owned by the client. |
| default | bool | Indicates whether the template is the default template for its type. |
| name | string | The name of the template. Template names are unique per template type. |
| type | string | The type of the template as defined in the introduction. |
| template | string | The raw JSON template. If the HTTP request has its Accept header set to application/json, the value of this property will be JSON-encoded JSON during transfer. |
Creating a template
A new template can be created by sending an HTTP POST request to /templates. The request body must contain values for at least the mandatory template properties encoded in the content type indicated by the client through the Content-Type header. Currently only JSON encoded data is supported.Request
HTTP POST requests to /templates are validated before a
template is created. A new template cannot be archived and it cannot have the same name
as an existing template of the same type. If specified and true, the
default property causes the new template to be set as the default template for
its type taking that role from the current default.
Valid requests must provide valid values for the mandatory fields
listed in the table below. If specified, values for optional fields must be valid as
well. See the section on data types for an
explanation of property data types.
| Name | Type | Valid values | Description |
|---|---|---|---|
| default | bool? | Indicates whether the template should be set as the default template for its type. Defaults to false if not specified. | |
| name | string | ^.{4,50}$ | The name of the new template. |
| type | string | INVOICE, OFFER or REMINDER | The type of the new template as defined in the introduction. |
| template | string | ^.{1,8192}$ | The raw JSON template. The specified value is checked for being valid JSON and checked for adhering to the exact structure required. Mandatory blocks and properties must be present and all properties must have valid values. Textblock texts may contain a subset of HTML tags and HTML attributes. CSS in HTML style attributes is permitted. No script attributes, script blocks or any other active code is allowed. |
Examples
// A minimal example for creating a new invoice template:
POST /templates HTTP/1.1
{
"name":"My new default template",
"type":"INVOICE",
"template":"=== omitted for brevity ===",
}
// Creating the new default offer template:
POST /templates HTTP/1.1
{
"name":"My new template",
"default":1,
"type":"OFFER",
"template":"=== omitted for brevity ===",
}
Response
The Profifact server may send any of the status codes defined in response status codes in response to an incoming request. For a valid request HTTP status 201 Created is returned and the response body contains exactly the same information as the Retrieving a template response.Updating a template
The update method supports updating of existing non-archived templates. Requests to update archived templates or to archive the current versions of templates are denied. The type of a template cannot be changed. The unique ID of the template to be updated must be specified as the RESOURCE_ID in HTTP PUT requests to /templates/RESOURCE_ID.When updating a template only the changes have to be specified. E.g. to update only the name property of template, the request data needs only provide the name property with its new value (see below for examples).
Setting the value of a property to null is interpreted by the service as a request to assign null to the property and not as a request to leave the value of that property unchanged. The latter can be accomplished by not specifying the property at all.
Updating a template may cause a new version of it to be created if the current version is referenced by one or more non-concept invoices, offers or reminders. If that happens, new version is returned instead of the (now archived) old version. This means that the update method is not idempotent for templates that are in use.
Request
To update an existing non-archived invoice, send an HTTP PUT request to /templates/RESOURCE_ID where RESOURCE_ID is the unique ID of the template to be updated. All the properties defined in the section on creating an template may be present in the request data. The same validation rules apply.
Examples
// Changing the name of a template:
PUT /templates/6 HTTP/1.1
{ "name": "With holiday notice" }
// Making a template the default for its type:
PUT /templates/17 HTTP/1.1
{ "default":1 }