SignWise Services REST API overview 2017-07-12T20:54:41+00:00

SignWise Services REST API allows you to authenticate users, generate documents, create and share documents, request from users electronic signatures and validate electronic signatures. Users can use their current electronic identity. There are different levels of integration available out of which you must determine the one that suits you best.

Integration Methods Diagrams for electronic signing process

Making an integration with SignWise Services is achieved through REST API calls to SignWise Services application in your backend code. You may choose to use one of our Server SDK, or you may make the API calls directly.You can implement the web interface for authentication and signing yourself, or you can use SignWise Services UI so you can avoid any frontend development altogether. You can also combine the two methods, e.g., your agents can manage the document lifecycle and sign the documents in your information system, while the end users can sign the documents in SignWise Services UI, never having to gain access to your information system.

Integration method no. 1 – SignWise Services UI: e-signing documents with customers

SignWise Services UI  (SignLink) is a Signwise Corporation Limited managed web page where it is possible to sign documents that are shared by SignWise Services API. All recipients have their personalised URL that directs them to the place where they can sign the document. This is used if the integrator does not want to let third party sign in their info-system or does not want to manage all the difficulties that come with online electronic signing and secure authentication and document delivery to the signee.

Integration method no. 2 – Customer application User Interface –  e-signing documents with customer

For systems where it is necessary to create, manage and sign documents, SignWise Services API can be used as a library that hides all the difficult tasks and provides easy-to-use API.

  • SignWise Services application – The main endpoint for SignWise Services that provides the core functionality: creating the document, managing its lifecycle, storing and validating signatures. This component runs at SignWise, and the access is with a client certificate.
  • Server-SDK – Back-end library to use in your code. It consists of the API-Client that facilitates the use of SignWise Services Application and File Proxy that provides a sample interface for your file storage.
  • Your file storage – File storage of your choice that allows read and write operations. SignWise will not store any instance of your data (files) and will access your file storage only when required to perform a requested operation.
  • Smart Card SDK – JavaScript library for communicating with SignWise Web Browser Module. You need to download and use Smart Card SDK in your frontend code if you choose Integration Method 2, and you require strong authentication and signing functionality.
  • Mobile ID SDK – JavaScript library for communicating with Mobile ID services. You need to download and use Mobile ID SDK in your frontend code if you choose Integration Method 2 and need Mobile ID authentication and signing support
  • SignWise Services UI – Hosted frontend for authenticating or signing using the smart card or Mobile ID. This component runs at SignWise, and the access is unrestricted by default. Users will arrive at SignWise Services UI either by being redirected from your web page or by following their personalized link in the e-mail. SignWise Services UI provides the leverage when using Integration Method 1.
  • SignWise Web Browser Module – Web browser Module developed by SignWise for Microsoft Windows and Mac OS X platforms to allow authentication and signing using smart cards. Your users must install this module to use smart cards.

About electronic signing

Containers To simplify, container in this scope is a file that can contain both files and signatures. Think ZIP that contains other files. If API integrator wants users to electronically sign files (.doc, .pdf, .jpg etc) the integrator should create a container (POST /container) that includes these files. Then the user can sign the container that includes the files, so the file and signature are included in one package. It is also possible to sign PDF files without putting them to the container. In this case creating a container in not required, because PDF can contain signatures itself, thus making a PDF file also a container. Decision about whether to put the PDF into a container a sign PDF directly depends on the country where the signing is intended to take place.

Signatures

Digital signature is a way to connect the person with ID-card and the files. Using private key that is located in secure signing device (ID-card, USB stick or SIM card) it is possible to sign the hash of the document container, resulting in a signature that is put to that document container.

{
  "outputPath":"//fp/path/to/container",
  "containerType":"ddoc",
  "overwrite":true,
  "files":[
    {
      "inputPath":"//fp/path/to/container/file-1",
      "fileName":"file1",
      "fileType":"application/octet-stream"
    },
    {
      "inputPath":"//fp/path/to/container/file-2",
      "fileName":"file2",
      "fileType":"application/octet-stream"
    }
  ]
}

Integration use-cases

Authentication

API user authentication is done via SSL client certificate authentication. Credentials for certificate generation can be obtained by contacting support@signwise.org.

Then you get a link to our certificate enrollment page where you generate and download a PKCS #12 container with file extension of .p12. From this container the integrator can extract the files necessary for client certificate authentication. Sample tools for extraction:

  1. //www.openssl.org/docs/apps/pkcs12.html
  2. //keystore-explorer.sourceforge.net

