Overview

This node operation "Add Extra Document From Template" under the Document resource allows users to add an additional document to an existing envelope by generating it from a predefined dynamic template. The extra document is created by specifying a template token and providing template variables that replace placeholders in the template.

This functionality is useful when you want to append customized documents to an existing signed or in-progress envelope without manually uploading files. For example, you might add a dynamically generated contract appendix or an additional terms document based on user-specific data.

Practical Example

• You have a main contract document already sent for signing.
• You want to add an extra document such as a personalized annex generated from a template.
• You provide the document token of the main contract, the template token of the annex template, and key-value pairs for template variables (e.g., client name, date).
• The node calls the API to generate and attach this extra document automatically.

Properties

Output

The node outputs a JSON array where each item corresponds to the result of adding the extra document from the template for each input item processed.

• The json output contains the API response from the ZapSign service after successfully adding the extra document.
• This typically includes details about the newly created extra document, such as its token, status, and metadata.
• No binary data output is involved in this operation.

Dependencies

• Requires an active connection to the ZapSign API with valid credentials (an API key or token).
• The environment must have the ZapSign API base URL configured, either for sandbox or production.
• The template token provided must correspond to an existing dynamic template in the ZapSign system.
• The document token must refer to an existing document/envelope in ZapSign.

Troubleshooting

Common Issues

• Missing required fields: The operation requires both the document token and the template token. Omitting these will cause errors.
• Invalid template token: If the template token is invalid or expired, the API will reject the request.
• Empty or invalid template variables: All variables must have both a non-empty name and value; otherwise, the API may fail or ignore them.
• API errors: Bad requests (HTTP 400) often indicate parameter issues such as missing tokens or malformed variable data.

Error Messages and Resolutions

• Bad request (400):
  Message: "Bad request - please check your parameters. Common issues: Template token is invalid or expired, Template variables have invalid names or values, Required fields are missing."
  Resolution: Verify that the template token is correct and active. Ensure all template variables have valid names and values. Confirm all required inputs are provided.

• Missing required fields error:
  Message: "Missing required fields for extra document creation: template_id. Please ensure you have provided a template token."
  Resolution: Provide a valid template token.

• No valid template variables warning:
  Message: "No valid template variables found. All variables must have both name and value."
  Resolution: Check the template variables collection and ensure each entry has both a variable name and a corresponding value.

Links and References

• ZapSign API Documentation (for detailed API endpoints and parameters)
• ZapSign Templates Guide (for managing and using templates)
• n8n Documentation on Creating Custom Nodes

Summary of execute() logic for "Add Extra Document From Template"

• Reads input items.
• For each item:
  • Retrieves documentToken, extraDocumentTemplateToken, and extraDocumentTemplateData.
  • Constructs a request body with template_id set to the template token.
  • Maps template variables from the input collection into an array of {de: variableName, para: variableValue} objects, filtering out empty entries.
  • Sends a POST request to /api/v1/docs/{documentToken}/extra-docs/ endpoint with the constructed body.
  • Handles errors, especially HTTP 400 Bad Request, providing helpful messages about common causes.
• Collects all responses and returns them as JSON output array.