diff --git a/_posts/2015-11-26-howto-create-a-multidocument-transaction.markdown b/_posts/2015-11-26-howto-create-a-multidocument-transaction.markdown index cb7adbf..c7cf4e1 100644 --- a/_posts/2015-11-26-howto-create-a-multidocument-transaction.markdown +++ b/_posts/2015-11-26-howto-create-a-multidocument-transaction.markdown @@ -5,6 +5,7 @@ date: 2015-11-26 00:00:00 +0000 categories: api howto tags: - multidoc +product: Signhost --- ## How-to start a multi document transaction diff --git a/_posts/2015-12-07-update-timezone-information-on-data-retrieval.markdown b/_posts/2015-12-07-update-timezone-information-on-data-retrieval.markdown index 222800f..7f6c152 100644 --- a/_posts/2015-12-07-update-timezone-information-on-data-retrieval.markdown +++ b/_posts/2015-12-07-update-timezone-information-on-data-retrieval.markdown @@ -3,6 +3,7 @@ layout: post title: "Updated timezone information on data retrieval" date: 2015-12-07 00:00:00 +0000 categories: api changes +product: Signhost --- ## Losing timezone information diff --git a/_posts/2016-04-21-howto-create-a-transaction-with-fillable-pdf-fields.markdown b/_posts/2016-04-21-howto-create-a-transaction-with-fillable-pdf-fields.markdown index 7f26672..293fa7c 100644 --- a/_posts/2016-04-21-howto-create-a-transaction-with-fillable-pdf-fields.markdown +++ b/_posts/2016-04-21-howto-create-a-transaction-with-fillable-pdf-fields.markdown @@ -5,6 +5,7 @@ date: 2016-04-21 00:00:00 +0000 categories: api howto tags: - formfields +product: Signhost --- ## How-to create a transaction with fillable form fields diff --git a/_posts/2016-10-06-api-generated-fields.markdown b/_posts/2016-10-06-api-generated-fields.markdown index e7e3613..a40aeb1 100644 --- a/_posts/2016-10-06-api-generated-fields.markdown +++ b/_posts/2016-10-06-api-generated-fields.markdown @@ -5,6 +5,7 @@ date: 2016-10-06 00:00:00 +0000 categories: api howto tags: - formfields +product: Signhost --- ## How-to create a transaction with api generated fields diff --git a/_sass/_layout.scss b/_sass/_layout.scss index 0606ce7..2c8410b 100644 --- a/_sass/_layout.scss +++ b/_sass/_layout.scss @@ -10,6 +10,23 @@ position: relative; } +.site-select { + float: left; + font-size: 16px; + font-weight: 300; + line-height: 56px; + letter-spacing: -1px; + margin: 0.5rem; + padding: 0.5rem; + box-sizing: border-box; + width: 100%; + height: calc(1.5rem + 1rem); + max-width: 10em; + display: block; + border: 1px solid #478A9D; + border-radius: 2px; +} + .site-title { font-size: 26px; font-weight: 300; diff --git a/about.md b/about.md index ad697cb..e05c21b 100644 --- a/about.md +++ b/about.md @@ -2,6 +2,7 @@ layout: page title: About permalink: /about/ +product: Evidos --- [Signhost.com](https://www.signhost.com) is a service that makes it possible to digitally sign, seal or deliver your documents. Documents can be signed directly from your webportal or by sending a signing request by email or other message to the end-user. @@ -16,7 +17,7 @@ This document describes the Signhost REST API implementation. The REST API is the underlying interface for all of our official Signhost API methods. It's the most direct way to access the API. This reference document is designed for those interested in developing for solutions using the SignHost.com REST API Signing feature or for those interested in exploring Ondertekenen.nl integration features in detail. -Further details about the methods can be found [here](/). +Further details about the methods can be found [here](/signhost/endpoints). # Questions Please contact us if you have any questions regarding our API or making it even better. Drop us an e-mail at [support@signhost.com](mailto:support@signhost.com) or call us on +31237370046. diff --git a/forms/configuration.md b/forms/configuration.md new file mode 100644 index 0000000..08d5a51 --- /dev/null +++ b/forms/configuration.md @@ -0,0 +1,78 @@ +--- +layout: page +title: Configuration of the form to Evidos Signhost +permalink: forms/configuration/ +product: Forms +--- + +Evidos forms has a native integration with [Evidos Signhost](/signhost) the signing API of Evidos. +After the user filled all the information the signing transaction including the PDF(s) to be signed are created. + +## Mapping formfields to sign API + +The creation of the PDF is based on a template. +Within the project, the PDF template is mapped to the formfields. + +The formfield are included in the postback/GET using the Context property, a valid json object containing the name and input of the formfield. +This also includes hidden fields for additional background validations. + +See Evidos Signhost get for an example of the result. In the json the Context property could look like: +```json +"Context": { + "Name": { + "Firstname": "John", + "Lastname": "Doe", + } +``` + +## Defining the signing flow – Number of Signers +At the end of the form it is possible to let the user define if he will be the authoritative signer and directly view and sign the document(s), or define the authoritative signer(s) by typing the name/ email. +The customer needs to know or decide if the end user is allowed to sign directly and/or delegate to other signers. +If other signers are defined the signing URL will be sent by email to the other signers or the enduser is able to distribute the signing link himself. + +## Sign Parameters +It is also required to define the additional parameters for Evidos Signhost. +During the project, these parameters will be defined with the customer. +A detailed overview of the parameters can be viewed in the Evidos Signhost API: [https://evidos.github.io/signhost/endpoints/##/definitions/Transaction](/signhost/endpoints/##/definitions/Transaction) + +## Verificationmethods +It is important to decide on what level the enduser will identify during the signing process, for example SMS, Scribble, eID. Multiple verification methods are supported. +Methods are described here: [https://evidos.github.io/signhost/endpoints/##/definitions/Verification](/signhost/endpoints/##/definitions/Verification) + +## Postback URL +When the customer system will use the Signhost API to retrieve the document(s) and receipt a postback must be configured. +For details on the postback mechanism see: [https://evidos.github.io/signhost/postback/](/signhost/postback) + +## Return URL +At the end of the signing, the signers are sent to a return URL. +This can be a result page of the customer or a result page on Evidos forms. +Within the Evidos forms, it is possible to additionally start a payment process or any other trigger. + +## Retrieving the result Postback/ Get +For the webform a specific postback URL is configured. +This postback URL can be an endpoint at the customer system. +The customer system is able to retrieve the filled form data from the postback. +The formfield are included in the postback using the Context property, a valid json object containing the name and input of the formfield. +This also includes hidden fields for additional background validations. + +Based on the postback the customer system is also informed on the transaction and signer activities like; how many signers signed, clicked or looked at the transaction. +See status in our signing api: [https://evidos.github.io/signhost/status-activity/](/signhost/status-activity) + +Based on the postback the customer system can do a GET to retrieve the signed documents and transaction receipt. + +Signed document(s): +[https://evidos.github.io/signhost/endpoints/##/paths//api/transaction/{transactionId}/file/{fileId}//get](/signhost/endpoints/##/paths//api/transaction/{transactionId}/file/{fileId}//get) + +Transaction Receipt: +[https://evidos.github.io/signhost/endpoints/##/paths//api/file/receipt/{transactionId}/get](/signhost/endpoints/##/paths//api/file/receipt/{transactionId}/get) + +**Note:** If no postback can be implemented it is possible to configure Evidos Forms to send the result by email or other secure distribution mechanisms. + +## Delete a transaction +Within Evidos Signhost a time is defined for the sign URL’s to be available. +Optionally the customer system can send a delete after successfully retrieving the signed documents and transaction receipt. +This delete will directly remove the customer data from the Evidos Signhost system. + +## Transaction dashboard +Based on the postback integration the customer system is able to integrate a status dashboard of the signing transactions linked with the form webanalytics. +If this is not available or implemented the Evidos Portal can be used to view the signing transaction dashboard. ([https://portal.signhost.com](https://portal.signhost.com)) \ No newline at end of file diff --git a/forms/design.md b/forms/design.md new file mode 100644 index 0000000..a952b7d --- /dev/null +++ b/forms/design.md @@ -0,0 +1,46 @@ +--- +layout: page +title: Designing the webform +permalink: forms/design/ +product: Forms +--- + +Evidos will define the webform and fields together with the customer. +During the design the different steps in the form can be defined. +Also specific form validations, required/non required fields are defined. +The webforms are responsive and mobile friendly. + +## Branding + +The form can be branded in the style and look and feel of the customer. +There are two ways to present the webform: +1. By including a javascript library and a javascript include in the website of the customer. +2. A dedicated form on Evidos Forms, optionally with a custom website domain (for example: ```https://mydomain.com/form``` ) + +To include a form you have to do the following: +1. If not included yet include JQuery library and JQuery UI with widgets functionality. (Recommended jQuery version is > 1.10.2.2) +2. Include our Forms library: +```html + +``` +3. Initialize the form +```javascript +jQuery(function() { + FormsEngine.initForm({ + id: "", + containerId: "
", + publisherUri: "https://formsengine.signhost.com/publisher", + }); +}); +``` + +## Data validation +The following data field validation and enrichment is possible to include; + +Identity check; within the form the user presents eID like iDIN or passport/selfie check; + +Data enrichment; Additional data is prefilled using registers like address, chamber of commerce; + +Registry check; Additional checks in a register like creditworthiness, Politically Exposed Person (PEP); + +Data validation; Checking value entry, like IBAN check, phone check. diff --git a/forms/images/sequence_diagram.svg b/forms/images/sequence_diagram.svg new file mode 100644 index 0000000..0b515b7 --- /dev/null +++ b/forms/images/sequence_diagram.svg @@ -0,0 +1,21 @@ +Customer System -> Enduser: Create formlink +Note left of Enduser: Form link has a UID/token as queryparameter +Enduser -> Evidos Forms: Click on formlink +Evidos Forms -> Enduser: Request authentication to show prefilled form (Optional) +Evidos Forms -> Customer System: Validate authentication (optional) +Evidos Forms -> Customer System: Retrieve prefilled data by UID/token Rest API +Note right of Customer System: This authentication / Data REST API\n is provided by te Customer System +Customer System -> Evidos Forms: Return prefilled data +Evidos Forms -> Enduser: Show prefilled form +Enduser -> Enduser: Fill in form data +Evidos Forms -> Evidos Forms: Validate data +Enduser -> Evidos Forms: Submit form +Evidos Forms -> Evidos Signhost: Forward data to Sighost Signing Platform API +Evidos Signhost -> Enduser: Show sign URL with document(s) +Enduser -> Evidos Signhost: Sign document(s) +Evidos Signhost -> Enduser: Redirect enduser to returnURL +Evidos Signhost -> Customer System: Email Signing confirmarion (Optional) +Evidos Signhost -> Enduser: Email Signing Confirmation (Optional) +Evidos Signhost -> Customer System: Send Postback status (Optional) +Customer System -> Evidos Signhost: Get signed docment and receipt (Optional) +Customer System -> Evidos Signhost: Delete transaction (Optional)Customer SystemCustomer SystemEnduserEnduserEvidos FormsEvidos FormsEvidos SignhostEvidos SignhostCreate formlinkForm link has a UID/token as queryparameterClick on formlinkRequest authentication to show prefilled form (Optional)Validate authentication (optional)Retrieve prefilled data by UID/token Rest APIThis authentication / Data REST APIis provided by te Customer SystemReturn prefilled dataShow prefilled formFill in form dataValidate dataSubmit formForward data to Sighost Signing Platform APIShow sign URL with document(s)Sign document(s)Redirect enduser to returnURLEmail Signing confirmarion (Optional)Email Signing Confirmation (Optional)Send Postback status (Optional)Get signed docment and receipt (Optional)Delete transaction (Optional) \ No newline at end of file diff --git a/forms/index.md b/forms/index.md new file mode 100644 index 0000000..3c6aa3a --- /dev/null +++ b/forms/index.md @@ -0,0 +1,45 @@ +--- +layout: page +title: Basic Information +permalink: forms/ +product: Forms +--- + +Evidos makes it possible to provide webforms to your customers to fill and sign transactions in one integrated flow. +In this way, you have a flexible solution to collect data in a smart way and generate the documents to be signed based on a template. +In general, it is not possible to fill any smart formfields during the Evidos Signhost signing process, Evidos Forms is a specialized module to offer this functionality. + +It is also possible to offer a prefilled form based on the data that you already have available in your own customer system. +This makes it possible that the enduser is not required to fill all data all over again. + +The following technical documentation describes the way how you can integrate your application with Evidos Forms. + +## Before you start +All connections are done using JSON Rest webservices over an https connection; + +The architectural principle is to store a minimum of personal data for the shortest time as possible at the Evidos platform. +Only for the time needed to process the transaction; + +If the forms are prefilled with customer data, this data is not stored on the Evidos platform. +When the enduser clicks on the webform URL the customer data is retrieved; + +Retrieving customer data is based on a pull principle. +Evidos forms gets the data using an integration with the customer system. +Preferable a JSON/REST webservice; + +Evidos has several standard REST API integrations available for common customer systems like Salesforce to retrieve the customer data; + +Detailed mapping of the REST API and data forms is dependent on the design of the form and required data fields. +They follow the same implementation principles as described below. + +## Sequence diagram +The integration of Evidos Forms makes use of the following components; + - **Enduser**; Enduser using a (mobile) browser to fill in the form and sign the contract(s) + - **Evidos Forms**; The module that provides the webform and optionally retrieves the data from the customer system + - **Customer system**; The system of the customer where enduser data is available, retrieved and signed contracts are stored. + - **Evidos Signhost**; The Evidos signing platform to sign the documents. + +The following sequence diagram shows an example of the process flow of the webform signing integration + +**Evidos Forms Signhost integration** +![Sequence diagram](images/sequence_diagram.svg) diff --git a/forms/initiate.md b/forms/initiate.md new file mode 100644 index 0000000..e323d47 --- /dev/null +++ b/forms/initiate.md @@ -0,0 +1,65 @@ +--- +layout: page +title: Initiate Form URL +permalink: forms/initiate/ +product: Forms +--- + +For the webform there is two possible scenario’s +1. Non prefilled form; this is a standard form that can be filled by any customer that receives the same link +2. Prefilled form; the form is prefilled with data from the customer system and the link is a personal link + +To initiate a personalized form and retrieve the data, the link contains a unique non guessable id/token. +```https://mydomain.com/form/?id=``` + +Note: although the non-prefilled link does not prefill any personal information, it could be useful to link the final signed document to a certain customer file. +In this case it is possible to include a unique non guessable ID in the URL; ```https://mydomain.com/form/?id=``` + +## Authentication + +When prefilled data is included it could be a requirement to let the enduser login before seeing the personal data. +This could minimize to risk to expose personal data to unauthorized persons. +Optionally it is possible to link the form to the authentication service of the customer. +Evidos Forms will then check if the entered credentials are valid using the customer system REST API. + +## Retrieving the customerdata +When the enduser clicks on the formlink, Evidos Forms will get the prefilled data from the customer system using a Rest API service. +Evidos forms will use the unique non guessable ID within the Rest API to retrieve the data. +Evidos forms has several standard Rest API connections available, further specification of this (existing) customer API is specified within the project. + +The mapping of the formfields and the customer datafields is done during the project and depends on the API specifications and required formfields. + +**Note:** it is not required to show prefilled data as a formfield, this could also be hidden data for use in the customer system. + +## Additional PDF attachments +In certain use cases the customer wants to include a default PDF, or generate PDF in the signing process. +For example when the customer configured a custom proposal from a product configuration system. +It is possible to get this PDF from the customer system. +In this case an additional REST API service must be available to retrieve the document. + +## Errors/ non availability of customer webservice +For prefilled forms it could happen that the webservice of the customer is not available or the specific enduser record is not available. +This will result in a configured error message for the enduser, for example: +> Form is unavailable, try again later or contact your merchant + +Endpoints of the webservice must be monitored by the customer. + +## PDF documents +There are three types of PDF documents that can be included or used to be signed; +1. Default PDF without custom data, these documents can be added automatically and are configured in Evidos Forms; +2. Template PDF, the PDF template that can be filled with the formfields entered by the enduser; +3. Pre-generated PDF, a PDF document that is generated earlier in the journey, for example when the customer configured a custom proposal from a product configuration system. It is possible to get this PDF from the customer system. In this case an additional REST API service must be available to retrieve the document. + +## User filling in the form +When the user clicks the URL the webform is opened. +The user fills in the details and one or more additional checks are performed. + +If the data entry is not correct or results in not finishing the form, the user will be shown the error or mismatch. + +No data is cached. If the user closes the form he is able to open the link again clicking on the link. + +**Note:** The prefilled form URL is available as long as the data can be retrieved from the customer system. +Non-prefilled forms are available until the customer closes the webform by contacting Evidos. + +## Form analytics +Customer can see the analytics of the forms by including their web analytics tools. \ No newline at end of file diff --git a/index.md b/index.md index b3cfcc1..725cc95 100644 --- a/index.md +++ b/index.md @@ -1,169 +1,38 @@ --- -layout: frontpage +layout: page +title: Documentation +product: Evidos --- -The Signhost API is RESTful and HTTP-based. Basically, this means that the communication is made through normal HTTP requests. - -Required steps to create a transaction: - -1. Create a new transaction with [POST api/transaction](/endpoints#%23/paths//api/transaction/post). -2. Optionally you can add metadata to generate fields with [PUT api/transaction/{transactionId}/file/{fileId}](/endpoints#%23/paths//api/transaction/%7BtransactionId%7D/file/%7BfileId%7D/put). -You have to submit the metadata first before you upload the file. -Make sure you use the same fileId for both the metadata and the file. -3. Upload the documents you want to be signed by performing a [PUT api/transaction/{transactionId}/file/{fileId}](/endpoints#%23/paths//api/transaction/%7BtransactionId%7D/file/%7BfileId%7D/put). -Repeat for each file. -4. Finally start the transaction with [PUT api/transaction/{transactionId}/start](/endpoints#%23/paths//api/transaction/%7BtransactionId%7D/start/put). - -### Server Address - -The REST gateway BaseURL is: https://api.signhost.com/api/ - -### Security - -We require that all requests are done over SSL. - -## Authentication - -To authenticate you have to add two HTTP headers to every request you make. -The first header includes the name "Application" with the value "APPKey {appkey here}". -This application key will be provided to you by email. -The second header includes the name "Authorization" with the value "APIKey {your usertoken}". -The Usertoken can be generated via Settings > Usertokens at the [SignHost Portal](https://portal.signhost.com/). -A name for the usertoken has to be submitted, after which the value for this usertoken will be displayed once only. -The amount of usertokens that can be generated for an account is limited to 64. -If more usertokens are needed, this needs to be requested at support@signhost.com. - -Below you find a HTTP request header example: - - Content-Type: application/json - Authorization: APIKey {usertoken here} - Application: APPKey {appkey here} - Accept: application/vnd.signhost.v1+json - Connection: keep-alive - -## Get signed document and receipt - -With the Signhost API it is possible to facilitate two different signing flows to the signer. - -**Invite flow;** Signhost API will send a SignRequest by email to the signer and will facilitate the workflow process for sending reminder emails and the signed result. - -**The direct flow;** The Signhost API returns a URL you will be able to directly redirect the signer on your portal or send the signer a message with the signing link yourself. - -By default the direct flow will be used when you create a transaction. -If you would like to make use of the Invite flow, you can do so by setting the SendSignRequest parameter to TRUE during the POST api/transaction. - -If you choose to make use of the Invite flow we will send a reminder after 7 days, you can adjust the amount of days by supplying a DaysToRemind parameter during the POST api/transaction (a value of -1 disables reminders). - -When the transaction is successfully signed (Status=30) you will be able to GET the signed document and receipt with a HTTP GET request to [api/transaction/{transactionId}/file/{fileId}](/endpoints#%23/paths//api/transaction/%7BtransactionId%7D/file/%7BfileId%7D//get) or [api/file/receipt/{transactionId}](/endpoints#%23/paths//api/file/receipt/%7BtransactionId%7D/get). -Do not forget to add the authorization headers as well. - -For legal proof it is important to store both the signed document and the receipt. - -* The Sender will receive the signed documents and receipt per mail when the **SendEmailNotifications** is set to true. -* The Signers will receive the signed documents and receipt per mail when the **SendSignConfirmation** is set to true. -* The Receivers will always receive the signed documents per mail. - -## Specify signature location - -We provide three ways to specify the location for the signatures. - -### Signer tag - -In our API it is possible to specify the signature location in the PDF document. When you create the PDF that needs to be signed you can include the tag {% raw %}{{Signer1}}, {{Signer2}}{% endraw %}, etc.. at the location you want the signature displayed. - -If you do not want to show a {% raw %}{{Signer}}{% endraw %} tag in your document you can give the tag the background colour of your document, in general this is the colour white. - -Although PDF is a document standard we strongly recommend to test the signer location and {% raw %}{{Signer}}{% endraw %} tag to see if the location is correct. - -Please be aware that including a lot of {% raw %}{{Signer}}{% endraw %} tags will have an impact on the performance and signature validation process. For a digital signature we do not recommend to include a signature on every page. If you do not include the {% raw %}{{Signer}}{% endraw %} tag, or you do not use another way to specify the location, we will use the default signing location; top right on the first page. - -### Create fields through API calls - -A second method of specifying the signature location is via the api. - -For this method you do not need to prepare the PDF file in any way. -The flow of making a transaction is basically the same as before, although this time you need to add file metadata to the transaction before uploading the file(s). -For more information about this method please take a further look at the following post: [How to create a transaction with api generated fields]({% post_url 2016-10-06-api-generated-fields %}). - -### Signature fields - -Besides specifying the signature location via the signer tag or via the API you also make use of pdf signature fields. -This method is not recommended as it requires external PDF tools. -To make sure that the signature fields are recognized they have to be named a specific pattern: Signature-x_y. Where the x stands for the signer and the y for the signature number. - -For example: Signature-1_2 will specify the place for the second signature of the first signer. - -## Webhook / Postback URL - -In your request you can specify a PostbackUrl. -On this URL on your own server Signhost will do a POST with the status of the request. -We only support a postback on the default https:// port 443. -Port 80 / http:// is *not* supported. -We will only issue 1 postback per PostbackURL at a time, one-by-one. - -When a postback fails we will queue all new postbacks and retry these again at a later time. -If the postback succeeds again we will continue issuing the remaining queued postbacks. - -For more information about postbacks and calculating the checksum and the body of the request view the [webhook postback sample](/postback) help page. - -## Return URL Parameters - -When the user signs or rejects the transaction we will redirect the browser to the return URL. -The return URL will have one of the following parameters, determined by the user action: - -* **User signs :** - https://www.example.org/[yourReturnUrl]?sh_signerstatus=signed -* **User rejects :** - https://www.example.org/[yourReturnUrl]?sh_signerstatus=rejected -* **Other :** - https://www.example.org/[yourReturnUrl] or https://www.example.org/[yourReturnUrl]?sh_signerstatus= - -The user actions provide an indication on what the user chose to do. -However, you must validate the actual status using the API, and you should not trust the sh_signerstatus for any important processing. -Depending on the communicated sh_signerstatus, you might want to show a different page. -Once the user signed or rejected the transaction, the server will process the input. -Therefore, the return URL will always be available before the transaction status has been updated. -Once the server has completed processing, a new postback will be send with the new transaction status. - -## Return codes - -Our REST API uses the standard [HTTP/1.1 status codes](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) to return the status of your request. -In short this means that any status code in the range of: - -* **2xx** (eg 200) your request was successful; -* **4xx** (eg 400 bad request, invalid email address) there is an error in your request. -You must not retry this request unless you have corrected the error; -* **5xx** (eg 500) there was an error on our side. You may retry this request at a later time. -If you implement a retry policy you should use a backoff policy. - -## Formats - -JSON results which contain a date, time or datetime property are formatted according to [ISO8601](https://www.iso.org/iso/iso8601). A short explanation of the format is available at [w3.org - Date and Time Formats](https://www.w3.org/TR/NOTE-datetime). - -## Libraries & demos - -There are a few libraries and demos available to make connecting to our API easier. - -* [.Net Client Library](https://github.com/Evidos/SignhostClientLibrary) -* [PHP Demo Client](https://github.com/Evidos/signhost-phpdemoclient) -* [Java Client Library](https://github.com/Evidos/OndertekenenDemo-Java) -* [SignHost Ruby Gem](https://rubygems.org/gems/sign_host) - -## Handy tools - -* [Webhook Tester](https://webhook.site) / [Webhook Inbox*](http://webhookinbox.com/) for testing the postback. -* [JSONLint](https://jsonlint.com/) for formatting and checking json messages. - -\* Webhook Inbox only supports HTTP. +Evidos stands for Evidence in Online Services, that is to say being secure while operating on the internet. +Evidos is a market leader in the field of electronic signatures and electronic identification. +Our solutions allow you to conduct your business on the internet quickly, safely and in a legally valid manner, enabling faster and more efficient delivery of your products and services. + +For over a decade, Evidos has been actively involved in the latest national and international standards, legislation and technologies for identity verification and electronic signatures. +Thanks to our business administration background and excellent understanding of the technical aspects, we can offer solutions to a wide range of companies and organisations in various sectors. +We offer solutions that are both high quality and outcome-driven. + +## Products +This documentation website provides documentation for the following Evidos products: + +
    +{% for product in site.data.structure %} + {% unless product.name == "Evidos" %} +
  • + {{ product.name }} +
    • + {% endunless %} +{% endfor %} +
