How the visual editor and n8n work together
This guide uses Studio invoice, the starter report included in your workspace, as its example. The same workflow works with any saved Bitavu report—for example, a quote, delivery note or custom report. Adjust the layout in Bitavu: text, images, spacing and the repeating line-item table. Connect the changing content to fields such as {{client.name}} and {{invoice.number}}, then save a version.
For this invoice example, n8n sends customer details, the invoice number and line items as JSON, together with the template ID and saved revision. Bitavu fills that layout and returns a PDF. Change the data for each invoice; edit the layout in Studio when the design needs to change.
Build and test the layout in Bitavu Studio. n8n supplies the document data; Bitavu renders that data into the saved template version and returns a PDF file.
01 · BITAVU
Prepare your template and access
You need an active Bitavu trial or subscription with render credits, a saved report template, and an n8n instance you can edit.
Save and test your report in Studio
Open your report in studio.bitavu.com. Bind the text, tables and other elements to the fields your workflow will send. Save a version, then test it with sample JSON. A draft must be saved before an API key can render it.
Prepare the API request
Open Integrations, choose your saved report under Prepare a template request, then open Use in your app. Copy the request’s
templateId, numericrevisionanddata. These belong together: the data must match the fields expected by that saved version.Use a key with access to this report
In Integrations → API keys, reuse a suitable active key or choose New API key. Give it a clear name such as “n8n PDF workflow”, select your report and enable Generate PDFs. This example does not need Read templates. Choose an expiry that suits your integration.
Copy the secret when Bitavu reveals it; it is shown only once. You’ll store it in n8n Credentials in step 3. Keep the secret out of workflow JSON, screenshots and support messages.
https://api.bitavu.com/v1/render. Open the image to enlarge it.02 · N8N
Import the example workflow
In the n8n workflow editor, open the top-right … menu and choose Import from File…, then select the downloaded JSON. The workflow uses three built-in nodes:
- Run example — a manual trigger.
- Invoice data — Edit Fields with the template, version and sample JSON.
- Generate PDF with Bitavu — an authenticated HTTP Request that returns a file.
Open Invoice data. Check templateId, revision and data against your Studio request. The download is ready for the default Studio invoice at saved v1. If you changed its expected fields or use another report, replace these values with your tested request. View the sample data.
03 · CONNECTION
Store your key in n8n Credentials
Open Generate PDF with Bitavu
Set Authentication to Generic Credential Type and Generic Auth Type to Bearer Auth. Create or select a Bearer Auth credential.
Enter the Bitavu secret
Paste only the key into Bearer Token, then save the credential. Do not add the word
Bearer; n8n adds the Authorization header. Give the credential a recognizable name such as “Bitavu production”.Check the request settings
The imported node already includes the settings below. If you’re building it manually, use the same values.
| Method | POST |
|---|---|
| URL | https://api.bitavu.com/v1/render |
| Authentication | Generic Credential Type → Bearer Auth |
| Send Headers | On. Name: Idempotency-Key. Value, in Expression mode: {{ $json.operationId }} |
| Send Body | On. Body Content Type: JSON. Specify Body: Using JSON. |
| Options → Response | Response Format: File. Put Output in Field: pdf. |
| Timeout | 120000 milliseconds in the downloaded workflow. |
In the JSON body field, switch to Expression and enter:
{{ { templateId: $json.templateId, revision: $json.revision, data: $json.data } }}The workflow JSON contains an initial = marker for n8n expressions; the editor handles that marker. With JSON selected, n8n sets the request’s Content-Type automatically.
04 · FIRST PDF
Execute and download the PDF
Save the workflow and select Execute workflow. Open Generate PDF with Bitavu and check its output. A successful request returns a binary file in pdf; use Download to open the document.
Compare the examples: Studio shows DEMO-1042 and Example customer. n8n sends N8N-2087 and Workflow demo customer, and those values appear in the generated PDF below.
The response is the PDF itself, rather than JSON containing a download URL. If the output looks like unreadable text, change Response Format to File.
The PDF should show the exact sample values you sent and the layout from the selected saved revision. A successful render uses your workspace’s render allowance. Re-running the example starts a new operation and may use another render credit.
05 · YOUR AUTOMATION
Connect data from your own workflow
Replace the manual trigger with your usual workflow trigger and map its output to the fields your Bitavu report expects. Keep templateId and revision explicit. Pass the resulting pdf binary field to your next node, such as file storage or an attachment step.
Give each document operation its own idempotency key
The example creates operationId from the n8n execution ID and item index. A new execution gets a new key. Reuse the same key only when retrying the same operation with the same template, revision and data. For retries across separate workflow executions, generate and retain the operation ID upstream; the example’s execution-based value will change.
Do not reuse one constant key for every document. If data changes, start a new operation with a new key. When adding retries, respect Bitavu’s Retry-After response and check the error before retrying.
Keep the tested saved version pinned
This guide uses a numeric revision so layout changes do not silently change the automation. After editing a template, save and test the new revision, then update the workflow deliberately. API rendering allows three successfully used root versions per template in a rolling seven days, shared across workspace keys.
Bitavu does not save actual rendering inputs or generated PDFs. n8n may retain execution data and binary files according to your n8n settings. Check that retention before sending confidential document data through your workflow.
Generate a PDF with the Bitavu node
Generate PDF is Bitavu’s official n8n node for creating PDFs. It uses a Bitavu API credential, lets you pick a template and version from lists, and returns the PDF as a file for the next step. The node handles the HTTP POST, headers, and file response settings for you.
We expect the Bitavu listing to appear soon in the n8n integrations directory. You can already install the Bitavu package directly from npm on self-hosted n8n.
The playground connects Manual Trigger → Set Custom Fields → Generate PDF. Set Custom Fields supplies sample invoice data, and Generate PDF is the only Bitavu node you need.
Download the Bitavu node workflow
Install Bitavu and import the playground
On self-hosted n8n, go to Settings → Community nodes → Install and enter
@bitavu/n8n-nodes-bitavuto install it from npm. On n8n Cloud, you can follow the HTTP Request walkthrough while the Bitavu node listing is pending.Once the package is installed, open the workflow editor’s … menu, choose Import from File… and select the download.
Connect Generate PDF to Bitavu
In Bitavu Studio, open Integrations → API keys. Give your key access to the report and enable both Generate PDFs and Read templates. Generate PDFs lets the node render the document. Read templates lets it load the reports and saved versions you can choose from. In n8n, open Generate PDF, create or select a Bitavu API credential and enter the secret in API Key.
Choose the saved template and version
The playground starts with Studio invoice pinned to version 1. To use another report, pick it under Template → From List, then pick the saved version you tested under Pinned Version → From List. The list shows newer versions first and marks the current published version.
The playground pins version 1 and takes its document data from the previous step. Open the image to enlarge it. Choose Latest Published when you want the workflow to follow published changes. Set Base Version to the version you tested so Bitavu can check that the current publication still accepts the same JSON. Leaving the base empty uses the first published version for that comparison.
In Latest Published mode, Base Version sets the version used for the compatibility check. Open the image to enlarge it. Run the workflow and download the PDF
Open Set Custom Fields to see the sample invoice JSON. Generate PDF reads it through Document Data using
{{ $json.data }}. Template and version are set on the node, so the incoming JSON only needs the document fields.Select Execute workflow and open Generate PDF. Download the file from the Binary tab under
pdf, or pass that field to your next node.
Browse templates, inspect versions, and save examples
Use these nodes on their own when a workflow needs to work with templates. For example, a workflow could read the expected JSON fields before preparing data for a report. The three read actions use the same Read templates permission as the pickers in Generate PDF.
- List Templates returns the reports the API key can access, including their IDs, names, folder paths and latest saved versions. Use it when a workflow needs to look up a report by name or build a list of reports to choose from.
- List Template Versions lists saved versions for the report you choose. It identifies the current published version and the latest saved version, which can be different. Use it to check what is published before deciding which version to render or inspect.
- Get Template Version reads one saved version. Select the template and Version to Read to see its bindings, example JSON and the input paths Bitavu found missing or unused. This can help you map fields from a previous n8n step.
- Save Template Example stores the Example JSON you supply as a new saved version. Set Expected Version to the latest version you reviewed so Bitavu can detect a newer save before applying yours. The key needs Save template examples permission, and the current published version stays in place.
Generate invoice PDFs from Google Sheets
Start with an approved invoice in Google Sheets. n8n gathers its line items and passes them to the Bitavu Generate PDF node. Bitavu fills the invoice layout you saved in Studio. The workflow archives the PDF in Google Drive, then attaches that same file to an unsent Gmail draft for review.
- Download the n8n workflow (JSON)
- Download the sample workbook (XLSX)
- Download the generated invoice (PDF)
Render the built-in sample
Install the Bitavu node and import the workflow JSON using Import from File. Save a version of Studio invoice and enter its
templateIdandrevisionin Workflow settings. Select a Bitavu API credential with Generate PDFs access to that template in Generate PDF.Leave
useSampleDataset totrueand run manually. Open the Binary output of Generate PDF to downloadINV-1042.pdf. Compare it with the included sample. It should show three line items and total $1,160.00 USD. This mode uses a Bitavu render credit and skips the Google steps.The PDF generated from the sample data. Open the image to enlarge it. Connect your test spreadsheet, Drive folder and Gmail account
Open the workbook in Google Sheets and save it as a Google spreadsheet. Keep the Invoices and Line Items tab names and headers, and use plain text
YYYY-MM-DDfor dates. The sample expects USD and checks the approved total against the line items in cents.Invoices. INV-1042 is approved and INV-1043 is on hold. Open the image to enlarge it. Line Items. The invoice_numbercolumn links each line item to its invoice. Open the image to enlarge it.Create a private test folder in My Drive. Enter its ID and the spreadsheet ID as
driveFolderIdandspreadsheetIdin Workflow settings. LeaveinvoiceNumberatINV-1042.Assign the Google credentials in n8n. Use a Sheets credential with edit access on both reader nodes and all four checkpoint nodes, a Drive credential with read and write access on both Drive nodes, and a Gmail credential on Create Gmail draft.
Check the archive and the draft
Set
useSampleDatatofalseand run manually. OpenINV-1042.pdfin your Drive test folder and the attachment in the Invoice INV-1042 draft in Gmail. The draft uses the file downloaded from Drive. The invoice row should showcompleteand contain bothdrive_file_idandgmail_draft_id.Run the same invoice again to see Already complete. Select
INV-1043to see the approval check stop aHOLDinvoice before rendering. Run one invoice at a time and keep the approved data and template revision fixed while recovering an interrupted run.
Resume an interrupted run
If the state is empty, run again. If it is archived, run again to reuse the saved Drive file.
For archive_pending, check the prior execution and the test folder. If the invoice was uploaded, enter its drive_file_id, keep the fingerprint, and set the state to archived. If you confirm the upload never happened, clear the state and fingerprint.
For draft_pending, check the execution and Gmail Drafts and Sent. If you find the draft, record its gmail_draft_id and set the state to complete. If you confirm no draft was created or sent, set the state to archived and run again.
Something didn’t work?
401: the API key is missing or invalid
Check the selected n8n credential, copy only the secret into Bearer Token, and check the key’s expiry and revocation status in Bitavu. The Studio sign-in cookie is not a substitute for the API key.
403: this key cannot access the report
In Bitavu Integrations, check that the key has Generate PDFs permission and access to the exact template ID. An owner or admin can edit the key’s access without changing its secret.
400, 404 or 422: request, template or data mismatch
Use a saved template ID and a positive numeric revision. Copy the tested request from Studio, keep data as a JSON object and match the required fields and types. Read Bitavu’s error message; adding the word “Bearer” inside n8n’s Bearer Token field also creates an invalid credential.
409: an operation conflict
Read the response code and message. If an idempotency key was reused with different input, use a new key for the new operation.
429 or a subscription/allowance error
Check Billing & usage in Bitavu. Wait for any Retry-After interval before retrying. For API_VERSION_LIMIT, reuse a permitted saved revision or wait for a slot in the rolling seven-day version window; changing the operation ID does not bypass that limit. A trial or subscription must be active and have enough remaining allowance; editing n8n does not increase the workspace’s quota.
The request succeeds but there is no downloadable file
Set Options → Response → Response Format to File and Put Output in Field to pdf. In later nodes, use the binary field named pdf rather than looking for a URL in the JSON output.
Still stuck? Tell us your n8n version, the failing step, HTTP status, error code and any support reference. Send only sample data or a screenshot with private values removed. Never include API keys, sign-in links or private document content.
Contact support