I'm trying to create a Payment Item via the DocuSign API and I understand that to do so, I need to include a NumberTab and a FormulaTab. Our CRM, uses the AutoPlace functionality to place tabs on the document using the AnchorString property. A preview is shown so the user can check it before they send out the document and this all works fine.
However, when I create a new envelope, the tabs show up as a FormulaTab, not a payment item in the UI and then when I send the document, I can just complete the document without paying. The JSON I am sending across is as follows:
{"numberTabs":[{
"tabLabel":"Number Test",
"anchorString":"\\/Number 1\\/",
"anchorIgnoreIfNotPresent":"false",
"value":"1900.0",
"editable":"false",
"locked":"false",
"isPaymentAmount":"true"
}],
"formulaTabs":[{
"tabLabel":"Formula Test",
"formula":"([Number Test])",
"locked":"true",
"required":"true",
"hidden":"true",
"anchorString":"\\/PayNow\\/",
"anchorIgnoreIfNotPresent":"false",
"isPaymentAmount":"true",
"paymentDetails":{
"gatewayAccountId":"165be8b5-e212-43d4-b264-802d843f4182",
"currencyCode":"GBP",
"lineItems":[{
"amountReference":"1900.0",
"name":"AP-PACK-32 (2 days)",
"description":"32 Advisory Points",
"itemCode":346
}]
}
}]}
As I said when the document loads in DocuSign, the tab shows as a Formula tab, rather than displaying as a Payment Item so there must be something wrong with the above but I'm struggling to figure out what?
The last comment on this page: DocuSign Payments REST API create Tab gives an example, which is where I got the above from, but this doesn't work for me... Any ideas what I'm doing wrong?
EXTRA INFO
Since posting, I have now converted all amounts from strings to integers, just in case. I also tried setting the "isPaymentAmount" flag to true & false, and also leaving it out completely to no avail...
Ignore isPaymentAmount flag , it is obsolete , you can remove
it for both number and formula tab.
Formula property of Formula tab is the total amount that
needs to be charged in cents - update it to ([Number Test]) * 100
Only payment line items (Number tabs here are visible in the document) remove anchor properties for formula.
amount reference property in payment details is a reference tab label to the line item, update it to "Number Test" . This indicates that the number item is payment line item.
Related
In the api you can select multiple fields with something like this:
Text text = new Text();
text.setTabLabel("\\*_broker");
This will apply settings to all textfields that have names that end with "_broker".
But i want to select ALL text fields in the entire document and "\\*" does not seem to work.
Can anyone tell me how to select all fields from the API, or even better point me to the documentation for the setTabLabel matching format.
I've look all over and it seems alot of the old documentation links no longer work.
Thanks.
You can assign assign all transformed form fields to the first recipient by making them the default recipient (set defaultRecipient to true).
In order to make all of those form fields Collaborative, I believe you'll need to make extra API calls:
First, create the envelope as a draft (status = created instead of sent).
Then make a call to get the list of all the tabs (EnvelopeRecipients::List with include_tabs=true)
Finally, Use the tabLabels (or IDs) in an Envelopes::Update call to add the "shared": "true" parameter to each of them, and update the status to sent to actually send it.
I'm trying to populate the textTabs in one of the documents so that it has information prefilled into it using the call for EnvelopeTabs: update, however it keeps throwing me an error that it cannot find the tab that I am trying to test in the explorer. I have used the list call in the EnvelopeTabs to make sure that the information that I'm providing matches what is in the envelope and it is, here's an example of what I was seeing
enter image description here
enter image description here
When I make the call to update the tab in textTabs, I am doing it with the documentId, pageNumber, and tabLabel provided above and with the value set to what I want to be prefilled, however I keep getting an error that it cannot find the specified tab.
I have even tried filling it in with just the tabId and am still getting the same error.
In an effort to see if I was missing something, I also tried checking the linked reference documentation on the EnvelopeTabs: update page but it is 404ing (as were one or two other end points in the api explorer).
Any help would be appreciated as it seems like there is a piece of information that I'm missing to prefill tabs.
Are you creating the envelope via the API? If so, then the easy way to set a tab's value is to set the value parameter.
If you want to set a tab's value after the envelope is created, use the EnvelopeRecipientTabs: update method. (Note the resource name in your question was incorrect.)
When using this method, or any other DocuSign update method, remember that it is not a patch method: You must supply all of the parameters for the Envelope Recipient Tab that you're updating. If you don't already have all of the settings, then first do a get on the object, then update it.
I tried using below JSON call to update the Recipient tab and its updating the tab value:
PUT /restapi/v2/accounts/{accountId}/envelopes/{envelopeId}/recipients/{recipientId}/tabs
{
"textTabs": [
{
"value":"newVal",
"tabId": "cef562dd-e098-4dcd-935d-34ff8f5b5211"
}
]
}
Using the Docusign API, I am trying to change the fields that exist on a document. When I first create the document, I am able to change field values using "tabs." I get how to do that.
When I am trying to edit, or in Docusign's terms "correct," a document after it has been sent out, but before being signed, I am having trouble figuring out how to access those fields again to change the values.
I have tried using the API avenue described here ( PUT /v2/accounts/{accountId}/envelopes/{envelopeId}/documents/{documentId}/fields ), but even after successful calls, the values of the fields aren't changing, and I believe it is because I should be trying to access the tabs, as I did when first changing the tab values as I created the document, instead of targeting the fields, since the two seem to be different. Any thoughts? Thank you in advance for your answers.
To update Tab values you should use the putRecipientTabs api.
Once a signer completes the Signing process, the tab values cannot be updated.
Also not all Tab values can be updated. See this answer for more information.
The putEnvelopeDocumentFields api is for a different purpose. Document fields are different from Tabs. Document fields are an array of name-value custom data strings to be added to a document. Custom document field information is returned in the status, but otherwise is not used by DocuSign.
I figured it out.
The "fields" we are seeing on documents are "tabs," and they are children of the recipients.
The hierarchy goes envelope > recipients > tabs, which tabs we were trying to change. Not envelope > document > fields, which refers to something else--just familiarizing with the language of the api.
Here is a link to the reference for how to change "fields" aka "tabs", and that link includes sample requests.
One thing that helped me target my actual fields, since I kept on getting an error that the field didn't exist for the recipient, is to do a get request of all available tabs and use that response body as the request body for the update call (where we change the field values). Then you know the field information will be accurate, paring the body down to exactly the "fields" aka "tabs" you are interested in targeting.
We have defined a template that will be filled in and signed by our customers. In this template we have some fields that we pre-populate along with some documents that we will attach. The customer will fill in other fields and attach more documents. We are using the REST API to generate the sign request. We are able to generate the correct REST request to fill the tabs in the template, set the recipients and successfully send the signature request. All this works great. But now we're trying to get a document attached to the appropriate SignerAttachmentTab in the template and we cannot get REST to accept it.
We've tried using the Documents field but that doesn't work with templates it seems. We created a composite template and then defined a document for the document, server template for the template itself and an inline template to contain the tab data we want to populate. This keeps generating errors about the tab page number not being right. We've tried different values and we've looked over all the forum posts and documentation related to attaching documents to templates and none of them seem to work.
For the document we specify the file to upload, set the document ID and name. In the server template we specify the template ID. In the inline template we create a recipient, set their information, build up the envelope tabs with the data and then add a SignerAttachmentTab for the document. In this tab we set the document ID to match the document ID from the Document element. We set the tabLabel to the label used in the template itself. We've tried setting pagenumber but that doesn't change anything. All we want is for the document to be sent to the customer. When the open it they can double click the attachment field and view the document we're trying to send.
I'm trying to use the recipe explorer to get this to work using raw REST and it keeps failing with the TAB_PAGENUMBER_IS_NOT_IN_DOCUMENT error. It seems like the document is taking precedence over the template. Unfortunately I cannot change the order of the templates in the editor other than setting the sequence # on the server and inline templates. Here's the request that is generated using DocuSign's test system.
{
"compositeTemplates":[{
"document": {
"documentBase64":"<Base64BytesHere>",
"documentId":"2",
"name":"Test.pdf"
},
"inlineTemplates":[{
"recipients":{
"signers":[{
"email":"abc#def.org",
"name":"Person",
"recipientId":"1",
"roleName":"Sender 1",
"tabs":{
"signerAttachmentTabs":[{
"documentId":"2",
"tabLabel":"MyAttachment"
}],
"textTabs":[{
"tabLabel":"someText",
"value":"Value1" }
]}
}]},
"sequence":"2"
}],
"serverTemplates":[{
"sequence":"1",
"templateId":"guid}]
}],
"emailBlurb":"A message",
"emailSubject":"Test",
"status":"sent"
}
I've looked at the existing posts in the forums and either they don't work for my case or they aren't trying to actually attach the documents to the template but simply include them as a document in addition to the template.
Update
Re:
...associate [a] document to the tab so that the signer will be able to click the attachment field in the document and see the document
Yes, you can now do this by using Smart Sections with a documentHtmlDisplaySettings object in the Envelopes:create request. The collapsed (or collapsible) section can be displayed in different ways:
inline
collapsible
collapsed
continue_button
responsive_table
responsive_table_single_column
print_only
Live examples that you can try online
HTML source document
Word source document
Original answer
Re:
But now we're trying to get a document attached to the appropriate SignerAttachmentTab in the template and we cannot get REST to accept it.
You're trying to use the API to add a document to a SignerAttachmentTab?
This is not supported. Only signers themselves add documents to a SignerAttachmentTab. The API can't do it for them.
Is the issue that you want to make sure that a signer attaches (uploads) a document to the envelope as part of the signing ceremony? You can make the tab non-optional (required). But that won't check the contents of the attached file.
You could use a web hook / Connect to check the file(s) that were attached and, if the right files weren't attached, generate another enveloper for the signer.
I figured out what I was doing wrong. For a template without attachments I was using TemplateRole and EnvelopeTabs. But for attachments, trying to include any document would cause the document to override the template. So I switched to composite template with server and inline templates for the template and data. Trying to add documents in various combinations in the various areas where they are allowed generally caused the request to be sent but with no documents.
The final solution was to go back to the original TemplateRole approach but to create the envelope as a draft. After the draft envelope was created I could then add the document to the envelope. But unfortunately to send the envelope you then have to reattach the recipients. I'm looking to clean that up but otherwise it is working for me now.
I am using SOAP API to add hyperlink tabs on a document. The second recipient/signer is getting a duplicate link placed on top of the existing link. See attached screenshot.
No issues for the first signer though.
I have also noticed that though the signer can see the active link, the signed & completed document displays an inactive link when added as a Tab through the API.
Is there a possibility that I can embed a link within PDF and Docusign can activate this link while signing?
Thanks in advance.
I'm not sure what you mean by "...getting a duplicate link placed on top of the existing link" -- but if you're seeing tabs in unexpected places within the envlope, a good first step in troubleshooting might be to execute a "Request Envelope" operation for the envelope, and compare Tab information in the response with the Tab information you specified in your Create Envelope operation.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.docusign.net/API/3.0">
<soapenv:Header/>
<soapenv:Body>
<ns:RequestEnvelope>
<ns:EnvelopeID>ENVELOPE_ID</ns:EnvelopeID>
<ns:IncludeDocumentBytes>false</ns:IncludeDocumentBytes>
</ns:RequestEnvelope>
</soapenv:Body>
</soapenv:Envelope>
Regarding your statement that "the signed & completed document displays an inactive link when added as a Tab through the API" -- this DocuSign Community forum post (http://community.docusign.com/t5/Templates-and-Powerforms/Hyperlink-in-contract/td-p/25837) describes the expected behavior of the hyperlink for completed envelopes: "When the envelope is completed, the hyperlink will no longer be active from the member console but will be active from the Completed PDF. However, it will appear as static text.".
AFAIK, it's not possible for you to embed a link within a PDF and force DocuSign to 'activate' the link during the signing session.
-- UPDATE #1 --
Thank you for posting the "Request Envelope" response. Interestingly, that response shows that the Envelope only contains a single 'HREF' tag -- assigned to the first recipient, but shared amongst all recipients:
I've attempted to reproduce the issue that you describe, but without success. i.e., I created/sent an envelope with two recipients, and included a single 'HREF' (text) tab assigned to the first recipient (but shared). When the first signer signs, he sees the link just fine:
And when the second signer signs, the link appears exactly the same for her as it did for the first signer:
In your scenario, does the text string "TERMS & CONDITIONS" appear as text in the PDF itself -- and then perhaps you're trying to (exactly) overlay that text with a DocuSign (HREF) text tab? If so, then perhaps that's what's causing your issue -- i.e., the overlay position isn't quite precise enough -- so the signer is seeing the "TERMS & CONDITIONS" text in the document itself, overlayed by the (slightly offset) Hyperlink that you've added using a DocuSign tab.