Files included in the container:

  1. X.509 private key
  2. X.509 public key
  3. Certificate Chain (Root and intermediate X.509 public certificates used to sign the users certificate)

Files

To create a container, integrator can use POST /container path with sample message body:

{
  "outputPath":"//fp/path/to/container",
  "containerType":"ddoc",
  "overwrite":true,
  "files":[
    {
      "inputPath":"//fp/path/to/container/file-1",
      "fileName":"file1",
      "fileType":"application/octet-stream"
    },
    {
      "inputPath":"//fp/path/to/container/file-2",
      "fileName":"file2",
      "fileType":"application/octet-stream"
    }
  ]
}

In this example, a ASICe document container is created. Steps that SignWise Services API has to do:
1. Create empty ASICe
2. Download files listed in files array from their inputPath
3. Add downloaded files to the ASICe container
4. Upload ASICe container to outputPath

It is important to know, that SignWise Services API does not store the file at SignWise. This means that at every request that uses either inputPath, outputPath or both, the file is downloaded and uploaded again.

Therefore, an API integrator must implement a file-proxy, that serves files for the SignWise Services from specified paths.

Protocol for file operations:
– SignWise Services makes http GET request to path and expects that the response is a file. Success http status code: 200
– SignWise Services makes http PUT request to path. PUT body will be the file. Success http status code: 201

inputPath, outputPath and tmpPath must all support both GET and PUT operations. If status code is other than 200 for GET or 201 for PUT, General File Proxy error is raised.

API events

In this example, a DDOC container is created. Steps that SignWise Services API has to do:
1. Create empty DDOC
2. Download files listed in files array from their inputPath
3. Add downloaded files to the DDOC container
4. Upload DDOC container to outputPath

It is important to know, that SignWise Services API does not store the file at SignWise. This means that at every request that uses either inputPath, outputPath or both, the file is downloaded and uploaded again.

Therefore, an API integrator must implement a file-proxy, that serves files for the SignWise Services from specified paths.

Protocol for file operations:

  • SignWise Services makes http GET request to path and expects that the response is a file. Success http status code: 200
  • SignWise Services makes http PUT request to path. PUT body will be the file. Success http status code: 201

inputPath, outputPath and tmpPath must all support both GET and PUT operations. If status code is other than 200 for GET or 201 for PUT, General File Proxy error is raised.

Sharing

  1. POST /share returns signlinkURL for every recipient. API Integrator can redirect the user to this url.
  2. POST /share accepts body.notifications array that is used to specify the notifications sent to the user via email/sms. These notifications also include the signlinkURL so if share-created template was added, the user can click on the link in email and end up in Signlink.

All shares have a deadline. After the expire date nobody is allowed to sign anymore, but users can still access the share information and download the container if they had signed the document before the deadline.

All shares have auth on by default. This means that all recipients have to identify with PIN 1 before accessing the share and container information. If also recipient.ssn and recipient.country are used, Signlink verifies that users’ certificate subject country and serial number match with these values. It can be used to restrict the document access to specific persons, not just to the person who has the unique recipient signlinkURL link.

Formats

Container data varies based on the container type. While BDOC/EDOC/AsanDOC/ASICe are normalized to one structure.

