@docspring/node-red-docspring

Node-RED nodes for DocSpring: fill PDF forms, generate PDFs and Word documents, and collect e-signatures from your flows.

Version 1.0 calls DocSpring API v2. Upgrading from 0.1? See Upgrading from 0.1.

From the Node-RED editor: Menu → Manage palette → Install, search for @docspring/node-red-docspring. Or from your Node-RED user directory:

cd ~/.node-red
npm install @docspring/node-red-docspring

Restart Node-RED. The DocSpring node appears in the palette.

Add a DocSpring configuration (on the node, or via the config-nodes list): choose your Region (US / EU / Self-hosted), and paste the Token ID and Token Secret from the DocSpring web app (Settings → API Tokens). Click Test connection to confirm it works. Credentials are stored encrypted by Node-RED and never leave your instance. Test connection uses a saved Token Secret only with the saved region and host: to test a different one, type the Token Secret again.

Self-hosted (Enterprise) servers need a DocSpring release with API v2. If Test connection says your server doesn't have API v2 yet, upgrade it, or keep using version 0.1.0 of these nodes until you do.

Drop a DocSpring node into a flow, pick an Operation, and pass its inputs in msg.payload. The API's response is written back to msg.payload. Errors go to a Catch node, with DocSpring's message in msg.error.message and its error code in msg.error.code. You can override the operation per message with msg.operation (the value in brackets below).

The node's help (in the editor's Help sidebar) explains each input. A few that apply throughout:

• true/false and numbers can be strings, and objects and lists can be JSON strings.
• version is a published template version such as 1.2.0, latest (the default for making PDFs) or draft. Dates in data are YYYY-MM-DD.
• Operations that make a PDF wait for it. wait: false returns the record straight away, still pending.
• Each signer in a signature request needs fields: the names of the fields they fill in.
• DocSpring emails each signer their link (send_email is true by default), with any reminders and the signed PDF once everyone has signed; each signer then needs an email. Set email_subject, email_message, cc, reminders ({ interval_days, max_count }), reply_to, notification_emails and notify_when_signed as in the API. Set send_email to false to send the links yourself, or on a signer to send only theirs: those signers get a signing_url, and email is optional for one who signs in your own page through an api link. Email signing links last 7 days, API links 24 hours.
• signing_order: "sequential" has people sign one step at a time, by their signing_step or the order of the list.
• When the account reaches DocSpring's API rate limit (a 429), the node waits as long as DocSpring asks (up to a minute) and tries again, up to 3 times; then the error code is rate_limited. Each page of a large limit is a request, and test API tokens have a lower limit.
• Lists return { data, next_cursor }: pass next_cursor back as cursor for the next items. In Find Templates and Find Submissions, limit is how many to return (default 50), and above 100 the node gets several pages for you. List Folders returns one page (limit 1 to 100).

An inject node with this payload, wired into a DocSpring node (Operation: Generate PDF):

{ "template_id": "tpl_xxxxxxxxxxxxxxxxxxxx",
  "data": { "first_name": "Jane", "last_name": "Doe" },
  "test": true }

msg.payload then contains the submission; msg.payload.files.pdf.download_url is a link to the PDF.

1.0 uses DocSpring API v2, so the output of each operation changes. Flows saved with 0.1 keep most of their operations and inputs:

• findTemplate and findSubmission still work, as operation values and in msg.operation.
• The payload keys token_type, type: "live" | "test" and the combined_submission source type still work.
• limit is still how many templates or submissions to return, of any size (the default is now 50, not 20).

Signature requests use only their own names now, so update the nodes that make them:

• Open each saved Create Signature Request node and pick the operation again, and use createSignatureRequest in msg.operation.
• Send the signers as signature_requests (each with fields), and the ID as signature_request_id. Every signer is sent, so leave out rows for signers you don't need.

Check the nodes that read the output:

• The PDF link is files.pdf.download_url (it was download_url).
• Create Signature Request returns signature_requests and first_signature_request_id.
• Find Templates and Find Submissions return { data, next_cursor } instead of an array.
• Create Signing Link returns the token: the link is signature_request_url.

The API v2 migration guide lists everything that changed.

• DocSpring documentation
• API v2 reference
• Node-RED community nodes

MIT