How to execute an OAuth API Authentication

In his walk through we will be referring to the following example, where the client service alias is PRT.505767457-PRT.111222333-e064c8c0-32ad-4dcf-9a76-f7542a5bae15 and the defined client service is test_123_Test_456_!!!

Steps:

1. generate the base64 of the string relative to <client service alias>:<client service password>. In our example it would be PRT.505767457-PRT.111222333-e064c8c0-32ad-4dcf-9a76-f7542a5bae15:test_123_Test_456_!!! (please note the colon sign “:”).

   1. Example using https://www.base64encode.org/ will produce the encoded base64 credential string UFJULjUwNTc2NzQ1Ny1QUlQuMTExMjIyMzMzLWUwNjRjOGMwLTMyYWQtNGRjZi05YTc2LWY3NTQyYTViYWUxNTp0ZXN0XzEyM19UZXN0XzQ1Nl8hISE=

      

2. Authenticate your client service with the base64 credential string

   1. Example using curl command (linux command line https://curl.se/docs/manpage.html )

      # Input Command
      curl --insecure -v -X POST https://staging.must.digital/oauth2/authorization-server/oauth/token -d "grant_type=client_credentials" -H "Authorization: Basic UFJULjUwNTc2NzQ1Ny1QUlQuMTExMjIyMzMzLWUwNjRjOGMwLTMyYWQtNGRjZi05YTc2LWY3NTQyYTViYWUxNTp0ZXN0XzEyM19UZXN0XzQ1Nl8hISE="
      
      # Output Response from service
      {"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOb24td3MiXSwic2NvcGUiOlsicmVhZCIsIndyaXRlIl0sImV4cCI6MTY1NjQyMTk4OCwianRpIjoiaU1IRWdrTUhySlc1MmVvdDZyaVlxN1gyUWdBIiwiY2xpZW50X2lkIjoiUFJULjUwNTc2NzQ1Ny1QUlQuMTExMjIyMzMzLWEwZjViOGIwLTk3OGUtNDUwMy04OTU4LTZmZTBjYzAyNmZhMCJ9.OfeSMcsHgnFak3fl1I31reu6f8evrVceYa_LA4YeJrsDkHJMiZfie0KnSflteWVYsTvydqteBZC7fd8mPxslIvzn20fwYvCp8OpnBCV0oYEnLuyfYbTmgJltHho7XenLTZXPa3WVQmvh7Jp9WJQWID7iH6qruZOX2iHBNLwNuLGr6R9jv9k7Vy78tjqjm0LlT6KUL41UehWr3hakMSUOlLk8PQIvmsm8MzzQBnFtPre3bsFxXbimg7s-EuzO4JxOFHO9cw2132kV1Q","token_type":"bearer","expires_in":86399,"scope":"read write","jti":"iMHEgkMHrJW52eot6rgA"}

3. At this point you have successfully retrieved an access token to be used in the API business calls, and that will be expired in 86399 seconds (~24h)

How to apply a visible signature in a PDF file

The visible signature on a PDF file is an option that the client service can request to be applied on a given document. The business API allows the definition of the visible signature to be applied through the usage of the structure SignRequest > documents[i] > signatureInfo > visibleSignatureInfo (https://staging.must.digital/signstash/einvoice-integration-ws/swagger-ui/index.html#/Document%20sign%20service./signDocumentBatchBase64UsingPOST).

This identification of the location where the visible signature will be applied can be set in one of the following ways:

• SIGN_FIELD: Use a signature field present in the document. The signature field name should be set in the locationValue request attribute.

• COORDINATE: Use a coordinate to find the correct document position. Supported format: page=<page_number>,x=<lower_left_x>,y=<lower_left_y>

• PLACEHOLDER: Use a placeholder (unique word). System will scan the document for the given placeholder and stop in the first occurrence.
  The lower left part of the word will be used as a coordinate to start the drawing of the signature canvas from top/left orientation.
  If the placeholder is not found, an error will be thrown and the signature will not be applied. The placeholder value should be set in the locationValue request attribute.

Applying visible signature based on a signature field

1. Generate your PDF to be signed with a pre-configured signature field. The generation of such PDF is outside the scope of this tutorial, and should be investigated with your PDF generation software provider.

   1. For this example we will use this example PDF which has a signature field with the name “Signature2” (see attachment Test_signature_field.pdf)

   2. As with your typical signature, you’ll need to encode the pdf content in base64 format (see attachment Test_signature_field.b64).

2. Execute sign request on API using method ​/signstash​/einvoice-integration-ws​/api​/v0​/document​/sign​/base64​/ (see attachment Test_signature_request.txt)

   1. Note that locationType and locationValue attributes describes the type of visible signature to apply.

   2. "visibleSignatureInfo": {
        "area": "width=200,height=400",
        "font": "color=#ea9dd3,size=11",
        "locationType": "COORDINATE",
        "locationValue": "page=1,x=200,y=400",
        "oneOffTemplate": "Digitally Signed by $certificate.getCommonName().",
        "templateType": "ONE_OFF"
      }

3. Signature response will present a document with the signature applied on the defined signature field (see attachment Test_signature_field_signed.pdf).

Attachments:

Applying visible signature based on a coordinate

1. Generate your PDF to be signed with a pre-defined area where the signature is to be applied . The generation of such PDF is outside the scope of this tutorial, and should be investigated with your PDF generation software provider.

   1. For this example we will use this example PDF (see attachment Test_coordinate.pdf)

   2. As with your typical signature, you’ll need to encode the pdf content in base64 format (see attachment Test_coordinate.b64).

2. Execute sign request on API using method ​/signstash​/einvoice-integration-ws​/api​/v0​/document​/sign​/base64​/ (see attachment Test_signature_request.txt)

   1. Note that locationType and locationValue attributes describes the type of visible signature to apply.

   2. "visibleSignatureInfo": {
        "area": "width=200,height=400",
        "font": "color=#ea9dd3,size=11",
        "locationType": "COORDINATE",
        "locationValue": "page=1,x=200,y=400",
        "oneOffTemplate": "Digitally Signed by $certificate.getCommonName().",
        "templateType": "ONE_OFF"
      }

3. Signature response will present a document with the signature applied on the defined signature field (see attachment Test_coordinate_signed.pdf).

Attachments:

Applying visible signature based on a placeholder

1. Generate your PDF to be signed with a pre-defined unique word to act as a placeholder that indicates where the visibile signature will begin to be drawn. The generation of such PDF is outside the scope of this tutorial, and should be investigated with your PDF generation software provider.

   1. For better results, it’s advised that the placeholder word be set with a font color the same as the backgound.

   2. For this example we will use this example PDF (see attachment Test_placeholder.pdf)

   3. As with your typical signature, you’ll need to encode the pdf content in base64 format (see attachment Test_placeholder.b64).

2. Execute sign request on API using method ​/signstash​/einvoice-integration-ws​/api​/v0​/document​/sign​/base64​/ (see attachment Test_signature_request.txt)

   1. Note that locationType and locationValue attributes describes the type of visible signature to apply.

   2. "visibleSignatureInfo": {
        "area": "width=200,height=400",
        "font": "color=#ea9dd3,size=11",
        "locationType": "COORDINATE",
        "locationValue": "page=1,x=200,y=400",
        "oneOffTemplate": "Digitally Signed by $certificate.getCommonName().",
        "templateType": "ONE_OFF"
      }

3. Signature response will present a document with the signature applied on the defined signature field (see attachment Test_placeholder_signed.pdf).

Attachments:

Setting up the dynamic information on a visible signature

Use same message to every request for a given client service

You can setup your client service with a default visible signature message to be applied in each document sent to be processed.

To do this please refer to https://must.atlassian.net/wiki/spaces/SIGNSTASH/pages/3408243/Customization#Customize-visual-templates

Configure visible signature message in the request

1. Execute sign request on API using method ​/signstash​/einvoice-integration-ws​/api​/v0​/document​/sign​/base64​/ (see attachment Test_signature_request.txt)

   1. Note that templateType=ONE_OFF indicates that a custom text message will be set in the oneOffTemplate attribute.

   2. In the oneOffTemplate we mix a static message part and a dynamic part that is extracted from the certificate being used to sign the document. In this case we have “Digitally Signed by “ as a static element, and the “$certificate.getCommonName()” as the dynamic element. All the dynamic elements available to use in the signature template are defined in https://must.atlassian.net/wiki/spaces/SIGNSTASH/pages/3408243/Customization#Digital-signature-template

   3. "visibleSignatureInfo": {
        "area": "width=200,height=400",
        "font": "color=#ea9dd3,size=11",
        "locationType": "COORDINATE",
        "locationValue": "page=1,x=200,y=400",
        "oneOffTemplate": "Digitally Signed by $certificate.getCommonName().",
        "templateType": "ONE_OFF"
      }

   4. Please check attachment Test_signature_request.txt for a complete request example

2. This configuration will have the following output:

   

Attachments: