turbodocx-sdk 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/LICENSE +21 -0
- data/README.md +1462 -0
- data/lib/turbodocx_sdk/client_context.rb +122 -0
- data/lib/turbodocx_sdk/constants.rb +184 -0
- data/lib/turbodocx_sdk/deliverable.rb +171 -0
- data/lib/turbodocx_sdk/errors.rb +63 -0
- data/lib/turbodocx_sdk/http_client.rb +418 -0
- data/lib/turbodocx_sdk/response_normalizer.rb +89 -0
- data/lib/turbodocx_sdk/turbo_partner.rb +470 -0
- data/lib/turbodocx_sdk/turbo_quote.rb +1186 -0
- data/lib/turbodocx_sdk/turbo_sign.rb +757 -0
- data/lib/turbodocx_sdk/turbo_webhooks.rb +325 -0
- data/lib/turbodocx_sdk.rb +15 -0
- metadata +76 -0
data/README.md
ADDED
|
@@ -0,0 +1,1462 @@
|
|
|
1
|
+
[](https://www.turbodocx.com)
|
|
2
|
+
|
|
3
|
+
<div align="center">
|
|
4
|
+
|
|
5
|
+
# turbodocx-sdk (Ruby)
|
|
6
|
+
|
|
7
|
+
**Official Ruby SDK for TurboDocx**
|
|
8
|
+
|
|
9
|
+
The most developer-friendly **DocuSign & PandaDoc alternative** for **e-signatures** and **document generation**. Send documents for signature and automate document workflows programmatically.
|
|
10
|
+
|
|
11
|
+
[](https://rubygems.org/gems/turbodocx-sdk)
|
|
12
|
+
[](./LICENSE)
|
|
13
|
+
[](https://agentskills.io)
|
|
14
|
+
[](https://github.com/TurboDocx/quickstart)
|
|
15
|
+
|
|
16
|
+
[Documentation](https://docs.turbodocx.com/docs) • [API Reference](https://docs.turbodocx.com/docs/SDKs/) • [Examples](#examples) • [Discord](https://discord.gg/NYKwz4BcpX)
|
|
17
|
+
|
|
18
|
+
</div>
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## Skip the boilerplate — let an agent scaffold it for you
|
|
23
|
+
|
|
24
|
+
Have an AI coding agent (Claude Code, Cursor, Copilot, Codex, Gemini CLI, OpenCode) install this SDK, configure your env, write working route handlers, and wire them into your app:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
npx skills add TurboDocx/quickstart
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Then run `/turbodocx-sdk` inside your agent — or one of the focused shortcuts:
|
|
31
|
+
|
|
32
|
+
| Shortcut | What it scaffolds |
|
|
33
|
+
|---|---|
|
|
34
|
+
| `/turbodocx-sdk turbosign` | Send documents for e-signature, check status, download signed PDF |
|
|
35
|
+
| `/turbodocx-sdk deliverable` | Generate documents from templates with variable substitution |
|
|
36
|
+
| `/turbodocx-sdk turbopartner` | Provision and manage customer organizations (partner accounts) |
|
|
37
|
+
| `/turbodocx-sdk turbowebhooks` | Subscribe to `signature.document.completed` events + verify HMAC |
|
|
38
|
+
| `/turbodocx-sdk turboquote` | Build and send sales quotes with line items, bundles, and price books |
|
|
39
|
+
|
|
40
|
+
The skill auto-detects your framework (Rails, Sinatra, Rack, …) and follows your existing project conventions. Source: [github.com/TurboDocx/quickstart](https://github.com/TurboDocx/quickstart).
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## Why TurboDocx?
|
|
45
|
+
|
|
46
|
+
A modern, developer-first alternative to legacy e-signature platforms:
|
|
47
|
+
|
|
48
|
+
| Looking for... | TurboDocx offers |
|
|
49
|
+
|----------------|------------------|
|
|
50
|
+
| DocuSign API alternative | Simple REST API, transparent pricing |
|
|
51
|
+
| PandaDoc alternative | Document generation + e-signatures in one SDK |
|
|
52
|
+
| HelloSign/Dropbox Sign alternative | Full API access, modern DX |
|
|
53
|
+
| Adobe Sign alternative | Quick integration, developer-friendly docs |
|
|
54
|
+
| SignNow alternative | Predictable costs, responsive support |
|
|
55
|
+
| Documint alternative | DOCX/PDF generation from templates |
|
|
56
|
+
| WebMerge alternative | Data-driven document automation |
|
|
57
|
+
|
|
58
|
+
**Other platforms we compare to:** SignRequest, SignEasy, Zoho Sign, Eversign, SignWell, Formstack Documents
|
|
59
|
+
|
|
60
|
+
### TurboDocx Ecosystem
|
|
61
|
+
|
|
62
|
+
| Package | Description |
|
|
63
|
+
|---------|-------------|
|
|
64
|
+
| [@turbodocx/html-to-docx](https://github.com/turbodocx/html-to-docx) | Convert HTML to DOCX - fastest JS library |
|
|
65
|
+
| [@turbodocx/n8n-nodes-turbodocx](https://github.com/turbodocx/n8n-nodes-turbodocx) | n8n community nodes for TurboDocx |
|
|
66
|
+
| [TurboDocx Writer](https://appsource.microsoft.com/product/office/WA200007397) | Microsoft Word add-in |
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## Features
|
|
71
|
+
|
|
72
|
+
- **Production-Ready** — Battle-tested, processing thousands of documents daily
|
|
73
|
+
- **Zero runtime dependencies** — Pure Ruby stdlib (`net/http`, `json`, `openssl`); nothing else to install
|
|
74
|
+
- **Idiomatic Ruby** — snake_case methods, keyword arguments, typed exception hierarchy
|
|
75
|
+
- **Static class pattern** — `configure` once, then call class methods; no instantiation required
|
|
76
|
+
- **Five modules** — TurboSign (e-signatures), Deliverable (document generation), TurboPartner (partner portal), TurboWebhooks (signature webhook), TurboQuote (CPQ)
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## Installation
|
|
81
|
+
|
|
82
|
+
Add to your `Gemfile`:
|
|
83
|
+
|
|
84
|
+
```ruby
|
|
85
|
+
gem "turbodocx-sdk"
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Then run:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
bundle install
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Or install directly:
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
gem install turbodocx-sdk
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## Install via AI Agent Skill
|
|
103
|
+
|
|
104
|
+
Let an AI coding agent set up this SDK for you with the [TurboDocx Quickstart Agent Skill](https://github.com/TurboDocx/quickstart):
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
npx skills add TurboDocx/quickstart
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Works with Claude Code, GitHub Copilot, Cursor, OpenCode, and other AI coding agents. The skill detects your language, installs the gem, and generates working integration code.
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## Quick Start
|
|
115
|
+
|
|
116
|
+
```ruby
|
|
117
|
+
require "turbodocx_sdk"
|
|
118
|
+
|
|
119
|
+
# 1. Configure with your API key and sender information
|
|
120
|
+
TurboDocxSdk::TurboSign.configure(
|
|
121
|
+
api_key: ENV["TURBODOCX_API_KEY"],
|
|
122
|
+
org_id: ENV["TURBODOCX_ORG_ID"],
|
|
123
|
+
sender_email: ENV["TURBODOCX_SENDER_EMAIL"], # REQUIRED
|
|
124
|
+
sender_name: ENV["TURBODOCX_SENDER_NAME"] # OPTIONAL
|
|
125
|
+
)
|
|
126
|
+
|
|
127
|
+
# 2. Send a document for signature
|
|
128
|
+
result = TurboDocxSdk::TurboSign.send_signature(
|
|
129
|
+
# Request-hash keys are camelCase — the SDK forwards the hash to the API
|
|
130
|
+
# as-is and does NOT convert snake_case. (Only method keyword args like
|
|
131
|
+
# configure(api_key:, sender_email:) are snake_case.)
|
|
132
|
+
fileLink: "https://example.com/contract.pdf",
|
|
133
|
+
documentName: "Partnership Agreement",
|
|
134
|
+
recipients: [
|
|
135
|
+
{ name: "John Doe", email: "john@example.com", signingOrder: 1 }
|
|
136
|
+
],
|
|
137
|
+
fields: [
|
|
138
|
+
{
|
|
139
|
+
type: "signature",
|
|
140
|
+
recipientEmail: "john@example.com",
|
|
141
|
+
template: { anchor: "{signature1}", placement: "replace",
|
|
142
|
+
size: { width: 100, height: 30 } }
|
|
143
|
+
}
|
|
144
|
+
]
|
|
145
|
+
)
|
|
146
|
+
|
|
147
|
+
puts "Document ID: #{result['documentId']}"
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## Configuration
|
|
153
|
+
|
|
154
|
+
```ruby
|
|
155
|
+
require "turbodocx_sdk"
|
|
156
|
+
|
|
157
|
+
TurboDocxSdk::TurboSign.configure(
|
|
158
|
+
api_key: "your-api-key", # REQUIRED
|
|
159
|
+
org_id: "your-org-id", # REQUIRED
|
|
160
|
+
sender_email: "you@company.com", # REQUIRED — reply-to for signature emails
|
|
161
|
+
sender_name: "Your Company" # OPTIONAL but strongly recommended
|
|
162
|
+
)
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
**Important:** `sender_email` is **REQUIRED**. It is used as the reply-to address for signature request emails and recorded as the sender in the audit trail. An API key has no mailbox of its own, so the API rejects a send without it rather than mailing from an unmonitored address. `sender_name` is optional — it defaults to the name of your API key.
|
|
166
|
+
|
|
167
|
+
### Environment Variables
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
# .env
|
|
171
|
+
TURBODOCX_API_KEY=your-api-key
|
|
172
|
+
TURBODOCX_ORG_ID=your-org-id
|
|
173
|
+
TURBODOCX_SENDER_EMAIL=you@company.com
|
|
174
|
+
TURBODOCX_SENDER_NAME=Your Company Name
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
## API Reference
|
|
180
|
+
|
|
181
|
+
### TurboSign
|
|
182
|
+
|
|
183
|
+
#### `configure(api_key:, org_id:, sender_email:, sender_name: nil, base_url: nil)`
|
|
184
|
+
|
|
185
|
+
Configure the TurboSign module. `sender_email` is required.
|
|
186
|
+
|
|
187
|
+
#### `create_signature_review_link(request)`
|
|
188
|
+
|
|
189
|
+
Upload a document for review **without** sending signature emails. Returns a preview URL you can share manually. Accepts the same request hash as `send_signature` (`file`, `fileLink`, `deliverableId`, or `templateId` as document source).
|
|
190
|
+
|
|
191
|
+
```ruby
|
|
192
|
+
result = TurboDocxSdk::TurboSign.create_signature_review_link(
|
|
193
|
+
fileLink: "https://example.com/contract.pdf",
|
|
194
|
+
recipients: [
|
|
195
|
+
{ name: "John Doe", email: "john@example.com", signingOrder: 1 }
|
|
196
|
+
],
|
|
197
|
+
fields: [
|
|
198
|
+
{ type: "signature", page: 1, x: 100, y: 500, width: 200, height: 50, recipientEmail: "john@example.com" }
|
|
199
|
+
],
|
|
200
|
+
documentName: "Service Agreement", # Optional
|
|
201
|
+
documentDescription: "Q4 Contract", # Optional
|
|
202
|
+
ccEmails: ["legal@acme.com"] # Optional
|
|
203
|
+
)
|
|
204
|
+
|
|
205
|
+
puts "Preview URL: #{result['previewUrl']}"
|
|
206
|
+
puts "Document ID: #{result['documentId']}"
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
#### `send_signature(request)`
|
|
210
|
+
|
|
211
|
+
Upload a document and send it for signature. Recipients are emailed their signing links unless you pass `sendEmail: false`.
|
|
212
|
+
|
|
213
|
+
Pass `fileName:` alongside `file:` to name the stored file: any non-empty name up to 255 characters, with or without an extension. Without it (or with an empty one) the file keeps the uploaded part's name: `document.<ext>` for an IO, or a file path's basename when it ends in `.pdf`, `.docx` or `.pptx` (otherwise `document.<ext>`). The document's display name is `documentName` when given, otherwise the stored file name up to its first `.`.
|
|
214
|
+
|
|
215
|
+
The request hash uses **camelCase** keys (`fileLink`, `documentName`, and inner `recipients`/`fields` keys like `signingOrder`/`recipientEmail`) — the SDK forwards them to the API unchanged and does not convert snake_case. Fields bind to a recipient via `recipientEmail`.
|
|
216
|
+
|
|
217
|
+
```ruby
|
|
218
|
+
result = TurboDocxSdk::TurboSign.send_signature(
|
|
219
|
+
fileLink: "https://example.com/contract.pdf",
|
|
220
|
+
recipients: [
|
|
221
|
+
{ name: "Alice", email: "alice@example.com", signingOrder: 1 },
|
|
222
|
+
{ name: "Bob", email: "bob@example.com", signingOrder: 2 }
|
|
223
|
+
],
|
|
224
|
+
fields: [
|
|
225
|
+
{ type: "signature", page: 1, x: 100, y: 500, width: 200, height: 50, recipientEmail: "alice@example.com" },
|
|
226
|
+
{ type: "signature", page: 1, x: 100, y: 600, width: 200, height: 50, recipientEmail: "bob@example.com" }
|
|
227
|
+
]
|
|
228
|
+
)
|
|
229
|
+
|
|
230
|
+
# The created recipients come back on the send result — each carries id, name and email.
|
|
231
|
+
# Signing links are emailed to them; they are not returned here.
|
|
232
|
+
result["recipients"].each do |r|
|
|
233
|
+
puts "#{r['name']} <#{r['email']}> — #{r['id']}"
|
|
234
|
+
end
|
|
235
|
+
|
|
236
|
+
# For signing progress afterwards, use get_recipients.
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
The document source can also be raw bytes or a local file path (`file: File.binread("contract.pdf")` or `file: "contract.pdf"` — the file type is detected from magic bytes), a TurboDocx deliverable (`deliverableId:`), or a TurboSign template (`templateId:`).
|
|
240
|
+
|
|
241
|
+
#### Send a template set up in TurboDocx (signer roles)
|
|
242
|
+
|
|
243
|
+
Upload a PDF as a template in TurboDocx, add its signers as roles (e.g. "Client", "Countersigner"),
|
|
244
|
+
drag their fields onto the page and save the signature setup. Then send it by naming each
|
|
245
|
+
recipient's `role`. The fields saved for that role come with it, so `fields` can be left out.
|
|
246
|
+
|
|
247
|
+
```ruby
|
|
248
|
+
# The role keys come from the template (also shown under "Use via API" on the template page)
|
|
249
|
+
setup = TurboDocxSdk::TurboSign.get_template_signature_setup("your-template-id")
|
|
250
|
+
setup["roles"].each { |r| puts "#{r['key']} (saved signer: #{r['hasSavedSigner']})" }
|
|
251
|
+
# client (saved signer: false)
|
|
252
|
+
# countersigner (saved signer: true)
|
|
253
|
+
|
|
254
|
+
TurboDocxSdk::TurboSign.send_signature(
|
|
255
|
+
templateId: "your-template-id",
|
|
256
|
+
recipients: [
|
|
257
|
+
{ role: "client", name: "Jane Doe", email: "jane@client.com" }
|
|
258
|
+
# "countersigner" left out: the signer saved on the template is used
|
|
259
|
+
]
|
|
260
|
+
)
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
- Roles sign in the order saved on the template; recipients without a `role` sign after them.
|
|
264
|
+
- A role left out uses the template's saved signer. If it has none, the API returns a 400 naming the role.
|
|
265
|
+
- An unknown role raises `TurboDocxSdk::ValidationError` listing the template's roles (`e.code == "UnknownSignerRole"`).
|
|
266
|
+
- Any `fields` you pass are added to the template's (for example an extra witness signature).
|
|
267
|
+
- Roles work on PDF templates. Without roles, `send_signature` needs `fields`: a send without them gets a 400 `FieldsRequired`. A review link (`create_signature_review_link`) can be created with no fields; you place them in the preview.
|
|
268
|
+
- `get_template_signature_setup` throws `TurboDocxSdk::NotFoundError` (404, code `SignatureSetupNotFound`) when the template has no saved signature setup, or is not a template in your organization.
|
|
269
|
+
- `role` works the same way on `create_signature_review_link` and `create_embedded_signature`.
|
|
270
|
+
|
|
271
|
+
#### `send_reminder(document_id, recipient_ids = nil)`
|
|
272
|
+
|
|
273
|
+
Send a standalone reminder to whoever's turn it is to sign. It is independent of the automatic
|
|
274
|
+
reminder cadence — it works even when reminders are disabled or the cap is spent, does not
|
|
275
|
+
consume that cap, and only emails signers at the CURRENT signing order. Omit the recipient ids
|
|
276
|
+
to remind everyone eligible; do **not** pass an empty array, which the API rejects.
|
|
277
|
+
|
|
278
|
+
Recipients verified with `external_idv` or `override` sign only through a single-use `create_signing_url` link and are never emailed: they come back as `skipped_requires_single_use_url`. Naming only such recipients raises `TurboDocxSdk::ConflictError` (409) with code `RecipientRequiresSingleUseUrl`.
|
|
279
|
+
|
|
280
|
+
```ruby
|
|
281
|
+
result = TurboDocxSdk::TurboSign.send_reminder("doc-uuid")
|
|
282
|
+
|
|
283
|
+
result["results"].each do |r|
|
|
284
|
+
# status is "sent", or a "skipped_*" reason (e.g. "skipped_wrong_order")
|
|
285
|
+
puts "#{r['recipientId']}: #{r['status']}"
|
|
286
|
+
end
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
Reminders and expiration can also be scheduled when you send. `send_signature` accepts optional
|
|
290
|
+
`remindersEnabled` / `reminderDelay` / `reminderInterval` / `maxReminders` and `expirationEnabled`
|
|
291
|
+
/ `expireAfter` / `expirationWarning` / `expirationWarningInterval` options — both features are
|
|
292
|
+
off by default, so omitting them preserves the original send behavior. These are camelCase like
|
|
293
|
+
every other send key, and each duration takes a `{ value:, unit: }` shape. The deadline is frozen
|
|
294
|
+
onto the document at send time and is then readable via `get_status(...)["expiresAt"]`.
|
|
295
|
+
|
|
296
|
+
```ruby
|
|
297
|
+
TurboDocxSdk::TurboSign.send_signature(
|
|
298
|
+
fileLink: "https://example.com/contract.pdf",
|
|
299
|
+
remindersEnabled: true,
|
|
300
|
+
reminderDelay: { value: 3, unit: "days" },
|
|
301
|
+
expirationEnabled: true,
|
|
302
|
+
expireAfter: { value: 14, unit: "days" }
|
|
303
|
+
# ...recipients, fields, etc.
|
|
304
|
+
)
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
#### `get_status(document_id)`
|
|
308
|
+
|
|
309
|
+
Check the document-level status. For per-recipient detail, use `get_recipients`.
|
|
310
|
+
|
|
311
|
+
```ruby
|
|
312
|
+
status = TurboDocxSdk::TurboSign.get_status("doc-uuid")
|
|
313
|
+
puts "Status: #{status['status']}" # "under_review" | "completed" | "voided" | "expired" | ...
|
|
314
|
+
# "expiresAt" is the signing-window deadline (ISO 8601), or nil when expiration is off.
|
|
315
|
+
puts "Expires: #{status['expiresAt'] || 'never'}"
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
#### `get_recipients(document_id)`
|
|
319
|
+
|
|
320
|
+
See who the document went to, who has signed, who you are still waiting on, and who sent it.
|
|
321
|
+
|
|
322
|
+
```ruby
|
|
323
|
+
result = TurboDocxSdk::TurboSign.get_recipients("doc-uuid")
|
|
324
|
+
|
|
325
|
+
sender = result["document"]["sentBy"]
|
|
326
|
+
puts "Sent by #{sender['name']} <#{sender['email']}>"
|
|
327
|
+
|
|
328
|
+
summary = result["summary"]
|
|
329
|
+
puts "#{summary['completed']} of #{summary['total']} signed, waiting on #{summary['waitingOn']}"
|
|
330
|
+
|
|
331
|
+
result["recipients"].each do |r|
|
|
332
|
+
# "pending" | "viewed" | "completed" | "voided" | "expired"
|
|
333
|
+
puts "#{r['name']} <#{r['email']}>: #{r['effectiveStatus']}"
|
|
334
|
+
puts " signed #{r['signedOn']}" if r["signedOn"]
|
|
335
|
+
puts " emailed #{r['delivery']['totalSent']}x"
|
|
336
|
+
end
|
|
337
|
+
|
|
338
|
+
# Who are we chasing?
|
|
339
|
+
chasing = result["recipients"].select { |r| %w[pending viewed].include?(r["effectiveStatus"]) }
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
**Two status fields, and they differ on purpose:**
|
|
343
|
+
|
|
344
|
+
| Field | Values | Use it for |
|
|
345
|
+
|---|---|---|
|
|
346
|
+
| `status` | `pending`, `viewed`, `completed` | The raw database value |
|
|
347
|
+
| `effectiveStatus` | `pending`, `viewed`, `completed`, `voided`, `expired` | Display |
|
|
348
|
+
|
|
349
|
+
The database has no per-recipient declined/voided/expired state, so on a voided or expired
|
|
350
|
+
document an unsigned signer still reads `pending` in `status`. `effectiveStatus` layers the
|
|
351
|
+
document's outcome on top — that's the one to show a user. A completed signature is never
|
|
352
|
+
revoked: someone who signed before the document was voided still reads `completed`.
|
|
353
|
+
|
|
354
|
+
`summary` counts by `effectiveStatus`, and `waitingOn` (pending + viewed) drops to zero once
|
|
355
|
+
the document is terminal.
|
|
356
|
+
|
|
357
|
+
**`delivery`** is that recipient's email history — `firstSentOn`, `lastSentOn`, `totalSent`,
|
|
358
|
+
`reminderCount`, `lastRemindedAt`, `warningCount`, `lastWarningAt`. It counts the signature
|
|
359
|
+
request, resends, reminders, expiry warnings and terminal notices. CC notifications are
|
|
360
|
+
excluded, since a CC address is not a signer.
|
|
361
|
+
|
|
362
|
+
Two `delivery` fields are easy to misread:
|
|
363
|
+
|
|
364
|
+
| Field | What it actually means |
|
|
365
|
+
|---|---|
|
|
366
|
+
| `reminderCount` | **Automatic (scheduled) reminders only** — the counter `maxReminders` caps. A manual "remind now" does **not** increment it (it must not consume the cap budget), though it does land in `totalSent`. So it can read `0` while reminder emails have genuinely been sent. |
|
|
367
|
+
| `lastRemindedAt` | **When the reminder cadence clock was last reset** — not necessarily when a reminder was sent. The initial signature-request send, each scheduled reminder, each manual "remind now" and each expiry warning all stamp it. A freshly-sent document therefore normally reads a non-null `lastRemindedAt` alongside `reminderCount` of `0`. |
|
|
368
|
+
|
|
369
|
+
`warningCount` and `lastWarningAt` are touched only by an expiry warning.
|
|
370
|
+
|
|
371
|
+
#### `download(document_id)`
|
|
372
|
+
|
|
373
|
+
Download the signed document as raw bytes.
|
|
374
|
+
|
|
375
|
+
```ruby
|
|
376
|
+
pdf_bytes = TurboDocxSdk::TurboSign.download("doc-uuid")
|
|
377
|
+
File.binwrite("signed-contract.pdf", pdf_bytes)
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
#### `void_document(document_id, reason)`
|
|
381
|
+
|
|
382
|
+
Cancel a signature request.
|
|
383
|
+
|
|
384
|
+
```ruby
|
|
385
|
+
TurboDocxSdk::TurboSign.void_document("doc-uuid", "Contract terms changed")
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
#### `resend_email(document_id, recipient_ids)`
|
|
389
|
+
|
|
390
|
+
Resend signature emails to specific recipients.
|
|
391
|
+
|
|
392
|
+
Recipients verified with `external_idv` or `override` are skipped (they sign only through a single-use `create_signing_url` link), and naming only such recipients raises `TurboDocxSdk::ConflictError` (409) with code `RecipientRequiresSingleUseUrl`.
|
|
393
|
+
|
|
394
|
+
```ruby
|
|
395
|
+
TurboDocxSdk::TurboSign.resend_email("doc-uuid", ["recipient-uuid-1"])
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
#### `get_audit_trail(document_id)`
|
|
399
|
+
|
|
400
|
+
Get the complete audit trail for a document, including all events and timestamps.
|
|
401
|
+
|
|
402
|
+
```ruby
|
|
403
|
+
audit = TurboDocxSdk::TurboSign.get_audit_trail("doc-uuid")
|
|
404
|
+
|
|
405
|
+
puts "Document: #{audit['document']['name']}"
|
|
406
|
+
|
|
407
|
+
audit["auditTrail"].each do |entry|
|
|
408
|
+
puts "#{entry['actionType']} at #{entry['timestamp']}"
|
|
409
|
+
puts " By: #{entry['user']['name']} (#{entry['user']['email']})" if entry["user"]
|
|
410
|
+
puts " Recipient: #{entry['recipient']['name']}" if entry["recipient"]
|
|
411
|
+
end
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
The audit trail includes a cryptographic hash chain for tamper-evidence verification.
|
|
415
|
+
|
|
416
|
+
---
|
|
417
|
+
|
|
418
|
+
### Deliverable (Document Generation)
|
|
419
|
+
|
|
420
|
+
The `Deliverable` module generates documents from TurboDocx templates with variable substitution, and manages/downloads the resulting deliverables.
|
|
421
|
+
|
|
422
|
+
#### Configuration
|
|
423
|
+
|
|
424
|
+
```ruby
|
|
425
|
+
require "turbodocx_sdk"
|
|
426
|
+
|
|
427
|
+
TurboDocxSdk::Deliverable.configure(
|
|
428
|
+
api_key: ENV["TURBODOCX_API_KEY"], # REQUIRED (or access_token)
|
|
429
|
+
org_id: ENV["TURBODOCX_ORG_ID"] # REQUIRED
|
|
430
|
+
# base_url: "https://api.turbodocx.com" # optional
|
|
431
|
+
)
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
`Deliverable` does **not** require `sender_email` — it never sends signature emails.
|
|
435
|
+
|
|
436
|
+
#### `generate_deliverable(request)`
|
|
437
|
+
|
|
438
|
+
Generate a new document from a template with variable substitution. Request-hash keys are camelCase (`templateId`).
|
|
439
|
+
|
|
440
|
+
```ruby
|
|
441
|
+
result = TurboDocxSdk::Deliverable.generate_deliverable(
|
|
442
|
+
"templateId" => "template-uuid",
|
|
443
|
+
"name" => "Q3 Statement of Work",
|
|
444
|
+
"variables" => [
|
|
445
|
+
{ "placeholder" => "{ClientName}", "text" => "Acme Corp" },
|
|
446
|
+
{ "placeholder" => "{StartDate}", "text" => "2026-08-01" }
|
|
447
|
+
],
|
|
448
|
+
"description" => "SOW for Acme", # Optional
|
|
449
|
+
"tags" => ["sow", "acme"] # Optional
|
|
450
|
+
)
|
|
451
|
+
|
|
452
|
+
deliverable = result["results"]["deliverable"]
|
|
453
|
+
puts "Deliverable ID: #{deliverable['id']}"
|
|
454
|
+
```
|
|
455
|
+
|
|
456
|
+
#### `list_deliverables(options = nil)`
|
|
457
|
+
|
|
458
|
+
List deliverables with pagination, search, and tag filtering.
|
|
459
|
+
|
|
460
|
+
```ruby
|
|
461
|
+
page = TurboDocxSdk::Deliverable.list_deliverables(limit: 25, offset: 0, query: "sow", show_tags: true)
|
|
462
|
+
puts "Total: #{page['totalRecords']}"
|
|
463
|
+
page["results"].each { |d| puts d["name"] }
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
#### `get_deliverable_details(id, options = nil)`
|
|
467
|
+
|
|
468
|
+
Get full details of a single deliverable, including variables, fonts, and template info.
|
|
469
|
+
|
|
470
|
+
```ruby
|
|
471
|
+
deliverable = TurboDocxSdk::Deliverable.get_deliverable_details("deliverable-uuid", show_tags: true)
|
|
472
|
+
puts deliverable["name"]
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
#### `update_deliverable_info(id, request)`
|
|
476
|
+
|
|
477
|
+
Update a deliverable's name, description, or tags. **Note:** when `tags` is provided, all existing tags are replaced.
|
|
478
|
+
|
|
479
|
+
```ruby
|
|
480
|
+
TurboDocxSdk::Deliverable.update_deliverable_info("deliverable-uuid",
|
|
481
|
+
"name" => "Q3 SOW (final)",
|
|
482
|
+
"description" => "Signed-off version"
|
|
483
|
+
)
|
|
484
|
+
```
|
|
485
|
+
|
|
486
|
+
#### `delete_deliverable(id)`
|
|
487
|
+
|
|
488
|
+
Soft-delete a deliverable.
|
|
489
|
+
|
|
490
|
+
```ruby
|
|
491
|
+
TurboDocxSdk::Deliverable.delete_deliverable("deliverable-uuid")
|
|
492
|
+
```
|
|
493
|
+
|
|
494
|
+
#### `download_source_file(deliverable_id)`
|
|
495
|
+
|
|
496
|
+
Download the original source file (DOCX or PPTX) as raw bytes.
|
|
497
|
+
|
|
498
|
+
```ruby
|
|
499
|
+
docx_bytes = TurboDocxSdk::Deliverable.download_source_file("deliverable-uuid")
|
|
500
|
+
File.binwrite("sow.docx", docx_bytes)
|
|
501
|
+
```
|
|
502
|
+
|
|
503
|
+
#### `download_pdf(deliverable_id)`
|
|
504
|
+
|
|
505
|
+
Download the PDF version as raw bytes.
|
|
506
|
+
|
|
507
|
+
```ruby
|
|
508
|
+
pdf_bytes = TurboDocxSdk::Deliverable.download_pdf("deliverable-uuid")
|
|
509
|
+
File.binwrite("sow.pdf", pdf_bytes)
|
|
510
|
+
```
|
|
511
|
+
|
|
512
|
+
#### Generate, then send for signature
|
|
513
|
+
|
|
514
|
+
`Deliverable` pairs naturally with `TurboSign` — generate a document, then send it without downloading:
|
|
515
|
+
|
|
516
|
+
```ruby
|
|
517
|
+
result = TurboDocxSdk::Deliverable.generate_deliverable(
|
|
518
|
+
"templateId" => "template-uuid",
|
|
519
|
+
"name" => "Consulting Agreement",
|
|
520
|
+
"variables" => [{ "placeholder" => "{ClientName}", "text" => "Acme Corp" }]
|
|
521
|
+
)
|
|
522
|
+
|
|
523
|
+
TurboDocxSdk::TurboSign.send_signature(
|
|
524
|
+
deliverableId: result["results"]["deliverable"]["id"],
|
|
525
|
+
recipients: [{ name: "John Doe", email: "john@example.com", signingOrder: 1 }],
|
|
526
|
+
fields: [
|
|
527
|
+
{ type: "signature", recipientEmail: "john@example.com",
|
|
528
|
+
template: { anchor: "{signature1}", placement: "replace", size: { width: 100, height: 30 } } }
|
|
529
|
+
]
|
|
530
|
+
)
|
|
531
|
+
```
|
|
532
|
+
|
|
533
|
+
---
|
|
534
|
+
|
|
535
|
+
### TurboPartner (Partner API)
|
|
536
|
+
|
|
537
|
+
The `TurboPartner` module provides partner portal operations for managing organizations, users, API keys, and audit logs.
|
|
538
|
+
|
|
539
|
+
#### Configuration
|
|
540
|
+
|
|
541
|
+
```ruby
|
|
542
|
+
require "turbodocx_sdk"
|
|
543
|
+
|
|
544
|
+
TurboDocxSdk::TurboPartner.configure(
|
|
545
|
+
partner_api_key: ENV["TURBODOCX_PARTNER_API_KEY"], # Must start with TDXP-
|
|
546
|
+
partner_id: ENV["TURBODOCX_PARTNER_ID"] # UUID format
|
|
547
|
+
)
|
|
548
|
+
```
|
|
549
|
+
|
|
550
|
+
**Environment Variables:**
|
|
551
|
+
|
|
552
|
+
```bash
|
|
553
|
+
TURBODOCX_PARTNER_API_KEY=TDXP-your-partner-api-key
|
|
554
|
+
TURBODOCX_PARTNER_ID=your-partner-uuid
|
|
555
|
+
```
|
|
556
|
+
|
|
557
|
+
#### Organization Management
|
|
558
|
+
|
|
559
|
+
```ruby
|
|
560
|
+
# Create an organization
|
|
561
|
+
org = TurboDocxSdk::TurboPartner.create_organization(
|
|
562
|
+
name: "Acme Corp",
|
|
563
|
+
features: { maxUsers: 50, hasTDAI: true }
|
|
564
|
+
)
|
|
565
|
+
puts "Org ID: #{org['data']['id']}"
|
|
566
|
+
|
|
567
|
+
# List organizations
|
|
568
|
+
orgs = TurboDocxSdk::TurboPartner.list_organizations(limit: 10, search: "acme")
|
|
569
|
+
|
|
570
|
+
# Get organization details (includes features + usage tracking)
|
|
571
|
+
details = TurboDocxSdk::TurboPartner.get_organization_details("org-uuid")
|
|
572
|
+
|
|
573
|
+
# Update organization
|
|
574
|
+
TurboDocxSdk::TurboPartner.update_organization_info("org-uuid", name: "New Name")
|
|
575
|
+
|
|
576
|
+
# Delete organization
|
|
577
|
+
TurboDocxSdk::TurboPartner.delete_organization("org-uuid")
|
|
578
|
+
|
|
579
|
+
# Update entitlements
|
|
580
|
+
TurboDocxSdk::TurboPartner.update_organization_entitlements("org-uuid",
|
|
581
|
+
features: { maxUsers: 100, hasTDAI: true }
|
|
582
|
+
)
|
|
583
|
+
|
|
584
|
+
# Read the org's TurboSign display preferences
|
|
585
|
+
# (returns only the partner-settable keys, with defaults applied)
|
|
586
|
+
prefs = TurboDocxSdk::TurboPartner.get_organization_preferences("org-uuid")["data"]["preferences"]
|
|
587
|
+
prefs["lockedFieldsBackground"] # => true by default
|
|
588
|
+
|
|
589
|
+
# Update them — pass only the keys you want to change; every other organization
|
|
590
|
+
# setting is preserved. Hash keys stay camelCase: they are the API contract, not
|
|
591
|
+
# Ruby names, and a snake_case key is dropped by the backend allowlist.
|
|
592
|
+
TurboDocxSdk::TurboPartner.update_organization_preferences("org-uuid",
|
|
593
|
+
"lockedFieldsBackground" => false
|
|
594
|
+
)
|
|
595
|
+
```
|
|
596
|
+
|
|
597
|
+
**Partner-settable display preferences**
|
|
598
|
+
|
|
599
|
+
| Key | Default | Effect |
|
|
600
|
+
|-----|---------|--------|
|
|
601
|
+
| `hideSignatureOutline` | `false` | Hide the outline/label drawn around signed fields |
|
|
602
|
+
| `hideSignatureHash` | `false` | Hide the verification hash printed on signed fields |
|
|
603
|
+
| `lockedFieldsBackground` | `true` | Grey box behind locked fields (`false` = plain text) |
|
|
604
|
+
| `allowDownloadBeforeSigning` | `false` | When enabled, a signer can download the unsigned PDF from the signing page before they sign it (for example, to review it with their legal team). Defaults to off. |
|
|
605
|
+
|
|
606
|
+
#### Organization User Management
|
|
607
|
+
|
|
608
|
+
```ruby
|
|
609
|
+
# List users
|
|
610
|
+
users = TurboDocxSdk::TurboPartner.list_organization_users("org-uuid")
|
|
611
|
+
|
|
612
|
+
# Add a user
|
|
613
|
+
TurboDocxSdk::TurboPartner.add_user_to_organization("org-uuid",
|
|
614
|
+
email: "user@example.com", role: "contributor"
|
|
615
|
+
)
|
|
616
|
+
|
|
617
|
+
# Update role
|
|
618
|
+
TurboDocxSdk::TurboPartner.update_organization_user_role("org-uuid", "user-uuid",
|
|
619
|
+
role: "admin"
|
|
620
|
+
)
|
|
621
|
+
|
|
622
|
+
# Remove user
|
|
623
|
+
TurboDocxSdk::TurboPartner.remove_user_from_organization("org-uuid", "user-uuid")
|
|
624
|
+
|
|
625
|
+
# Resend the org invitation email
|
|
626
|
+
TurboDocxSdk::TurboPartner.resend_organization_invitation_to_user("org-uuid", "user-uuid")
|
|
627
|
+
```
|
|
628
|
+
|
|
629
|
+
#### Organization API Key Management
|
|
630
|
+
|
|
631
|
+
```ruby
|
|
632
|
+
# List keys
|
|
633
|
+
keys = TurboDocxSdk::TurboPartner.list_organization_api_keys("org-uuid")
|
|
634
|
+
|
|
635
|
+
# Create key (full value returned only on creation)
|
|
636
|
+
key = TurboDocxSdk::TurboPartner.create_organization_api_key("org-uuid",
|
|
637
|
+
name: "Production Key", role: "admin"
|
|
638
|
+
)
|
|
639
|
+
puts "Key: #{key['data']['key']}" # TDX-... (only shown once)
|
|
640
|
+
|
|
641
|
+
# Update key
|
|
642
|
+
TurboDocxSdk::TurboPartner.update_organization_api_key("org-uuid", "key-uuid", name: "Renamed Key")
|
|
643
|
+
|
|
644
|
+
# Revoke key
|
|
645
|
+
TurboDocxSdk::TurboPartner.revoke_organization_api_key("org-uuid", "key-uuid")
|
|
646
|
+
```
|
|
647
|
+
|
|
648
|
+
#### Partner API Keys & Partner Portal Users
|
|
649
|
+
|
|
650
|
+
```ruby
|
|
651
|
+
# Create a scoped partner API key (full key value returned only on creation)
|
|
652
|
+
key = TurboDocxSdk::TurboPartner.create_partner_api_key(
|
|
653
|
+
name: "Read-Only Key",
|
|
654
|
+
scopes: ["org:read", "audit:read"]
|
|
655
|
+
)
|
|
656
|
+
|
|
657
|
+
# List / update / revoke partner API keys
|
|
658
|
+
TurboDocxSdk::TurboPartner.list_partner_api_keys(limit: 10)
|
|
659
|
+
TurboDocxSdk::TurboPartner.update_partner_api_key("key-uuid", name: "Renamed")
|
|
660
|
+
TurboDocxSdk::TurboPartner.revoke_partner_api_key("key-uuid")
|
|
661
|
+
|
|
662
|
+
# Add a user to the partner portal.
|
|
663
|
+
# `permissions` is all-or-nothing: every one of the seven keys must be present.
|
|
664
|
+
# A partial permissions hash is rejected with a 400.
|
|
665
|
+
TurboDocxSdk::TurboPartner.add_user_to_partner_portal(
|
|
666
|
+
email: "ops@company.com",
|
|
667
|
+
role: "member", # partner roles: "admin" | "member" | "viewer"
|
|
668
|
+
permissions: {
|
|
669
|
+
canManageOrgs: true,
|
|
670
|
+
canManageOrgUsers: true,
|
|
671
|
+
canManagePartnerUsers: false,
|
|
672
|
+
canManageOrgAPIKeys: false,
|
|
673
|
+
canManagePartnerAPIKeys: false,
|
|
674
|
+
canUpdateEntitlements: false,
|
|
675
|
+
canViewAuditLogs: true
|
|
676
|
+
}
|
|
677
|
+
)
|
|
678
|
+
|
|
679
|
+
# List / update / remove / re-invite partner portal users
|
|
680
|
+
TurboDocxSdk::TurboPartner.list_partner_portal_users(search: "ops")
|
|
681
|
+
|
|
682
|
+
# The `permissions` object is optional on update — but if you send it, send all
|
|
683
|
+
# seven keys. There is no partial permissions update.
|
|
684
|
+
TurboDocxSdk::TurboPartner.update_partner_user_permissions("user-uuid",
|
|
685
|
+
permissions: {
|
|
686
|
+
canManageOrgs: false,
|
|
687
|
+
canManageOrgUsers: true,
|
|
688
|
+
canManagePartnerUsers: false,
|
|
689
|
+
canManageOrgAPIKeys: false,
|
|
690
|
+
canManagePartnerAPIKeys: false,
|
|
691
|
+
canUpdateEntitlements: false,
|
|
692
|
+
canViewAuditLogs: true
|
|
693
|
+
}
|
|
694
|
+
)
|
|
695
|
+
TurboDocxSdk::TurboPartner.remove_user_from_partner_portal("user-uuid")
|
|
696
|
+
TurboDocxSdk::TurboPartner.resend_partner_portal_invitation_to_user("user-uuid")
|
|
697
|
+
```
|
|
698
|
+
|
|
699
|
+
**Partner permissions** — all seven keys are required whenever `permissions` is sent (booleans):
|
|
700
|
+
|
|
701
|
+
| Key | Grants |
|
|
702
|
+
|:----|:-------|
|
|
703
|
+
| `canManageOrgs` | Create / update / delete organizations |
|
|
704
|
+
| `canManageOrgUsers` | Manage users inside organizations |
|
|
705
|
+
| `canManagePartnerUsers` | Manage partner portal users |
|
|
706
|
+
| `canManageOrgAPIKeys` | Manage organization API keys |
|
|
707
|
+
| `canManagePartnerAPIKeys` | Manage partner API keys |
|
|
708
|
+
| `canUpdateEntitlements` | Update organization entitlements |
|
|
709
|
+
| `canViewAuditLogs` | Read the partner audit log |
|
|
710
|
+
|
|
711
|
+
**Role enums are different for orgs and partners** — do not mix them:
|
|
712
|
+
|
|
713
|
+
| Scope | Valid roles |
|
|
714
|
+
|:------|:------------|
|
|
715
|
+
| Org users, org API keys | `admin`, `contributor`, `user`, `viewer` |
|
|
716
|
+
| Partner portal users | `admin`, `member`, `viewer` |
|
|
717
|
+
|
|
718
|
+
#### Audit Logs
|
|
719
|
+
|
|
720
|
+
```ruby
|
|
721
|
+
logs = TurboDocxSdk::TurboPartner.get_partner_audit_logs(
|
|
722
|
+
action: "org.created",
|
|
723
|
+
startDate: "2025-01-01",
|
|
724
|
+
endDate: "2025-12-31",
|
|
725
|
+
limit: 100
|
|
726
|
+
)
|
|
727
|
+
|
|
728
|
+
logs["data"]["results"].each do |entry|
|
|
729
|
+
puts "#{entry['action']} - #{entry['createdOn']}"
|
|
730
|
+
end
|
|
731
|
+
```
|
|
732
|
+
|
|
733
|
+
#### All 25 Methods
|
|
734
|
+
|
|
735
|
+
| Category | Methods |
|
|
736
|
+
|:---------|:--------|
|
|
737
|
+
| **Organizations** | `create_organization`, `list_organizations`, `get_organization_details`, `update_organization_info`, `delete_organization`, `update_organization_entitlements` |
|
|
738
|
+
| **Org display preferences** | `get_organization_preferences`, `update_organization_preferences` |
|
|
739
|
+
| **Org Users** | `add_user_to_organization`, `list_organization_users`, `update_organization_user_role`, `remove_user_from_organization`, `resend_organization_invitation_to_user` |
|
|
740
|
+
| **Org API Keys** | `create_organization_api_key`, `list_organization_api_keys`, `update_organization_api_key`, `revoke_organization_api_key` |
|
|
741
|
+
| **Partner API Keys** | `create_partner_api_key`, `list_partner_api_keys`, `update_partner_api_key`, `revoke_partner_api_key` |
|
|
742
|
+
| **Partner Users** | `add_user_to_partner_portal`, `list_partner_portal_users`, `update_partner_user_permissions`, `remove_user_from_partner_portal`, `resend_partner_portal_invitation_to_user` |
|
|
743
|
+
| **Audit Logs** | `get_partner_audit_logs` |
|
|
744
|
+
|
|
745
|
+
---
|
|
746
|
+
|
|
747
|
+
### TurboWebhooks (Signature Webhook)
|
|
748
|
+
|
|
749
|
+
The `TurboWebhooks` module manages your organization's **signature webhook** — a single subscription to TurboDocx signature events. It also pairs with the `TurboDocxSdk.verify_webhook_signature` helper for incoming webhook receivers.
|
|
750
|
+
|
|
751
|
+
> **One webhook per org.** The SDK manages a single fixed-name webhook (`signature`) per org so SDK-managed and UI-managed webhooks stay in sync — what you create here also appears in the dashboard's Signature Webhooks settings page. To manage multiple webhooks per org, call the REST API directly.
|
|
752
|
+
>
|
|
753
|
+
> **Requires administrator role.** All webhook routes require an admin TDX- API key.
|
|
754
|
+
|
|
755
|
+
#### The 7 signature events
|
|
756
|
+
|
|
757
|
+
Use the `TurboDocxSdk::WebhookEvent` constants instead of hand-writing the wire strings — a typo becomes a `NameError` rather than a webhook that silently never fires.
|
|
758
|
+
|
|
759
|
+
| Event | Constant | Fires when |
|
|
760
|
+
|---|---|---|
|
|
761
|
+
| `signature.document.sent` | `WebhookEvent::SENT` | The document is dispatched to recipients |
|
|
762
|
+
| `signature.document.viewed` | `WebhookEvent::VIEWED` | A recipient opens the document for the first time |
|
|
763
|
+
| `signature.document.recipient_signed` | `WebhookEvent::RECIPIENT_SIGNED` | Any individual signer completes their signature — fires **once per signer**, and carries `is_final_signer` + `remaining_signers` |
|
|
764
|
+
| `signature.document.signed` | `WebhookEvent::SIGNED` | A signer signs but the document is **not yet complete** (document-level partial progress) |
|
|
765
|
+
| `signature.document.completed` | `WebhookEvent::COMPLETED` | All recipients have signed and the signed PDF is finalized |
|
|
766
|
+
| `signature.document.finalization_failed` | `WebhookEvent::FINALIZATION_FAILED` | The signed PDF fails to finalize (e.g. a KMS signing error); the document is **not** completed |
|
|
767
|
+
| `signature.document.voided` | `WebhookEvent::VOIDED` | The document is voided or cancelled |
|
|
768
|
+
|
|
769
|
+
On every signature, `recipient_signed` fires first, then **exactly one** document-level event:
|
|
770
|
+
|
|
771
|
+
```
|
|
772
|
+
Recipient signs
|
|
773
|
+
│
|
|
774
|
+
├─ signature.document.recipient_signed (always — one per signer)
|
|
775
|
+
│
|
|
776
|
+
└─ more signers remaining?
|
|
777
|
+
├─ yes → signature.document.signed (partial progress)
|
|
778
|
+
└─ no → signature.document.completed (finalized OK)
|
|
779
|
+
or signature.document.finalization_failed (finalization failed)
|
|
780
|
+
```
|
|
781
|
+
|
|
782
|
+
> **`signed` never fires on the final signature.** To detect "the whole document is done", subscribe to `completed` (or to `recipient_signed` and check `is_final_signer: true`) — **not** `signed`.
|
|
783
|
+
>
|
|
784
|
+
> **A single-signer document never emits `signed` at all.** It emits `recipient_signed` (with `is_final_signer: true`), then `completed`.
|
|
785
|
+
|
|
786
|
+
`TurboDocxSdk::WebhookEvent::ALL` is a frozen array of all 7 wire strings if you want to subscribe to everything. `events:` stays an array of plain strings, so the backend can add events without a gem release.
|
|
787
|
+
|
|
788
|
+
#### Configuration
|
|
789
|
+
|
|
790
|
+
```ruby
|
|
791
|
+
require "turbodocx_sdk"
|
|
792
|
+
|
|
793
|
+
TurboDocxSdk::TurboWebhooks.configure(
|
|
794
|
+
api_key: ENV["TURBODOCX_API_KEY"],
|
|
795
|
+
org_id: ENV["TURBODOCX_ORG_ID"]
|
|
796
|
+
# base_url: "https://api.turbodocx.com" # optional
|
|
797
|
+
)
|
|
798
|
+
```
|
|
799
|
+
|
|
800
|
+
Unlike `TurboSign`, `TurboWebhooks` does NOT require `sender_email` — webhook routes don't send signature emails.
|
|
801
|
+
|
|
802
|
+
#### Create the signature webhook (save the secret immediately)
|
|
803
|
+
|
|
804
|
+
```ruby
|
|
805
|
+
Events = TurboDocxSdk::WebhookEvent
|
|
806
|
+
|
|
807
|
+
created = TurboDocxSdk::TurboWebhooks.create_webhook(
|
|
808
|
+
urls: ["https://your-server.example.com/webhooks/turbodocx"], # HTTPS only, 1-10 urls
|
|
809
|
+
events: [
|
|
810
|
+
Events::SENT,
|
|
811
|
+
Events::VIEWED,
|
|
812
|
+
Events::RECIPIENT_SIGNED,
|
|
813
|
+
Events::COMPLETED,
|
|
814
|
+
Events::VOIDED
|
|
815
|
+
]
|
|
816
|
+
# ...or subscribe to everything: events: TurboDocxSdk::WebhookEvent::ALL
|
|
817
|
+
)
|
|
818
|
+
|
|
819
|
+
# `secret` is shown ONCE here. Store it securely; it cannot be retrieved later.
|
|
820
|
+
puts "Save this secret: #{created['secret']}"
|
|
821
|
+
```
|
|
822
|
+
|
|
823
|
+
If the signature webhook already exists, `create_webhook` raises `TurboDocxSdk::ConflictError` (409). Either update the existing one with `update_webhook` or `delete_webhook` first.
|
|
824
|
+
|
|
825
|
+
#### Get, update, delete
|
|
826
|
+
|
|
827
|
+
```ruby
|
|
828
|
+
webhook = TurboDocxSdk::TurboWebhooks.get_webhook
|
|
829
|
+
# webhook["deliveryStats"] and webhook["availableEvents"] are included
|
|
830
|
+
|
|
831
|
+
# Only the keywords you pass are sent; the rest are left untouched.
|
|
832
|
+
TurboDocxSdk::TurboWebhooks.update_webhook(is_active: false)
|
|
833
|
+
TurboDocxSdk::TurboWebhooks.update_webhook(
|
|
834
|
+
urls: ["https://new-endpoint.example.com/webhooks/turbodocx"],
|
|
835
|
+
events: ["signature.document.completed"]
|
|
836
|
+
)
|
|
837
|
+
TurboDocxSdk::TurboWebhooks.delete_webhook
|
|
838
|
+
```
|
|
839
|
+
|
|
840
|
+
> **`urls` and `events` can never be empty.** They stay `min(1)` on the backend even on update, so `urls: []` is a 400, not a "clear this field" instruction — and there is no way to remove every URL from a webhook. `update_webhook` raises `TurboDocxSdk::ValidationError` before hitting the wire if you pass an empty or `nil` array. To leave a field unchanged, just omit the keyword. `urls` accepts **1-10** entries.
|
|
841
|
+
|
|
842
|
+
#### Test deliveries and replay
|
|
843
|
+
|
|
844
|
+
```ruby
|
|
845
|
+
tested = TurboDocxSdk::TurboWebhooks.test_webhook(
|
|
846
|
+
event_type: "signature.document.completed",
|
|
847
|
+
payload: { "documentId" => "doc-xyz", "status" => "completed" }
|
|
848
|
+
)
|
|
849
|
+
puts tested["summary"] # { "total" => ..., "successful" => ..., "failed" => ... }
|
|
850
|
+
|
|
851
|
+
deliveries = TurboDocxSdk::TurboWebhooks.list_webhook_deliveries(limit: 10)
|
|
852
|
+
replayed = TurboDocxSdk::TurboWebhooks.replay_webhook_delivery(deliveries["results"][0]["id"])
|
|
853
|
+
```
|
|
854
|
+
|
|
855
|
+
`list_webhook_deliveries` accepts `limit:`, `offset:`, `event_type:`, `is_delivered:`, and `http_status:` filters. `notify_webhook(event_type:, payload:)` is also available and currently behaves identically to `test_webhook` — prefer `test_webhook` in new code.
|
|
856
|
+
|
|
857
|
+
#### Rotate the secret
|
|
858
|
+
|
|
859
|
+
```ruby
|
|
860
|
+
rotated = TurboDocxSdk::TurboWebhooks.regenerate_webhook_secret
|
|
861
|
+
# rotated["secret"] is the new secret. Old signatures will fail immediately.
|
|
862
|
+
```
|
|
863
|
+
|
|
864
|
+
#### Aggregate stats
|
|
865
|
+
|
|
866
|
+
```ruby
|
|
867
|
+
stats = TurboDocxSdk::TurboWebhooks.get_webhook_stats(days: 30)
|
|
868
|
+
puts stats["summary"]["successRate"]
|
|
869
|
+
puts stats["eventBreakdown"]
|
|
870
|
+
```
|
|
871
|
+
|
|
872
|
+
#### Verify incoming webhook signatures
|
|
873
|
+
|
|
874
|
+
Webhook deliveries from TurboDocx are signed with HMAC-SHA256 over `"#{timestamp}.#{raw_body}"` using your webhook secret. Use the free module function `TurboDocxSdk.verify_webhook_signature` in your receiver:
|
|
875
|
+
|
|
876
|
+
```ruby
|
|
877
|
+
# In your Rack/Rails webhook handler:
|
|
878
|
+
# CRITICAL: read the RAW body bytes. Do NOT parse-then-reserialize JSON first —
|
|
879
|
+
# the signature is over the exact bytes; re-serialization breaks verification.
|
|
880
|
+
raw_body = request.body.read
|
|
881
|
+
signature = request.get_header("HTTP_X_TURBODOCX_SIGNATURE") || ""
|
|
882
|
+
timestamp = request.get_header("HTTP_X_TURBODOCX_TIMESTAMP") || ""
|
|
883
|
+
secret = ENV["TURBODOCX_WEBHOOK_SECRET"]
|
|
884
|
+
|
|
885
|
+
unless TurboDocxSdk.verify_webhook_signature(
|
|
886
|
+
payload: raw_body,
|
|
887
|
+
signature_header: signature,
|
|
888
|
+
timestamp_header: timestamp,
|
|
889
|
+
secret: secret
|
|
890
|
+
)
|
|
891
|
+
return [401, {}, ["invalid signature"]]
|
|
892
|
+
end
|
|
893
|
+
|
|
894
|
+
event = JSON.parse(raw_body)
|
|
895
|
+
# ... process event ...
|
|
896
|
+
[200, {}, ["ok"]]
|
|
897
|
+
```
|
|
898
|
+
|
|
899
|
+
By default the helper enforces a 300-second timestamp tolerance to prevent replay attacks. Override with `tolerance_seconds: N` (`0` disables the check — not recommended in production; a negative value, NaN, `Infinity` or a non-number such as `"300"` fails closed and rejects every delivery). The `X-TurboDocx-Timestamp` header must be digits only. Comparison uses constant-time equality.
|
|
900
|
+
|
|
901
|
+
#### All Methods
|
|
902
|
+
|
|
903
|
+
| Category | Methods |
|
|
904
|
+
|:---------|:--------|
|
|
905
|
+
| **Configuration** | `configure` |
|
|
906
|
+
| **Webhook CRUD** | `create_webhook`, `get_webhook`, `update_webhook`, `delete_webhook` |
|
|
907
|
+
| **Testing** | `test_webhook`, `notify_webhook` |
|
|
908
|
+
| **Secret** | `regenerate_webhook_secret` |
|
|
909
|
+
| **Deliveries** | `list_webhook_deliveries`, `replay_webhook_delivery`, `get_webhook_stats` |
|
|
910
|
+
| **Receiver helper** | `TurboDocxSdk.verify_webhook_signature` (free module function — no API key needed) |
|
|
911
|
+
|
|
912
|
+
---
|
|
913
|
+
|
|
914
|
+
### TurboQuote (CPQ — Configure, Price, Quote)
|
|
915
|
+
|
|
916
|
+
The `TurboQuote` module provides end-to-end sales quoting: manage your product catalog (products, bundles, price books), companies and contacts, and assemble/send quotes with line items.
|
|
917
|
+
|
|
918
|
+
#### Configuration
|
|
919
|
+
|
|
920
|
+
```ruby
|
|
921
|
+
require "turbodocx_sdk"
|
|
922
|
+
|
|
923
|
+
TurboDocxSdk::TurboQuote.configure(
|
|
924
|
+
api_key: ENV["TURBODOCX_API_KEY"], # REQUIRED (or access_token)
|
|
925
|
+
org_id: ENV["TURBODOCX_ORG_ID"] # REQUIRED
|
|
926
|
+
# base_url: "https://api.turbodocx.com" # optional
|
|
927
|
+
)
|
|
928
|
+
```
|
|
929
|
+
|
|
930
|
+
`TurboQuote` does **not** require `sender_email` — use `api_key` + `org_id` only.
|
|
931
|
+
|
|
932
|
+
#### All 68 Methods
|
|
933
|
+
|
|
934
|
+
| Group | Methods |
|
|
935
|
+
|---|---|
|
|
936
|
+
| **Configuration** | `configure` |
|
|
937
|
+
| **Quotes** | `create_quote`, `get_quote`, `list_quotes`, `update_quote`, `delete_quote`, `duplicate_quote` |
|
|
938
|
+
| **Quote status transitions** | `send_quote`, `decline_quote`, `void_quote`, `handle_expired_quote` |
|
|
939
|
+
| **Quote extras** | `send_quote_with_deliverable`, `apply_price_book`, `remove_price_book`, `download_quote_pdf` |
|
|
940
|
+
| **Line items** | `add_line_items`, `add_bundle_line_items`, `list_line_items`, `update_line_item`, `remove_line_item` |
|
|
941
|
+
| **Products** | `create_product`, `bulk_create_products`, `get_product`, `list_products`, `update_product`, `delete_product`, `duplicate_product`, `get_product_primary_images` |
|
|
942
|
+
| **Bundles** | `create_bundle`, `bulk_create_bundles`, `get_bundle`, `list_bundles`, `update_bundle`, `delete_bundle`, `duplicate_bundle` |
|
|
943
|
+
| **Price books** | `create_price_book`, `bulk_create_price_books`, `get_price_book`, `list_price_books`, `update_price_book`, `delete_price_book`, `duplicate_price_book`, `list_price_book_products` |
|
|
944
|
+
| **Quote templates** | `get_template`, `get_template_by_id`, `list_templates`, `create_template`, `update_template`, `delete_template` |
|
|
945
|
+
| **Types / categories** | `create_type`, `bulk_create_types`, `list_types`, `update_type`, `delete_type` |
|
|
946
|
+
| **Companies** | `create_company`, `bulk_create_companies`, `get_company`, `list_companies`, `update_company`, `delete_company`, `list_company_contacts` |
|
|
947
|
+
| **Contacts** | `create_contact`, `bulk_create_contacts`, `list_contacts`, `update_contact`, `delete_contact` |
|
|
948
|
+
| **Quote number config (admin)** | `get_quote_number_config`, `update_quote_number_config` |
|
|
949
|
+
| **Convenience** | `create_and_send` |
|
|
950
|
+
|
|
951
|
+
#### Create a quote, add line items, and send
|
|
952
|
+
|
|
953
|
+
```ruby
|
|
954
|
+
require "turbodocx_sdk"
|
|
955
|
+
|
|
956
|
+
TurboDocxSdk::TurboQuote.configure(
|
|
957
|
+
api_key: ENV["TURBODOCX_API_KEY"],
|
|
958
|
+
org_id: ENV["TURBODOCX_ORG_ID"]
|
|
959
|
+
)
|
|
960
|
+
|
|
961
|
+
# 1. Create the quote
|
|
962
|
+
quote = TurboDocxSdk::TurboQuote.create_quote(
|
|
963
|
+
"name" => "Professional Services Q3 2026",
|
|
964
|
+
"companyId" => "company-uuid",
|
|
965
|
+
"contactId" => "contact-uuid",
|
|
966
|
+
"currency" => "USD",
|
|
967
|
+
"termDays" => 90, # optional; defaults to 60, max 3650
|
|
968
|
+
"validUntil" => "2026-09-30"
|
|
969
|
+
)
|
|
970
|
+
puts "Quote number: #{quote['quoteNumber']}"
|
|
971
|
+
|
|
972
|
+
# 2. Add a product line item with a percent discount
|
|
973
|
+
# (single hash is auto-wrapped into an array; 1-50 items per call)
|
|
974
|
+
# productId, productName, unitPrice and billingFrequency are all REQUIRED.
|
|
975
|
+
# productId may be nil for an ad-hoc item, but the key must be present.
|
|
976
|
+
items = TurboDocxSdk::TurboQuote.add_line_items(quote["id"],
|
|
977
|
+
"productId" => "product-uuid",
|
|
978
|
+
"productName" => "Consulting Service",
|
|
979
|
+
"unitPrice" => 500,
|
|
980
|
+
"billingFrequency" => TurboDocxSdk::BillingFrequency::MONTHLY,
|
|
981
|
+
"quantity" => 3,
|
|
982
|
+
"discountType" => TurboDocxSdk::DiscountType::PERCENT,
|
|
983
|
+
"discountPercent" => 10
|
|
984
|
+
)
|
|
985
|
+
puts "Line item ID: #{items[0]['id']}"
|
|
986
|
+
|
|
987
|
+
# 3. Send the quote
|
|
988
|
+
sent = TurboDocxSdk::TurboQuote.send_quote(quote["id"])
|
|
989
|
+
puts sent["message"]
|
|
990
|
+
```
|
|
991
|
+
|
|
992
|
+
#### Scheduling reminders and expiration on send
|
|
993
|
+
|
|
994
|
+
`send_quote` and `send_quote_with_deliverable` accept the same eight optional
|
|
995
|
+
reminder/expiration keys as `send_signature` — `remindersEnabled` / `reminderDelay` /
|
|
996
|
+
`reminderInterval` / `maxReminders` and `expirationEnabled` / `expireAfter` /
|
|
997
|
+
`expirationWarning` / `expirationWarningInterval`. They're camelCase like every other send key,
|
|
998
|
+
each duration takes a `{ value:, unit: }` shape, and they ride flat on the JSON body alongside
|
|
999
|
+
`ccEmails` / `validUntil`. Both features are off by default, so omitting them preserves the
|
|
1000
|
+
original send behavior.
|
|
1001
|
+
|
|
1002
|
+
**Quote expiry is pinned to `validUntil`.** When expiration is on, `expireAfter` is ignored —
|
|
1003
|
+
the quote already carries its own deadline — though `expirationEnabled` still toggles the
|
|
1004
|
+
feature. The reminder and expiration-warning cadence applies (layered over your org defaults)
|
|
1005
|
+
and must fit within `validUntil`, or the send is rejected.
|
|
1006
|
+
|
|
1007
|
+
```ruby
|
|
1008
|
+
TurboDocxSdk::TurboQuote.send_quote(quote["id"],
|
|
1009
|
+
"ccEmails" => ["legal@acme.com"],
|
|
1010
|
+
"validUntil" => "2026-09-30",
|
|
1011
|
+
"remindersEnabled" => true,
|
|
1012
|
+
"reminderDelay" => { "value" => 2, "unit" => "days" },
|
|
1013
|
+
"reminderInterval" => { "value" => 3, "unit" => "days" },
|
|
1014
|
+
"maxReminders" => 4,
|
|
1015
|
+
"expirationEnabled" => true,
|
|
1016
|
+
"expirationWarning" => { "value" => 2, "unit" => "days" }
|
|
1017
|
+
)
|
|
1018
|
+
```
|
|
1019
|
+
|
|
1020
|
+
#### Sender identity — "Prepared by"
|
|
1021
|
+
|
|
1022
|
+
The quote's **"Prepared by"** name and email are resolved by the server, not by whoever
|
|
1023
|
+
downloads or sends the quote. Precedence: the org **quote template's** sender fields first,
|
|
1024
|
+
then the quote's **creator**.
|
|
1025
|
+
|
|
1026
|
+
A quote created with an **API key** has no mailbox of its own — so its sender email can only
|
|
1027
|
+
come from the quote template. **If your org's quote template has no sender email set,
|
|
1028
|
+
`create_quote` (and `duplicate_quote`) raise `ValidationError` (`400 SenderEmailRequired`)** for
|
|
1029
|
+
an API-key caller. Set a sender email on the template once (via `update_template`) and every
|
|
1030
|
+
subsequent create/duplicate/send resolves cleanly. Human (JWT) callers are never blocked — their
|
|
1031
|
+
own email is the fallback.
|
|
1032
|
+
|
|
1033
|
+
`get_quote` returns the resolved identity under `"preparedBy"` — **prefer it over `"creator"`**
|
|
1034
|
+
for any customer-facing display (`"creator"` may be the internal API service account). The
|
|
1035
|
+
`"email"` key may be absent for an API-created quote:
|
|
1036
|
+
|
|
1037
|
+
```ruby
|
|
1038
|
+
quote = TurboDocxSdk::TurboQuote.get_quote(quote_id)
|
|
1039
|
+
prepared = quote["preparedBy"] || {}
|
|
1040
|
+
puts prepared["name"] # e.g. "Acme Billing Integration" or the template sender
|
|
1041
|
+
puts prepared["email"] # may be nil — render a placeholder
|
|
1042
|
+
```
|
|
1043
|
+
|
|
1044
|
+
#### Quote terms and auto-renewal
|
|
1045
|
+
|
|
1046
|
+
`termDays` defaults to **60** and accepts up to **3650** (10 years). The special value **`-1`** means auto-renewal, and it is the only case where `renewalPeriod` is allowed — in fact it is then **required**:
|
|
1047
|
+
|
|
1048
|
+
```ruby
|
|
1049
|
+
# Auto-renewing quote: termDays == -1 REQUIRES renewalPeriod
|
|
1050
|
+
TurboDocxSdk::TurboQuote.create_quote(
|
|
1051
|
+
"name" => "Managed Services (auto-renew)",
|
|
1052
|
+
"companyId" => "company-uuid",
|
|
1053
|
+
"contactId" => "contact-uuid",
|
|
1054
|
+
"termDays" => -1,
|
|
1055
|
+
"renewalPeriod" => TurboDocxSdk::RenewalPeriod::MONTHLY # weekly | monthly | quarterly | annually
|
|
1056
|
+
)
|
|
1057
|
+
```
|
|
1058
|
+
|
|
1059
|
+
For any other `termDays`, `renewalPeriod` must be omitted (or `nil`) — sending it is a 400.
|
|
1060
|
+
|
|
1061
|
+
#### Handling an expired quote
|
|
1062
|
+
|
|
1063
|
+
`handle_expired_quote` voids or declines an expired **sent** quote and creates a duplicate carrying the new validity date. All three keys are required, and `action` accepts **only** `"void"` or `"decline"`:
|
|
1064
|
+
|
|
1065
|
+
```ruby
|
|
1066
|
+
replacement = TurboDocxSdk::TurboQuote.handle_expired_quote(quote["id"],
|
|
1067
|
+
"action" => "void", # "void" or "decline" — nothing else is accepted
|
|
1068
|
+
"reason" => "Pricing refreshed for Q4", # REQUIRED, max 190 chars
|
|
1069
|
+
"newValidUntil" => "2026-12-31" # REQUIRED, ISO 8601
|
|
1070
|
+
)
|
|
1071
|
+
puts replacement["quoteNumber"] # the new duplicate quote
|
|
1072
|
+
```
|
|
1073
|
+
|
|
1074
|
+
#### Download a quote as PDF
|
|
1075
|
+
|
|
1076
|
+
```ruby
|
|
1077
|
+
pdf_bytes = TurboDocxSdk::TurboQuote.download_quote_pdf(quote["id"])
|
|
1078
|
+
File.binwrite("quote.pdf", pdf_bytes)
|
|
1079
|
+
```
|
|
1080
|
+
|
|
1081
|
+
#### Create and send in one call
|
|
1082
|
+
|
|
1083
|
+
```ruby
|
|
1084
|
+
result = TurboDocxSdk::TurboQuote.create_and_send(
|
|
1085
|
+
"name" => "Enterprise License",
|
|
1086
|
+
"companyId" => "company-uuid",
|
|
1087
|
+
"contactId" => "contact-uuid",
|
|
1088
|
+
"items" => [
|
|
1089
|
+
{ "productId" => "product-uuid", "productName" => "Platform License",
|
|
1090
|
+
"unitPrice" => 1200, "quantity" => 5, "billingFrequency" => "annual" }
|
|
1091
|
+
]
|
|
1092
|
+
# "bundleItems" => [...], # optional bundle line items
|
|
1093
|
+
# "send" => {...} # optional send options
|
|
1094
|
+
)
|
|
1095
|
+
puts result["quote"]["status"] # "sent"
|
|
1096
|
+
```
|
|
1097
|
+
|
|
1098
|
+
#### Bulk create (CSV-style imports)
|
|
1099
|
+
|
|
1100
|
+
Six catalog resources support bulk creation: `bulk_create_products`, `bulk_create_bundles`, `bulk_create_price_books`, `bulk_create_companies`, `bulk_create_contacts`, and `bulk_create_types`. Each takes an **array of row hashes** (same field shapes as the corresponding single `create_*` method); the SDK wraps them in the `{ "rows" => [...] }` envelope the API expects.
|
|
1101
|
+
|
|
1102
|
+
```ruby
|
|
1103
|
+
# Every product row requires name, categoryId, listPrice and billingFrequency.
|
|
1104
|
+
# `categoryId` is a TurboQuote type UUID — there is no `categoryName` shorthand;
|
|
1105
|
+
# resolve or create the category first (`list_types` / `create_type`) and pass its ID.
|
|
1106
|
+
category = TurboDocxSdk::TurboQuote.create_type(
|
|
1107
|
+
"name" => "Plans",
|
|
1108
|
+
"categoryType" => TurboDocxSdk::CategoryType::PRODUCT_CATEGORY
|
|
1109
|
+
)
|
|
1110
|
+
|
|
1111
|
+
report = TurboDocxSdk::TurboQuote.bulk_create_products([
|
|
1112
|
+
{ "name" => "Basic Plan", "categoryId" => category["id"], "listPrice" => 10, "billingFrequency" => "monthly" },
|
|
1113
|
+
{ "name" => "Premium Plan", "categoryId" => category["id"], "listPrice" => 100, "billingFrequency" => "monthly" }
|
|
1114
|
+
])
|
|
1115
|
+
|
|
1116
|
+
puts "Imported: #{report['imported']}"
|
|
1117
|
+
|
|
1118
|
+
report["failed"].each do |f|
|
|
1119
|
+
puts "Row #{f['row']} failed: #{f['reason']}" # "row" is 1-indexed
|
|
1120
|
+
end
|
|
1121
|
+
|
|
1122
|
+
report["adjusted"].each do |a|
|
|
1123
|
+
puts "Row #{a['row']} adjusted: #{a['reason']}" # server tweaked the row (e.g. defaults)
|
|
1124
|
+
end
|
|
1125
|
+
```
|
|
1126
|
+
|
|
1127
|
+
Bulk-create semantics:
|
|
1128
|
+
|
|
1129
|
+
- **Partial success** — a failed row does NOT raise and does NOT roll back earlier rows; it is reported in `"failed"` with a 1-indexed `"row"` and a `"reason"`. Server-adjusted rows appear in `"adjusted"`.
|
|
1130
|
+
- **500-row cap** per request — the API returns a 400 (`ValidationError`) above the cap. The SDK does not validate rows or the cap client-side.
|
|
1131
|
+
- **Roles** — available to administrator and contributor API keys.
|
|
1132
|
+
|
|
1133
|
+
#### Quote number configuration (admin only)
|
|
1134
|
+
|
|
1135
|
+
Read and update the org-wide quote-number format. Both methods return `{ "format" => {...}, "currentFloor" => Integer }`.
|
|
1136
|
+
|
|
1137
|
+
```ruby
|
|
1138
|
+
config = TurboDocxSdk::TurboQuote.get_quote_number_config
|
|
1139
|
+
puts config["format"]["prefix"]
|
|
1140
|
+
puts config["currentFloor"]
|
|
1141
|
+
|
|
1142
|
+
# update_quote_number_config takes the FULL format hash — all keys required, camelCase
|
|
1143
|
+
updated = TurboDocxSdk::TurboQuote.update_quote_number_config(
|
|
1144
|
+
"prefix" => "Q",
|
|
1145
|
+
"yearToken" => TurboDocxSdk::QuoteNumberYearToken::FOUR, # "none" | "two" | "four"
|
|
1146
|
+
"monthToken" => TurboDocxSdk::QuoteNumberMonthToken::TWO, # "off" | "two"
|
|
1147
|
+
"separator" => "-",
|
|
1148
|
+
"padWidth" => 4, # 0-12
|
|
1149
|
+
"suffix" => "",
|
|
1150
|
+
"startNumber" => 1, # >= 0
|
|
1151
|
+
"resetCadence" => TurboDocxSdk::QuoteNumberResetCadence::YEARLY # "never" | "yearly" | "monthly"
|
|
1152
|
+
)
|
|
1153
|
+
```
|
|
1154
|
+
|
|
1155
|
+
Non-admin callers receive `TurboDocxSdk::AuthorizationError`.
|
|
1156
|
+
|
|
1157
|
+
---
|
|
1158
|
+
|
|
1159
|
+
## Field Types
|
|
1160
|
+
|
|
1161
|
+
| Type | Description |
|
|
1162
|
+
|:-----|:------------|
|
|
1163
|
+
| `signature` | Signature field (draw or type) |
|
|
1164
|
+
| `initial` | Initials field |
|
|
1165
|
+
| `text` | Free-form text input |
|
|
1166
|
+
| `date` | Date stamp |
|
|
1167
|
+
| `checkbox` | Checkbox / agreement |
|
|
1168
|
+
| `full_name` | Full name |
|
|
1169
|
+
| `first_name` | First name |
|
|
1170
|
+
| `last_name` | Last name |
|
|
1171
|
+
| `email` | Email address |
|
|
1172
|
+
| `title` | Job title |
|
|
1173
|
+
| `company` | Company name |
|
|
1174
|
+
|
|
1175
|
+
The `checkbox` type doubles as the **controlling** field for conditional logic (see below).
|
|
1176
|
+
|
|
1177
|
+
### Conditional (IF/THEN) Fields
|
|
1178
|
+
|
|
1179
|
+
Any field hash may carry an optional `"metadata"` key that drives conditional logic. Set
|
|
1180
|
+
`metadata.fieldKey` on a **controlling** `checkbox` to give it a stable id, then set
|
|
1181
|
+
`metadata.conditional` on a **dependent** field that references that id. Field hashes are passed
|
|
1182
|
+
through verbatim, so the keys stay **camelCase**:
|
|
1183
|
+
|
|
1184
|
+
```ruby
|
|
1185
|
+
"fields" => [
|
|
1186
|
+
# Controlling checkbox — carries the fieldKey dependents reference
|
|
1187
|
+
{
|
|
1188
|
+
"type" => "checkbox",
|
|
1189
|
+
"recipientEmail" => "john@example.com",
|
|
1190
|
+
"template" => { "anchor" => "{request_changes}", "placement" => "replace", "size" => { "width" => 20, "height" => 20 } },
|
|
1191
|
+
"metadata" => { "fieldKey" => "request_changes" }
|
|
1192
|
+
},
|
|
1193
|
+
# Dependent text field — hidden until the checkbox is checked ("If checked, explain")
|
|
1194
|
+
{
|
|
1195
|
+
"type" => "text",
|
|
1196
|
+
"recipientEmail" => "john@example.com",
|
|
1197
|
+
"isMultiline" => true,
|
|
1198
|
+
"template" => { "anchor" => "{change_details}", "placement" => "replace", "size" => { "width" => 200, "height" => 50 } },
|
|
1199
|
+
"metadata" => {
|
|
1200
|
+
"conditional" => {
|
|
1201
|
+
"controllingFieldKey" => "request_changes", # must equal the checkbox's fieldKey
|
|
1202
|
+
"operator" => "is_checked", # "is_checked" | "is_not_checked"
|
|
1203
|
+
"action" => "show" # "show" (hidden until met) | "unlock" (read-only until met)
|
|
1204
|
+
}
|
|
1205
|
+
}
|
|
1206
|
+
}
|
|
1207
|
+
]
|
|
1208
|
+
```
|
|
1209
|
+
|
|
1210
|
+
| `metadata` key | Set on | Meaning |
|
|
1211
|
+
|:---------------|:-------|:--------|
|
|
1212
|
+
| `fieldKey` | controlling `checkbox` | Stable client id (≤100 chars) that dependents reference |
|
|
1213
|
+
| `conditional.controllingFieldKey` | dependent field | Must equal the controlling checkbox's `fieldKey` |
|
|
1214
|
+
| `conditional.operator` | dependent field | `"is_checked"` or `"is_not_checked"` |
|
|
1215
|
+
| `conditional.action` | dependent field | `"show"` (hidden until met) or `"unlock"` (visible but read-only until met) |
|
|
1216
|
+
|
|
1217
|
+
---
|
|
1218
|
+
|
|
1219
|
+
## Constants
|
|
1220
|
+
|
|
1221
|
+
The SDK exposes idiomatic constants to avoid hard-coding string literals:
|
|
1222
|
+
|
|
1223
|
+
```ruby
|
|
1224
|
+
TurboDocxSdk::QuoteStatus::DRAFT # "draft"
|
|
1225
|
+
TurboDocxSdk::QuoteStatus::SENT # "sent"
|
|
1226
|
+
TurboDocxSdk::BillingFrequency::MONTHLY # "monthly"
|
|
1227
|
+
TurboDocxSdk::BillingFrequency::ANNUAL # "annual"
|
|
1228
|
+
TurboDocxSdk::DiscountType::PERCENT # "percent"
|
|
1229
|
+
TurboDocxSdk::DiscountType::AMOUNT # "amount"
|
|
1230
|
+
TurboDocxSdk::Currency::USD # "USD"
|
|
1231
|
+
TurboDocxSdk::LineItemType::PRODUCT # "product"
|
|
1232
|
+
TurboDocxSdk::CategoryType::PRODUCT_CATEGORY # "product_category"
|
|
1233
|
+
|
|
1234
|
+
# Quote number configuration
|
|
1235
|
+
TurboDocxSdk::QuoteNumberYearToken::FOUR # "four"
|
|
1236
|
+
TurboDocxSdk::QuoteNumberMonthToken::TWO # "two"
|
|
1237
|
+
TurboDocxSdk::QuoteNumberResetCadence::NEVER # "never"
|
|
1238
|
+
|
|
1239
|
+
# Partner API key permission scopes
|
|
1240
|
+
TurboDocxSdk::PartnerScope::ORG_READ # "org:read"
|
|
1241
|
+
TurboDocxSdk::PartnerScope::AUDIT_READ # "audit:read"
|
|
1242
|
+
```
|
|
1243
|
+
|
|
1244
|
+
Each constants module also exposes an `ALL` array of its valid values (e.g. `TurboDocxSdk::DiscountType::ALL`).
|
|
1245
|
+
|
|
1246
|
+
---
|
|
1247
|
+
|
|
1248
|
+
## Examples
|
|
1249
|
+
|
|
1250
|
+
For complete, working examples, see the [`examples/`](./examples/) directory:
|
|
1251
|
+
|
|
1252
|
+
- [`turbosign_basic.rb`](./examples/turbosign_basic.rb) — Send a document for signature, poll status, download the signed PDF
|
|
1253
|
+
- [`turbosign_template_roles.rb`](./examples/turbosign_template_roles.rb) — Send a template set up in TurboDocx by naming each signer's role
|
|
1254
|
+
- [`turbowebhooks_crud.rb`](./examples/turbowebhooks_crud.rb) — Create/get/update/delete the signature webhook + verify HMAC signatures
|
|
1255
|
+
- [`turboquote_basic.rb`](./examples/turboquote_basic.rb) — Full quote lifecycle: create company, quote, line items, download PDF, send
|
|
1256
|
+
- [`turboquote_products.rb`](./examples/turboquote_products.rb) — Products and bundles catalog management
|
|
1257
|
+
- [`turboquote_pricebooks.rb`](./examples/turboquote_pricebooks.rb) — Price books with per-product overrides, apply to quote
|
|
1258
|
+
|
|
1259
|
+
### Sequential Signing
|
|
1260
|
+
|
|
1261
|
+
```ruby
|
|
1262
|
+
result = TurboDocxSdk::TurboSign.send_signature(
|
|
1263
|
+
fileLink: "https://example.com/contract.pdf",
|
|
1264
|
+
recipients: [
|
|
1265
|
+
{ name: "Employee", email: "employee@company.com", signingOrder: 1 },
|
|
1266
|
+
{ name: "Manager", email: "manager@company.com", signingOrder: 2 },
|
|
1267
|
+
{ name: "HR", email: "hr@company.com", signingOrder: 3 }
|
|
1268
|
+
],
|
|
1269
|
+
fields: [
|
|
1270
|
+
# Employee signs first
|
|
1271
|
+
{ type: "signature", recipientEmail: "employee@company.com", page: 1, x: 100, y: 400, width: 200, height: 50 },
|
|
1272
|
+
{ type: "date", recipientEmail: "employee@company.com", page: 1, x: 320, y: 400, width: 100, height: 30 },
|
|
1273
|
+
# Manager signs second
|
|
1274
|
+
{ type: "signature", recipientEmail: "manager@company.com", page: 1, x: 100, y: 500, width: 200, height: 50 },
|
|
1275
|
+
# HR signs last
|
|
1276
|
+
{ type: "signature", recipientEmail: "hr@company.com", page: 1, x: 100, y: 600, width: 200, height: 50 }
|
|
1277
|
+
]
|
|
1278
|
+
)
|
|
1279
|
+
```
|
|
1280
|
+
|
|
1281
|
+
### Polling for Completion
|
|
1282
|
+
|
|
1283
|
+
```ruby
|
|
1284
|
+
def wait_for_completion(document_id, max_attempts: 60)
|
|
1285
|
+
max_attempts.times do
|
|
1286
|
+
status = TurboDocxSdk::TurboSign.get_status(document_id)
|
|
1287
|
+
|
|
1288
|
+
return TurboDocxSdk::TurboSign.download(document_id) if status["status"] == "completed"
|
|
1289
|
+
raise "Document was voided" if status["status"] == "voided"
|
|
1290
|
+
|
|
1291
|
+
sleep 30
|
|
1292
|
+
end
|
|
1293
|
+
|
|
1294
|
+
raise "Timeout waiting for signatures"
|
|
1295
|
+
end
|
|
1296
|
+
```
|
|
1297
|
+
|
|
1298
|
+
### With Rails
|
|
1299
|
+
|
|
1300
|
+
```ruby
|
|
1301
|
+
# config/initializers/turbodocx.rb
|
|
1302
|
+
require "turbodocx_sdk"
|
|
1303
|
+
|
|
1304
|
+
TurboDocxSdk::TurboSign.configure(
|
|
1305
|
+
api_key: ENV["TURBODOCX_API_KEY"],
|
|
1306
|
+
org_id: ENV["TURBODOCX_ORG_ID"],
|
|
1307
|
+
sender_email: ENV["TURBODOCX_SENDER_EMAIL"]
|
|
1308
|
+
)
|
|
1309
|
+
|
|
1310
|
+
# app/controllers/contracts_controller.rb
|
|
1311
|
+
class ContractsController < ApplicationController
|
|
1312
|
+
def create
|
|
1313
|
+
result = TurboDocxSdk::TurboSign.send_signature(
|
|
1314
|
+
fileLink: params[:pdf_url],
|
|
1315
|
+
recipients: params[:recipients],
|
|
1316
|
+
fields: params[:fields]
|
|
1317
|
+
)
|
|
1318
|
+
render json: { success: true, document_id: result["documentId"] }
|
|
1319
|
+
rescue TurboDocxSdk::TurboDocxError => e
|
|
1320
|
+
render json: { error: e.message }, status: e.status_code || 500
|
|
1321
|
+
end
|
|
1322
|
+
end
|
|
1323
|
+
```
|
|
1324
|
+
|
|
1325
|
+
### With Sinatra
|
|
1326
|
+
|
|
1327
|
+
```ruby
|
|
1328
|
+
require "sinatra"
|
|
1329
|
+
require "json"
|
|
1330
|
+
require "turbodocx_sdk"
|
|
1331
|
+
|
|
1332
|
+
TurboDocxSdk::TurboSign.configure(
|
|
1333
|
+
api_key: ENV["TURBODOCX_API_KEY"],
|
|
1334
|
+
org_id: ENV["TURBODOCX_ORG_ID"],
|
|
1335
|
+
sender_email: ENV["TURBODOCX_SENDER_EMAIL"]
|
|
1336
|
+
)
|
|
1337
|
+
|
|
1338
|
+
post "/api/send-contract" do
|
|
1339
|
+
body = JSON.parse(request.body.read)
|
|
1340
|
+
result = TurboDocxSdk::TurboSign.send_signature(
|
|
1341
|
+
fileLink: body["pdf_url"],
|
|
1342
|
+
recipients: body["recipients"],
|
|
1343
|
+
fields: body["fields"]
|
|
1344
|
+
)
|
|
1345
|
+
json_response = { success: true, document_id: result["documentId"] }
|
|
1346
|
+
content_type :json
|
|
1347
|
+
json_response.to_json
|
|
1348
|
+
end
|
|
1349
|
+
```
|
|
1350
|
+
|
|
1351
|
+
---
|
|
1352
|
+
|
|
1353
|
+
## Error Handling
|
|
1354
|
+
|
|
1355
|
+
```ruby
|
|
1356
|
+
require "turbodocx_sdk"
|
|
1357
|
+
|
|
1358
|
+
begin
|
|
1359
|
+
TurboDocxSdk::TurboSign.get_status("invalid-id")
|
|
1360
|
+
rescue TurboDocxSdk::NotFoundError => e
|
|
1361
|
+
puts "Not found: #{e.message}"
|
|
1362
|
+
rescue TurboDocxSdk::AuthenticationError => e
|
|
1363
|
+
puts "Auth failed (#{e.status_code}): #{e.message}"
|
|
1364
|
+
rescue TurboDocxSdk::ValidationError => e
|
|
1365
|
+
puts "Validation error: #{e.message}"
|
|
1366
|
+
rescue TurboDocxSdk::RateLimitError
|
|
1367
|
+
puts "Rate limited — slow down requests"
|
|
1368
|
+
rescue TurboDocxSdk::TurboDocxError => e
|
|
1369
|
+
puts "TurboDocx error (#{e.status_code}): #{e.message}"
|
|
1370
|
+
end
|
|
1371
|
+
```
|
|
1372
|
+
|
|
1373
|
+
### Error Hierarchy
|
|
1374
|
+
|
|
1375
|
+
| Class | HTTP Status |
|
|
1376
|
+
|:------|:------------|
|
|
1377
|
+
| `TurboDocxSdk::AuthenticationError` | 401 |
|
|
1378
|
+
| `TurboDocxSdk::AuthorizationError` | 403 |
|
|
1379
|
+
| `TurboDocxSdk::ValidationError` | 400 |
|
|
1380
|
+
| `TurboDocxSdk::NotFoundError` | 404 |
|
|
1381
|
+
| `TurboDocxSdk::ConflictError` | 409 |
|
|
1382
|
+
| `TurboDocxSdk::RateLimitError` | 429 |
|
|
1383
|
+
| `TurboDocxSdk::NetworkError` | (no status) |
|
|
1384
|
+
| `TurboDocxSdk::TurboDocxError` | base class |
|
|
1385
|
+
|
|
1386
|
+
---
|
|
1387
|
+
|
|
1388
|
+
### Error Codes
|
|
1389
|
+
|
|
1390
|
+
`code` is **always populated** — an API-supplied code when there is one, otherwise the error
|
|
1391
|
+
class's default (`VALIDATION_ERROR`, `AUTHENTICATION_ERROR`, `AUTHORIZATION_ERROR`,
|
|
1392
|
+
`NOT_FOUND`, `CONFLICT`, `RATE_LIMIT_EXCEEDED`, `NETWORK_ERROR`). Branch on it without a null
|
|
1393
|
+
check.
|
|
1394
|
+
|
|
1395
|
+
The API also returns more specific codes, passed through unchanged:
|
|
1396
|
+
|
|
1397
|
+
| Code | Status | Meaning |
|
|
1398
|
+
|:-----|:-------|:--------|
|
|
1399
|
+
| `SenderEmailRequired` | 400 | No sender email resolvable. TurboSign: set `senderEmail` on the request. TurboQuote: configure one on the org quote template (Quote Settings). |
|
|
1400
|
+
| `SenderNameRequired` | 400 | No sender name resolvable — the API key has no usable name. |
|
|
1401
|
+
| `OptionalNotSupported` | 400 | A `signature` or `initial` field was sent with `required: false`. The signer must always complete those two types. |
|
|
1402
|
+
| `InvalidFieldRequired` | 400 | A field's `required` is not a boolean. Send `true`, `false`, or leave it out (leaving it out means required). |
|
|
1403
|
+
| `NoEditableFieldsForRecipient` | 400 | A recipient has no field they must fill in: all of their fields are read-only or optional. Give each recipient at least one required, editable field. |
|
|
1404
|
+
| `FieldsRequired` | 400 | A send has no fields and no recipient names a `role`. Pass fields, or send a template whose recipients name roles. A review link can be created without fields. |
|
|
1405
|
+
| `FieldPageOutOfRange` | 400 | A field is placed on a page past the end of the document. |
|
|
1406
|
+
| `UnknownSignerRole` | 400 | A recipient's `role` is not one of the template's roles. The message lists them. |
|
|
1407
|
+
| `DuplicateSignerRole` | 400 | More than one recipient was given for the same role. |
|
|
1408
|
+
| `SignerRoleUnfilled` | 400 | A role has no recipient and no signer saved on the template. |
|
|
1409
|
+
| `TemplateHasNoSignerRoles` | 400 | `role` was used on a template with no saved signature setup. |
|
|
1410
|
+
| `RoleRequiresTemplate` | 400 | `role` was used without a `templateId`. |
|
|
1411
|
+
| `TemplateRolesNeedPdfTemplate` | 400 | Roles can only be sent for a PDF signature template. For a Word template, generate a deliverable and send it with `deliverableId`. |
|
|
1412
|
+
| `DuplicateRoleEmail` | 400 | Two roles resolve to the same email address (a recipient you passed or a signer saved on the template), or a recipient without a `role` uses a role's email address. Each signer needs their own email address. |
|
|
1413
|
+
| `SignerHasNoFields` | 400 | On a role send, a signer has no field to sign: neither the template nor your `fields` assigns one to them. Raised when sending (`send_signature`, embedded signing), not for a review link, where fields can be placed in the preview. |
|
|
1414
|
+
| `InvalidRecipient` | 400 | An entry in `recipients` is not an object (for example `null` or a string). |
|
|
1415
|
+
| `SignatureSetupNotFound` | 404 | `get_template_signature_setup` was called for a template with no saved signature setup, or one that is not in your organization. Thrown as `TurboDocxSdk::NotFoundError`. |
|
|
1416
|
+
| `QuoteHasNoLineItems` | 400 | The quote has no line items. Add at least one before sending. |
|
|
1417
|
+
| `QuoteExpired` | 400 | The quote is past its `validUntil` date. |
|
|
1418
|
+
| `QuoteValidUntilRequired` | 400 | The quote has no `validUntil` date set. |
|
|
1419
|
+
| `QuoteNotSendable` | 400 | Only draft quotes can be sent. |
|
|
1420
|
+
| `QuoteContactRequired` | 400 | The quote's contact is missing a name or email. |
|
|
1421
|
+
| `QuoteCustomerInactive` | 400 | The quote's company or contact was deleted or deactivated. |
|
|
1422
|
+
|
|
1423
|
+
Error **messages** carry the actionable reason, not a generic envelope — multiple field errors
|
|
1424
|
+
are joined with `"; "`, e.g. `"name" is not allowed to be empty; "companyId" must be a valid GUID`.
|
|
1425
|
+
|
|
1426
|
+
## Requirements
|
|
1427
|
+
|
|
1428
|
+
- Ruby 2.7+
|
|
1429
|
+
- Zero runtime dependencies — the SDK uses only the Ruby standard library (`net/http`, `json`, `openssl`)
|
|
1430
|
+
|
|
1431
|
+
---
|
|
1432
|
+
|
|
1433
|
+
## Related Packages
|
|
1434
|
+
|
|
1435
|
+
| Package | Description |
|
|
1436
|
+
|:--------|:------------|
|
|
1437
|
+
| [@turbodocx/sdk (JavaScript)](../js-sdk) | JavaScript/TypeScript SDK |
|
|
1438
|
+
| [turbodocx-sdk (Python)](../py-sdk) | Python SDK |
|
|
1439
|
+
| [turbodocx (Go)](../go-sdk) | Go SDK |
|
|
1440
|
+
| [@turbodocx/n8n-nodes-turbodocx](https://www.npmjs.com/package/@turbodocx/n8n-nodes-turbodocx) | n8n community nodes |
|
|
1441
|
+
|
|
1442
|
+
---
|
|
1443
|
+
|
|
1444
|
+
## Support
|
|
1445
|
+
|
|
1446
|
+
- [Documentation](https://docs.turbodocx.com/docs)
|
|
1447
|
+
- [Discord](https://discord.gg/NYKwz4BcpX)
|
|
1448
|
+
- [GitHub Issues](https://github.com/TurboDocx/SDK/issues)
|
|
1449
|
+
|
|
1450
|
+
---
|
|
1451
|
+
|
|
1452
|
+
## License
|
|
1453
|
+
|
|
1454
|
+
MIT — see [LICENSE](./LICENSE)
|
|
1455
|
+
|
|
1456
|
+
---
|
|
1457
|
+
|
|
1458
|
+
<div align="center">
|
|
1459
|
+
|
|
1460
|
+
[](https://www.turbodocx.com)
|
|
1461
|
+
|
|
1462
|
+
</div>
|