Tips & Tricks: Integration Resources
What Does a Developer Have to Do To Complete an Integration?
-
Prepare the website / platform to take in data from the user (names, emails, documents, etc) that will be fed into SIGNiX via XML. This could take the form of a new dialog, forms, buttons, etc. SIGNiX can't build this for you, but can provide some recommendations.
-
Tag all of the PDFs that need signatures with Acroform / PDF signature fields and be sure to give all those fields unique names. That means ALL signature, initial, text, checkbox, radio button and date(text) fields!! Alternatively, you may need to explore embedding the SIGNiX Wizard interface.
-
Create XML and set up your platform to make B2B calls to SIGNiX
-
Map values from your platform / website as well as the PDF to the values in the XML.
-
Tweak workflows, add features, experiment with (and request) customizations and client preference settings from SIGNiX
-
Your platform must generate at least 5-15 end-to-end tests once your integration has been completed before a Go-Live Review will be scheduled with SIGNiX
-
Demo completed integration to clients' business team(s) and SIGNiX for sign-off by both.
-
FIx any issues the business team didn't like.
-
Prepare for production - You may require the client to do a production release of their own product, which in turn may need to coincide with a SIGNiX production release, depending on customizations
-
Clear IP addresses and provide push notification URLs
Prerequisite Knowledge for Using the SIGNIX FlexAPI
-
Knowledge of Web Services API usage and XML format / structure
-
Base64 encoding/decoding
-
Concepts of PDF (ISO32000-1) structure/format as well as AcroForm-based PDF form fields
-
Knowledge of secure integration principles
Prerequisites for Using SIGNiX Push Notifications
-
All prerequisites for FlexAPI
-
A web page (URL) that SIGNiX push notifications can be sent to
-
Server that can respond to / acknowledge push notifications in a timely fashion
Test Environment Parameters and Requirements
Note that failure to adhere to the following parameters and requirements may result in your test account being suspended until the offending transactions are removed / cancelled.
- All email addresses used while operating in the SIGNiX test environment must resolve to real email addresses. Email addresses such as test@test.com, for example, will be flagged.
- SubmitterName should be the name of the individual generating the transaction. SubmitterEmail must also be a real email, as described in bullet above.
- Authentication methods (ServiceType) should be carefully chosen based on consultation with SIGNiX and guidance from SIGNiX documentation. Typically, the only acceptable authentication methods are SelectOneClick, SMSOneClick or KBAOneClick. If your use case requires something different, please consult with your SIGNiX integration specialist first.
- If you are using SelectOneClick or SMSOneClick, you should be using dummy SSN data in the format, "910000000" and for date of birth, "00/00/0000". If your chosen authentication method does require the delivery of a signer's SSN, in our test environment, please create a 'fake' SSN starting with 3 zeroes and the remaining 6 digits as random numbers (do not use 000123456 but more like 000194782). Do NOT use actual SSN data.
Archive / Storage Policy
-
SIGNiX does not store your transactions/completed PDFs/Audit Trails indefinitely
-
We do have an archive policy and those PDFs will no longer be readily available to your users after a 90-day period
-
Integrators are expected to download and store completed PDFs within their system. In addition, audit trails (evidence of the transactional events, known in some cases as a 'certificate') should also be downloaded as a PDF to make it human-readable.
-
In the event that Integrator did not store their PDFs and a user requests a copy of their signed documents, SIGNiX can provide Unarchive Professional Services at our standard hourly rate
-
Dependent on your compliance/storage regulations, you may request to be placed on a custom deletion schedule (only after you’ve confirmed receipts, will we purge our system of your data)
-
If Integration cannot store, SIGNiX does offer Storage Services for a fee
Tips & Other Requirements
-
Use the Test Harness to try out different configuration and parameter changes prior to coding to understand implications.
-
Come to the development table with a basic idea of the flow you are trying to accomplish with e-signatures. For example, a series of wireframe or concept images would be a great start.
-
Be sure to test early and often to head off integration issues late in the game.
-
Set your authentication and client preference choices early in the integration process to be sure your integration goes smoothly and relying parties are able to experience the integration as it will run in production.
-
Be sure to model use cases during integration and testing that are very similar if not identical to production use cases to ensure the best results.
-
PDF signature fields should not be set to 'hidden.' Doing so will make the resulting signature not appear (thus hidden) on the final PDF.
-
Documents are not stored by our system for use during a SubmitDocument call. PDFs either have to be Base64 encoded and included in the XML submission for a SubmitDocument, or a URL needs to be provided that SIGNiX can retrieve a PDF from.
-
PDF documents submitted to us must already include PDF fields that can then be referenced in the SubmitDocument call.
-
If your platform allows a user to 'delete' transactions, those transactions must be completed and downloaded, or cancelled if in process. Other scenarios should be discussed with SIGNiX for best practices.
-
Push notification response URLs must be secured via HTTPS.
Common Questions & Answers
Q: Do documents need to be PDFs before they are sent to SIGNiX?
A: Yes.
Q: Do fields need to be present on the PDF before submitting to SIGNiX?
A: Yes, at this point, unless you plan on embedding the SIGNiX UI to have users drag and drop fields (tasks) onto the document.
Q: What security is used to communicate with the SIGNiX API?
A: Calls to the SIGNiX API are sent via 256-bit TLS1.2 and also require the delivery of specific API credentials. Custom SSL certificates can also be used for certain API calls and responses. Please contact SIGNiX for more info.
Q: Do signers need to register for an account with SIGNiX before signing?
A: No.
Q: Does an integrator need to provide SSN info for a signer?
A: No. It is ONLY required when higher-end authentication (i.e. knowledge-based authentication) is used, which is generally rare. Pseudo / dummy SSN info must be used otherwise and is detailed in the API documentation.
Q: How does my system get notifications from SIGNiX?
A: SIGNiX has many ways to deliver notifications to a submitting system. Emails can be sent to a 'submitter,' and real-time push notifications can be delivered to an endpoint provided by the submitting system.
Q: Do I need to use push notifications?
A: In order to get the most real-time information, SIGNiX strongly recommends the use of push notifications as we let you know when events happen rather than your system having to poll ours on a regular basis, waiting for information. We do have some alternatives to push where some transaction details can be retrieved individually, and your SIGNiX representative can provide more details.
Q: What formats are files returned in?
A: Completed, signed documents are returned as digitally signed PDF documents. The audit trail can be returned as a PDF or XML file or both.
Q: Can data that a user enters in fields during signing be returned to a submitting system?
A: Yes, that data will be resident on the PDF, of course, and the DownloadDocument call can also be modified to request that SIGNiX return any changes to fields alongside the final PDF.
Q: Why does the signed PDF coming back from your test system have an invalid or 'signature with problems'?
A: The digital certificate used to sign documents in the production environment is part of the Adobe Approved Trust List (AATL) and is automatically trusted by Adobe Reader. However, the certificate in the test environment is not the same certificate, and thus it is not automatically trusted when opened in these tools. To set the trust and produce a green checkmark, right click on the signature. Choose Show Signature Properties, then Show Signer's Certificate. Click on the Trust tab and then click the Add to Trusted Certificates button. Then, simply click Yes to accept the trust. Close and open the document - the signature should now come up as a green checkmark and be trusted!