## Posts
    {% for post in site.posts reversed %}
  • - {{ post.date | date: "%b %-d, %Y" }} + {{ post.date | date: "%b %-d, %Y" }} - {{ post.product }}

    - {{ post.title }} + {{ post.title }}

    • {% endfor %} diff --git a/endpoints.html b/signhost/endpoints.html similarity index 98% rename from endpoints.html rename to signhost/endpoints.html index 1101107..4b4e2a5 100644 --- a/endpoints.html +++ b/signhost/endpoints.html @@ -1,7 +1,12 @@ --- layout: page title: Endpoints & Model types -permalink: /endpoints/ +permalink: signhost/endpoints/ +product: Signhost + +redirect_from: + - /endpoints + - /endpoints/ ---

    You can make HTTP GET, POST or PUT Requests. Requests are passed to the API by using JSON objects to the API endpoints with the appropriate parameters. The documentation for each API call will contain more detail on the parameters accepted by the call.

    diff --git a/signhost/index.md b/signhost/index.md new file mode 100644 index 0000000..889b641 --- /dev/null +++ b/signhost/index.md @@ -0,0 +1,173 @@ +--- +layout: page +title: Basic Information +permalink: signhost/ +product: Signhost +--- + +The Signhost API is RESTful and HTTP-based. Basically, this means that the communication is made through normal HTTP requests. + +Required steps to create a transaction: + +1. Create a new transaction with [POST api/transaction](endpoints#%23/paths//api/transaction/post). +2. Optionally you can add metadata to generate fields with [PUT api/transaction/{transactionId}/file/{fileId}](endpoints#%23/paths//api/transaction/%7BtransactionId%7D/file/%7BfileId%7D/put). +You have to submit the metadata first before you upload the file. +Make sure you use the same fileId for both the metadata and the file. +3. Upload the documents you want to be signed by performing a [PUT api/transaction/{transactionId}/file/{fileId}](endpoints#%23/paths//api/transaction/%7BtransactionId%7D/file/%7BfileId%7D/put). +Repeat for each file. +4. Finally start the transaction with [PUT api/transaction/{transactionId}/start](endpoints#%23/paths//api/transaction/%7BtransactionId%7D/start/put). + +### Server Address + +The REST gateway BaseURL is: https://api.signhost.com/api/ + +### Security + +We require that all requests are done over SSL. + +## Authentication + +To authenticate you have to add two HTTP headers to every request you make. +The first header includes the name "Application" with the value "APPKey {appkey here}". +This application key will be provided to you by email. +The second header includes the name "Authorization" with the value "APIKey {your usertoken}". +The Usertoken can be generated via Settings > Usertokens at the [SignHost Portal](https://portal.signhost.com/). +A name for the usertoken has to be submitted, after which the value for this usertoken will be displayed once only. +The amount of usertokens that can be generated for an account is limited to 64. +If more usertokens are needed, this needs to be requested at support@signhost.com. + +Below you find a HTTP request header example: + + Content-Type: application/json + Authorization: APIKey {usertoken here} + Application: APPKey {appkey here} + Accept: application/vnd.signhost.v1+json + Connection: keep-alive + +## Get signed document and receipt + +With the Signhost API it is possible to facilitate two different signing flows to the signer. + +**Invite flow;** Signhost API will send a SignRequest by email to the signer and will facilitate the workflow process for sending reminder emails and the signed result. + +**The direct flow;** The Signhost API returns a URL you will be able to directly redirect the signer on your portal or send the signer a message with the signing link yourself. + +By default the direct flow will be used when you create a transaction. +If you would like to make use of the Invite flow, you can do so by setting the SendSignRequest parameter to TRUE during the POST api/transaction. + +If you choose to make use of the Invite flow we will send a reminder after 7 days, you can adjust the amount of days by supplying a DaysToRemind parameter during the POST api/transaction (a value of -1 disables reminders). + +When the transaction is successfully signed (Status=30) you will be able to GET the signed document and receipt with a HTTP GET request to [api/transaction/{transactionId}/file/{fileId}](endpoints#%23/paths//api/transaction/%7BtransactionId%7D/file/%7BfileId%7D//get) or [api/file/receipt/{transactionId}](endpoints#%23/paths//api/file/receipt/%7BtransactionId%7D/get). +Do not forget to add the authorization headers as well. + +For legal proof it is important to store both the signed document and the receipt. + +* The Sender will receive the signed documents and receipt per mail when the **SendEmailNotification** is set to true. +* The Signers will receive the signed documents and receipt per mail when the **SendSignConfirmation** is set to true. +* The Receivers will always receive the signed documents per mail. + +## Specify signature location + +We provide three ways to specify the location for the signatures. + +### Signer tag + +In our API it is possible to specify the signature location in the PDF document. When you create the PDF that needs to be signed you can include the tag {% raw %}{{Signer1}}, {{Signer2}}{% endraw %}, etc.. at the location you want the signature displayed. + +If you do not want to show a {% raw %}{{Signer}}{% endraw %} tag in your document you can give the tag the background colour of your document, in general this is the colour white. + +Although PDF is a document standard we strongly recommend to test the signer location and {% raw %}{{Signer}}{% endraw %} tag to see if the location is correct. + +Please be aware that including a lot of {% raw %}{{Signer}}{% endraw %} tags will have an impact on the performance and signature validation process. For a digital signature we do not recommend to include a signature on every page. If you do not include the {% raw %}{{Signer}}{% endraw %} tag, or you do not use another way to specify the location, we will use the default signing location; top right on the first page. + +### Create fields through API calls + +A second method of specifying the signature location is via the api. + +For this method you do not need to prepare the PDF file in any way. +The flow of making a transaction is basically the same as before, although this time you need to add file metadata to the transaction before uploading the file(s). +For more information about this method please take a further look at the following post: [How to create a transaction with api generated fields]({% post_url 2016-10-06-api-generated-fields %}). + +### Signature fields + +Besides specifying the signature location via the signer tag or via the API you also make use of pdf signature fields. +This method is not recommended as it requires external PDF tools. +To make sure that the signature fields are recognized they have to be named a specific pattern: Signature-x_y. Where the x stands for the signer and the y for the signature number. + +For example: Signature-1_2 will specify the place for the second signature of the first signer. + +## Webhook / Postback URL + +In your request you can specify a PostbackUrl. +On this URL on your own server Signhost will do a POST with the status of the request. +We only support a postback on the default https:// port 443. +Port 80 / http:// is *not* supported. +We will only issue 1 postback per PostbackURL at a time, one-by-one. + +When a postback fails we will queue all new postbacks and retry these again at a later time. +If the postback succeeds again we will continue issuing the remaining queued postbacks. + +For more information about postbacks and calculating the checksum and the body of the request view the [webhook postback sample](postback) help page. + +## Return URL Parameters + +When the user signs or rejects the transaction we will redirect the browser to the return URL. +The return URL will have one of the following parameters, determined by the user action: + +* **User signs :** + https://www.example.org/[yourReturnUrl]?sh_signerstatus=signed +* **User rejects :** + https://www.example.org/[yourReturnUrl]?sh_signerstatus=rejected +* **Other :** + https://www.example.org/[yourReturnUrl] or https://www.example.org/[yourReturnUrl]?sh_signerstatus= + +The user actions provide an indication on what the user chose to do. +However, you must validate the actual status using the API, and you should not trust the sh_signerstatus for any important processing. +Depending on the communicated sh_signerstatus, you might want to show a different page. +Once the user signed or rejected the transaction, the server will process the input. +Therefore, the return URL will always be available before the transaction status has been updated. +Once the server has completed processing, a new postback will be send with the new transaction status. + +## Return codes + +Our REST API uses the standard [HTTP/1.1 status codes](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) to return the status of your request. +In short this means that any status code in the range of: + +* **2xx** (eg 200) your request was successful; +* **4xx** (eg 400 bad request, invalid email address) there is an error in your request. +You must not retry this request unless you have corrected the error; +* **5xx** (eg 500) there was an error on our side. You may retry this request at a later time. +If you implement a retry policy you should use a backoff policy. + +## Formats + +JSON results which contain a date, time or datetime property are formatted according to [ISO8601](https://www.iso.org/iso/iso8601). A short explanation of the format is available at [w3.org - Date and Time Formats](https://www.w3.org/TR/NOTE-datetime). + +## Libraries & demos + +There are a few libraries and demos available to make connecting to our API easier. + +* [.Net Client Library](https://github.com/Evidos/SignhostClientLibrary) +* [PHP Demo Client](https://github.com/Evidos/signhost-phpdemoclient) +* [Java Client Library](https://github.com/Evidos/OndertekenenDemo-Java) +* [SignHost Ruby Gem](https://rubygems.org/gems/sign_host) + +## Handy tools + +* [Webhook Tester](https://webhook.site) / [Webhook Inbox*](http://webhookinbox.com/) for testing the postback. +* [JSONLint](https://jsonlint.com/) for formatting and checking json messages. + +\* Webhook Inbox only supports HTTP. + +## Posts +
      + {% for post in site.posts reversed %} +
    • + {{ post.date | date: "%b %-d, %Y" }} + +

      + {{ post.title }} +

      +
      • + {% endfor %} +
    diff --git a/postback.md b/signhost/postback.md similarity index 98% rename from postback.md rename to signhost/postback.md index 1c5c79c..d591cad 100644 --- a/postback.md +++ b/signhost/postback.md @@ -1,7 +1,12 @@ --- layout: page title: Postback -permalink: /postback/ +permalink: signhost/postback/ +product: Signhost + +redirect_from: + - /postback + - /postback/ --- The Signhost postback service is meant to provide realtime updates on your transactions. diff --git a/status-activities.html b/signhost/status-activities.html similarity index 89% rename from status-activities.html rename to signhost/status-activities.html index 78af4ad..ae9e2e0 100644 --- a/status-activities.html +++ b/signhost/status-activities.html @@ -1,7 +1,12 @@ --- layout: page title: Statuses & Activities -permalink: /status-activity/ +permalink: signhost/status-activity/ +product: Signhost + +redirect_from: + - /status-activity + - /status-activity/ ---

    Some of our endpoints return both the status of the transaction and signer activities. A list of all the statuses as well as a list of all the activities can be found below.

    Transaction Statuses