"data": {
  "signatures": [
    {
      "id": "S0",
      "profile": "TM", //TM - TimeMark, TS - TimeStamp
      "status": "OK_TEST", //OK, OK_TEST, ERROR, ERROR_TEST
      "errors": [],
      "warnings": [],
      "signingTime": 1408605660000,
      "roles": [],
      "place": {
        "city": "Tallinn",
        "state": null,
        "postalCode": null,
        "country": null
      },
      "signerCertificate": {
        "issuer": {
          "raw": "email=pki@sk.ee, commonName=TEST of ESTEID-SK 2011, organization=AS Sertifitseerimiskeskus, country=EE",
          "country": "EE",
          "email": "pki@sk.ee",
          "commonName": "TEST of ESTEID-SK 2011",
          "organization": "AS Sertifitseerimiskeskus"
        },
        "subject": {
          "raw": "identificationCode=47101010033, firstName=MARI-LIIS, lastName=MÄNNIK, commonName="MÄNNIK,MARI-LIIS,47101010033", unitName=digital signature, organization=ESTEID, country=EE",
          "country": "EE",
          "identificationCode": "47101010033",
          "firstName": "MARI-LIIS",
          "lastName": "MÄNNIK",
          "commonName": ""MÄNNIK",
          "organization": "ESTEID",
          "unitName": "digital signature"
        },
        "validFrom": 1360154523000,
        "validTo": 1517695199000,
        "serial": "51979518684612199197274112989154467246"
      },
      "confirmation": {
        "responderId": "C=EE,O=AS Sertifitseerimiskeskus,OU=OCSP,CN=TEST of SK OCSP RESPONDER 2011,E=pki@sk.ee",
        "producedAt": 1408605667000,
        "certificate": {
          "issuer": {
            "raw": "email=pki@sk.ee, commonName=TEST of EE Certification Centre Root CA, organization=AS Sertifitseerimiskeskus, country=EE",
            "country": "EE",
            "email": "pki@sk.ee",
            "commonName": "TEST of EE Certification Centre Root CA",
            "organization": "AS Sertifitseerimiskeskus"
          },
          "subject": {
            "raw": "email=pki@sk.ee, commonName=TEST of SK OCSP RESPONDER 2011, unitName=OCSP, organization=AS Sertifitseerimiskeskus, country=EE",
            "country": "EE",
            "email": "pki@sk.ee",
            "commonName": "TEST of SK OCSP RESPONDER 2011",
            "organization": "AS Sertifitseerimiskeskus",
            "unitName": "OCSP"
          },
          "validFrom": 1299504165000,
          "validTo": 1725711765000,
          "serial": "138983222239407220571566848351990841243"
        }
      },
      "timestamps": []
    }
  ],
  "dataFiles": [
    {
      "path":"//fp/path/to/container/file-1",
      "size": 705298,
      "mimeType": "application/octet-stream",
      "fileName": "file1",
      "id": "D0"
    },
    {
      "path":"//fp/path/to/container/file-2",
      "size": 705298,
      "mimeType": "application/octet-stream",
      "fileName": "file2",
      "id": "D1"
    }
  ],
  "size": 705617,
  "version": "1.3",
  "format": "DIGIDOC-XML"
}

PDF format

PDF has a slightly different data.signatures structure. Check difference at id vs revision/name and roles/place vs reason/location.

{
  "data": {
    "signatures": [
      {
        "name": "Signature1",
        "revision": 1,
        "status": "OK_TEST",
        "error": null,
        "signingTime": 1408452848000,
        "reason": "",
        "location": "Tallinn",
        "signerCertificate": {
          "issuer": {
            "raw": "email=pki@sk.ee, commonName=TEST of ESTEID-SK 2011, organization=AS Sertifitseerimiskeskus, country=EE",
            "country": "EE",
            "email": "pki@sk.ee",
            "commonName": "TEST of ESTEID-SK 2011",
            "organization": "AS Sertifitseerimiskeskus"
          },
          "subject": {
            "raw": "identificationCode=14212128025, firstName=SEITSMES, lastName=TESTNUMBER, commonName="TESTNUMBER,SEITSMES,14212128025", unitName=digital signature, organization=ESTEID (MOBIIL-ID), country=EE",
            "country": "EE",
            "identificationCode": "14212128025",
            "firstName": "SEITSMES",
            "lastName": "TESTNUMBER",
            "commonName": ""TESTNUMBER",
            "organization": "ESTEID (MOBIIL-ID)",
            "unitName": "digital signature"
          },
          "validFrom": 1333537064000,
          "validTo": 1428181199000,
          "serial": "124389723988450407130206225571707197361"
        },
        "confirmation": {
          "responderId": "C=EE,O=AS Sertifitseerimiskeskus,OU=OCSP,CN=TEST of SK OCSP RESPONDER 2011,E=pki@sk.ee",
          "producedAt": 1408452829000,
          "certificate": null
        },
        "timestamps": [
          {
            "serialNumber": "8004496948939076",
            "created": 1408452848000,
            "policy": "1.3.6.1.4.1.5309.1.2.2",
            "errorBound": null,
            "ordered": false,
            "tsa": "6: //timestamping.edelweb.fr/",
            "certificate": {
              "issuer": {
                "raw": "commonName=Time Stamping Authority, unitName=Clepsydre Demonstration Service, organization=EdelWeb S.A., country=FR",
                "country": "FR",
                "commonName": "Time Stamping Authority",
                "organization": "EdelWeb S.A.",
                "unitName": "Clepsydre Demonstration Service"
              },
              "subject": {
                "raw": "commonName=Experimental Time Stamping Service, unitName=Project K7 Illidium Ultraspace Gas Factory, organization=EdelWeb S.A., country=FR",
                "country": "FR",
                "commonName": "Experimental Time Stamping Service",
                "organization": "EdelWeb S.A.",
                "unitName": "Project K7 Illidium Ultraspace Gas Factory"
              },
              "validFrom": 1023726041000,
              "validTo": 1654446041000,
              "serial": "72681180395546645"
            }
          }
        ]
      }
    ],
    "dataFiles": [],
    "size": 345654,
    "version": "4",
    "format": "PDF"
  }
}

