Currently, I am having a schedule job which get all uncompleted envelope status from my system and check each envelope status update from docusign via docusign sdk (Envelope env = envelopesApi.getEnvelope(accountId, envelopeId)). The reason to use that api is there are different use cases for each envelope status.
But I see that polling api (EnvelopesInformation envelopes = envelopesApi.ListStatusChanges(accountId, options)) has limitation that not allowed to poll DocuSign more than once every 15 minutes. I don't use this api now.
So is there any problems/limitation for envelopesApi.getEnvelope(accountId, envelopeId))?
Thanks.
The getEnvelope() and the listStatusChanges() requests both have the same polling limitation in place, if you start calling either too much your API key might get throttled or temporarily disabled by DocuSign.
However, since the listStatusChanges() request returns status on a whole set of envelopes instead of just one envelope at a time this is the preferred API request when polling the DocuSign platform.
Furthermore, the truly optimal option which doesn't count at all against the platform limits is using DocuSign webhooks to push status out to your app instead of your app constantly polling. You can configure webhooks either through the DocuSign Connect module or by using eventNofications through the envelope structure.
Learn more about DocuSign Webhooks.
Related
In my returnUrl handler, I am using list documents.
In the returned array, how can I figure out if the document has been signed or not?
Thanks!
Your return url handler will be called with a query parameter event as discussed in Inbar's answer.
But you should not use the query parameter for making business decisions since a bad guy could easily call your return url and simply tack on an event=signing_complete query parameter--spoofing your application.
Instead, when your application needs to know if the envelope has been signed or not, it has two categories of options:
Ask DocuSign
Your app can call the Envelopes::get method to determine the current status of the envelope. Other API methods can also be used for this functionality.
Design your app such that you do not call DocuSign about a particular envelope more often than once every 15 minutes since such behavior is considered polling and is not allowed.
Webhook: DocuSign will call your app
You can set up a webhook with DocuSign so that the eSignature platform will call your application when the envelope is complete (signed by all the signers, etc).
Use the DocuSign webhook HMAC feature to guarantee that the notification message came from DocuSign (was not spoofed) and that it was not altered in transmission.
By using AWS or equivalent, you can easily receive the notification messages behind the firewall, with no firewall changes. And AWS will not charge you for the first million notification messages per month. See the connect-* repos on github.com/docusign
Dashboards
If your app wants to present a dashboard to a business decision maker about the status of your envelopes, then relying on the event query parameter is fine. But before your app does anything that costs real money, eg initiate goods or services to be provided to a customer, make sure that the envelope has been signed by using one of the two techniques above.
The URL you get back from DocuSign has an event parameter and looks like this:
http://www.acme.com?event=signing_complete
signing_complete means it was signed.
https://developers.docusign.com/esign-rest-api/guides/features/embedding has the full list of other events in the "Determining Recipient Action" section of the article.
I'm using the DocuSign Envelopes: listStatusChanges API to poll DocuSign for updates to envelopes. I'm currently testing this out in the Sandbox environment. The docs say that "you are not allowed to poll DocuSign more than once every 15 minutes" but I've been testing this every 2-3 minutes and not encountering any issues here.
Does anyone know if this 15 minute limit does not apply to the Sandbox environment? I don't have a production version to test against at the moment.
The polling limit does apply to the sandbox accounts but DocuSign is more lenient about the limits in the sandbox platform since it is for development.
Your application will not pass the GoLive testing if it polls more than once per 15 minutes. See Polling Violations on this page.
If your application's polling behavior changes after it is on the production platforms then our automatic monitoring will notify DocuSign staff about your app's violation. The staff will then determine the next step. In the future, actions such as suspending your integration key (client id) may be taken automatically.
Recommended Don't poll. Instead, use the DocuSign Connect webhook feature. If you send your envelopes via the API, then the webhook feature is included with all pricing plans. See the eventNotification attribute of the Envelopes::create call.
How to configure DocuSign API to send only notifications that pertain to the document not being viewed within 32 hours in my email/inbox?
Aside from 'This envelope is expiring soon', there are not built-in notifications that relate to inactivity on an envelope. You would have to build a custom solution that monitors envelope status via DocuSign Connect, and then delivers notifications as desired.
Is it possible to request from the API to resend a webhook?
From here i can see this is possible from the Admin Panel
https://www.docusign.com/blog/dsdev-adding-webhooks-application/
When a webhook request fails, the Failures screen also enables you to
resend the notification. This can be very helpful when debugging your
listener software.
I want to do the same but from the API.
Thanks!
You can use the ConnectEvents Api's.
Specifically the following api's
retryForEnvelope
Republishes Connect information for the specified envelope.
retryForEnvelopes
Republishes Connect information for the specified set of envelopes. The primary use is to republish Connect post failures by including envelope IDs for the envelopes that failed to post in the request. The list of envelope IDs that failed to post correctly can be retrieved by calling to [ML:GetConnectLog] retrieve the failure log.
Once any document is sent for signature, we can see that document status like in process, completed. Also email notification is coming to document sender mail. Are these features exposed by docusign rest API?
Yes, absolutely. The status updates are delivered to your program via a "webhook" -- you register a url with DocuSign and then DocuSign calls your app when a change occurs.
You can create a webhook subscription at the account level or for individual envelopes.
See the docs. Recipes are also available at the DocuSign Developer Center.
Added
You can also determine the current status of your signing requests (your envelopes) by polling the DocuSign platform. However, this is actively discouraged, and in any case, you can't poll more than once per 15 minutes for a given envelope. The docs discuss this as well.