Skip to main content

​
Overview

Tesouro offers several built-in PDF templates for receivables and purchase orders, and organizations can choose the default template for their documents. The templates can also be customized to include the organization logo.

​
PDF translation and localization

Tesouro supports the translation and localization of PDF templates. PDF translation defines the language used on all Tesouro PDFs. PDF translation depends on both the organization’s and counterpart’s assigned language. For example, the original_file_language and file_language fields on Invoice and Quote objects represent the languages into which the PDF will be translated for organizations and counterparts, respectively. Tesouro provides translation of PDFs for counterparts in English, French, German, Spanish, and Dutch. The language field in the POST /counterparts and PATCH /counterparts/{counterpart_id} payloads accepts the ISO 639-1 standard and defines the language translation for all PDFs sent to the counterpart. If not provided, all PDFs sent to the counterpart are in English. For more information, see Create a counterpart. Tesouro handles the formatting of delimiters and decimal separators on amounts displayed on the PDFs based on the organization’s country.

​
List the available templates

To get a list of available supported templates, call GET /document-templates: 
curl -X GET 'https://api.sandbox.tesouro.com/v1/document-templates' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'
The response contains a list of all PDF templates with their language codes and some other internal metadata. The fields of note are id (template ID), name (template name), preview.url (link to a preview image), and template (HTML content of the template). The template ID can be used later to set the default template. 
{
  "data": [
    {
      "id": "94f9280b-d7d2-48ca-8290-3727d1b61861",
      "created_at": "2024-01-08T11:47:35.451048",
      "updated_at": "2024-01-08T11:47:35.451054",
      "blocks": [],
      "document_type": "receivable",
      "is_default": false,
      "language": "en",
      "name": "classic",
      "preview": {
        "id": "d7a112ef-0ef7-4ea7-ba1b-cbbb99990d81",
        "created_at": "2025-03-10T09:49:57.726721+00:00",
        "updated_at": "2025-03-10T09:49:57.726729+00:00",
        "file_type": "receivables",
        "md5": "4ac4b4238fa2fb93746c0a1eee98ed74",
        "mimetype": "image/png",
        "name": "218fc898-ff4f-4783-af36-86f41a918738",
        "region": "eu-central-1",
        "s3_bucket": "tesouro-file-saver-sandbox-eu-central-1",
        "s3_file_path": "sandbox/receivables/12345/67890.png",
        "size": 235016,
        "url": "https://<bucketname>.s3.amazonaws.com/sandbox/receivables/12345/67890.png"
      },
      "template": "<!doctype html>\n<html lang=\"en\" class=\"template-1\">\n...........</html>",
      "template_type": "source_object"
    },
    ...
  ]
}

​
Get all system templates

System templates refer to Tesouro’s built-in PDF templates. To retrieve all Tesouro’s built-in PDF templates, call GET /document-templates/system: 
curl -X GET 'https://api.sandbox.tesouro.com/v1/document-templates/system' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'
PDFs templates for receivables include the organization logo. You can upload the logo by using PUT /entities/{entity_id}/logo: 
curl -X PUT 'https://api.sandbox.tesouro.com/v1/entities/aea39...912/logo' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -F file=@path/to/image.png

​
Preview the templates

You can preview invoice templates as PDF or PNG. To get the previews as PNG images, use the preview.url field of each template:
GET /document-templates
{
  "data": [
    {
      ...
      "name": "classic",
      "preview": {
        ...
        "url": "https://<bucketname>.s3.amazonaws.com/sandbox/receivables/12345/67890.png"
      },
      ...
    },
    {
      ...
      "name": "standard",
      "preview": {
        ...
        "url": "https://<bucketname>.s3.amazonaws.com/sandbox/receivables/09876/54321.png"
      },
      ...
    },
    ...
  ]
}
To get the previews as PDF files, call GET /document-templates/{document_template_id}/preview with the template ID passed in the request URL. The response is a sample PDF invoice generated using the specified template. 
curl 'https://api.sandbox.tesouro.com/document-templates/94f9280b-d7d2-48ca-8290-3727d1b61861/preview' \
  -H 'X-Finops-Version: 2025-06-23' \
  -H 'X-Organization-Id: ORGANIZATION_ID' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -o ./file.pdf

​
Set the default template

Organizations can set or change the default PDF template at any time. The specified template will be used for all new receivables and purchase orders created by the organization. Existing PDFs previously generated by the organization are not affected. To set the default template call POST /document-templates/{document_template_id}/make-default, replacing {document_template_id} with the ID of the desired template: 
curl -X POST 'https://api.sandbox.tesouro.com/v1/document-templates/{document_template_id}/make-default' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'