Sample flows

To create a document container (BDOC/EDOC/AsanDOC/ASICe) and share it for signing in SignWise Services UI (Signlink).

1. POST /container

2. POST /container/share

Create a PDF share for having a visual signature badge on the document with coordinates.

{
  "visualSignature": {
    "type": "coordinates",
    "page": 1,
    "coordinates": [150, 100]
  }
}

Create a PDF share for having a visual signature badge on the document with placeholder.

POST /share with recipients array where every recipient object in the array has visualSignature attribute as follows:

{
  "visualSignature": {
    "type": "placeholder",
    "placeholder": "STRING IN THE PDF DOCUMENT"
  }
}

Create a PDF share for having a visual signature badge on the document by user dragging the badge to the document.

POST /share with recipients array where every recipient object in the array has visualSignature attribute as follows:

{
  "visualSignature": {
    "type": "user"
  }
}

Signing a document container (BDOC/EDOC/AsanDOC/ASICe) within integrator internal platform using tokens like (smart card and/or USB token)

{
  "visualSignature": {
    "type": "placeholder",
    "placeholder": "STRING IN THE PDF DOCUMENT"
  }
}

Signing a PDF within integrators system with visual signature badge using coordinates and tokens like (smart card and/or USB token)

POST /container/sign/prepare with visual signature parameters containing type of coordinates

{
  "signerInfo": {
    "visualSignature": {
      "type": "coordinates",
      "page": 1,
      "coordinates": [150, 100]
    }
  }
}

Sign the digest return in prepare with signing Web Browser Module (old name: SignWise Plugin)
POST /container/sign/finalize

Signing a PDF within integrators system with visual signature badge using placeholder and tokens like (smart card and/or USB token)

POST /container/sign/prepare with visual signature parameters containing type of placeholder

{
  "signerInfo": {
    "visualSignature": {
      "type": "placeholder",
      "placeholder": "STRING IN THE DOCUMENT"
    }
  }
}

Sign the digest return in prepare with signing Web Browser Module in web.
POST /container/sign/finalize

Signing a document container (BDOC/EDOC/AsanDOC/ASICe) within integrators system using mobileID

1. POST /container/sign/mobileID
2. User enters PIN in mobile device
3. SignWise Services API gets the response from mobile service provider and adds the signature to the document container
4. SignWise Services API makes POST callbackURL specified in the first step body to notify the integrator platform

  1. POST /container/sign/mobileID
  2. User enters PIN in mobile device
  3. SignWise Services API gets the response from mobile service provider and adds the signature to the document container
  4. SignWise Services API makes POST callbackURL specified in the first step body to notify the integrator platform

Signing a PDF within integrators system with visual signature badge using coordinates and mobileID

1. POST /container/sign/mobile

{
"signerInfo": {
"visualSignature": {
"type": "coordinates",
"page": 1,
"coordinates": [150, 100]
}
}
}

2. User enters PIN in mobile device 3. SignWise Services API gets the response from mobile service provider and adds the signature to the container 4. SignWise Services API makes POST callbackURL specified in the first step body to notify the integrator

Signing a PDF within integrators system with visual signature badge using placeholder and mobileID

1. POST /container/sign/mobile

{
  "signerInfo": {
    "visualSignature": {
      "type": "placeholder",
      "placeholder": "STRING IN THE DOCUMENT"
    }
  }
}

2. User enters PIN in mobile device
3. SignWise Services API gets the response from mobile service provider and adds the signature to the container
4. SignWise Services API makes POST callbackURL specified in the first step body to notify the integrator

By continuing to use the site, you agree to the use of cookies. more information

The cookie settings on this website are set to "allow cookies" to give you the best browsing experience possible. If you continue to use this website without changing your cookie settings or you click "Accept" below then you are consenting to this.

Close