Browse files

added the best practices

  • Loading branch information...
1 parent e4d47c7 commit 2990d9542ee9002ff8793de09853d40350321271 @mikebz mikebz committed Sep 27, 2012
Showing with 115 additions and 0 deletions.
  1. +115 −0 docusign_api_best_practices.txt
View
115 docusign_api_best_practices.txt
@@ -0,0 +1,115 @@
+DocuSign
+Information Guide
+
+API Best Practices Information
+
+This guide provides information about the best practices to use when making calls to the DocuSign SOAP and REST APIs.
+
+SOAP and REST API Best Practices
+
+To maintain reliability and stability within our demo and production environments, DocuSign operates with certain API call efficiency guidelines. To ensure effective load balance we continually monitor the API calls to our backend systems and we will contact developers that are putting unnecessary burden on the system.
+
+DocuSign has imposed a default 1,000 API call per hour limit for each account. This limit ensures resource availability for all account holders, while reducing the chances of a denial of service (DOS) attack. Exceeding this limit will result in your API calls receiving an exception for up to 60 minutes.
+
+However, the call limit is the default setting and not a service limitation. When evaluating your integration, if you feel the API call per hour limit will restrict your application�s usage based on anticipated volumes, please contact DocuSign to discuss further options.
+
+Additionally, your API certification review involves verifying that you do not exceed 1 status request per unique envelope per 15 minutes for polling compliance for the following methods:
+
+SOAP API: RequestStatus, RequestStatusEx, RequestStatuses, RequestStatusesEx, RequestPDF and RequestDocumentPDFs.
+
+REST API: GET /accounts/{accountId}/envelopes
+
+Failure to do so will result in a delay in your API certification approval for the Production environment and your application might be subject to revocation.
+
+To ensure your integration does not reach the API call limits, follow these best practices:
+
+1. Use DocuSign Connect for publishing near real-time envelope status to your web service listener.
+The DocuSign Connect Service Guide is included at the end of this document.
+
+2. When unable to use DocuSign Connect and you need to poll DocuSign for envelope status updates, use these guidelines:
+
+SOAP Requests:
+
+� Limit RequestStatus, RequestStatusEx, RequestStatuses, RequestStatusesEx, RequestPDF, RequestDocumentPDFs to 1 status request per unique envelope per 15 minutes.
+
+� Use RequestStatuses and RequestStatusesEx method calls on a changed status only.
+
+� Use RequestStatusCodes and RequestStatusChanges instead of RequestStatus (Ex) and RequestStatuses (Ex) in your poll loop. These two methods are useful in determining which envelopes have actually changed, match your criteria, and can be safely used in a reasonable polling loop cycle because they are lightweight. They return the matching envelope IDs rather than the whole envelope status structure.
+
+� Use RequestStatusChanges, which returns a list of envelopes that have changed since the last request and RequestStatusesEx to retrieve those envelopes.
+
+� When retrieving terminal state envelopes (declined and voided), the best method is to retrieve the certificate information only.
+
+� When retrieving terminal state envelopes (completed), one RequestPDF or RequestDocumentPDFs call should be made.
+
+REST Requests:
+� For GET /accounts/{accountId}/envelopes requests, use the optional query strings to limit request checks to shorter date ranges and specific envelope statuses.
+
+3. Your system should have the ability to capture outgoing request messages and the related response messages whether using SOAP or REST. This ability need not be active all the time, but should be easily activated when needed for troubleshooting.
+
+Again, applications are not allowed to poll for envelope status more than once every 15 minutes and DocuSign discourages integrators from continuously retrieving status on envelopes that are in a terminal state (Completed, Declined, and Voided). Excessive polling will result in your API access being revoked. If you need immediate notification of envelope events, DocuSign encourages you to review envelope events or use our Connect Publisher technology, DocuSign Connect.
+
+In addition, if you have an IPS or deep packet inspection in your network, please add the following common knowledge IP addresses:
+
+NA1
+www.docusign.net 209.67.98.12
+mailsea.docusign.net 209.67.98.59
+
+NA2
+na2.docusign.net 206.25.247.140
+mailch.docusign.net 206.25.247.155
+
+EU1
+eu1.docusign.net 206.25.247.144
+mailch.docusign.net 206.25.247.155
+
+DAL/DR
+demo.docusign.net 209.46.117.172
+preview.docusign.net 209.46.117.174
+mailda.docusign.net 209.46.117.17
+
+Please consult our online SOAP or REST API Developer�s Guide for code snippets and detailed explanations: http://www.docusign.com/developer-center
+
+Post-Certification Information
+
+After your API integration is certified, you need to take several actions to complete the move to the DocuSign Production environment.
+
+SOAP API Post-Certification
+You will need to perform these actions to ensure that your solution will function in the Production environment.
+
+1. Repoint your web services.
+
+Web Service
+Account Management from https://demo.docusign.net/api/3.0/api.asmx to https://www.docusign.net/api/3.0/api.asmx
+Credential from https://demo.docusign.net/credential.asmx to https://www.docusign.net/credential.asmx
+Service from https://demo.docusign.net/api/3.0/dsapi.asmx to https://www.docusign.net/api/3.0/dsapi.asmx
+2. Update both the API Account Number and API User ID to the production values.
+
+3. Typically, you do not need to change your Integrator Key.
+
+4. If you use the resource files or templates in the Demo Environment, transition those files them to your Production Environment.
+
+5. For templates, the Template ID will change from the Demo environment to your Production environment. Adjust your code accordingly.
+
+6. Conduct post-certification testing 3 business days prior to your go-live date to verify functionality.
+Envelopes used for Production testing will be credited back to your account upon verification.
+
+REST API Post-Certification
+You will need to perform these actions to ensure that your solution will function in the Production environment.
+
+1. Repoint your web services.
+
+Web Service
+Get Account Info from http://{server}/restapi/{apiVersion}/accounts/{accountId} to http://{server}/restapi/{apiVersion}/accounts/{accountId}
+BaseURL from http://{server}/restapi/{apiversion}/login_information to http://{server}/restapi/{apiversion}/login_information
+Service from https://test.docusign.net/restapi/service_information to https://www.docusign.net/restapi/service_information
+
+2. Update both the API Account Number and API User ID to the production values.
+
+3. Typically, you do not need to change your Integrator Key.
+
+4. If you use the resource files or templates in the Demo environment, please transition them to your Production environment.
+
+5. For templates, the Template ID will change from the Demo environment to your Production environment so adjust your code accordingly.
+
+6. Conduct post-certification testing 3 business days prior to your go-live date to verify functionality. Envelopes used for Production testing will be credited back to your account upon verification.

0 comments on commit 2990d95

Please sign in to comment.