Signature on every page

Hi Tejaswi,

You are seeing this error because you've put two signatures under the same "appoval". Approval represents signature in OneSpan Sign, so should be one to one mapping.

I've adjusted your JSON and this should creates you a package, where the capture signature is put at the page where the "Signature:" text anchor appears, and for the initial signature, I temporary put it at the second page.

So to further solve your requirement, if you already knows the exact pages of your document and the page number where the capture signature appears, you can build a complete JSON and upload the document in one API call.

Otherwise if you can modify the document content. I saw you are using text anchor to locate the capture signature. Actually text tags feature (guide here) is a better way to facilitate these use cases where the page number is dynamic. You can put text tags wherever you needs a capture/initials without building a complex JSON.

At the end, if you don't have any control to the document content, you may have to invoke additional APIs:

(1)first call uploads the document and extracts the capture signature 

(2)do a GET call to pull the document JSON, where you will get the page number of your documents and the page number where the capture signature locates

(3)build a complete JSON on top of the response, and update multiple approvals by API:
PUT /api/packages/{packageId}/documents/{documentId}/approvals

this API accepts an approval array which references the "documents" array > "approvals" array, in a package JSON. So you essentially just need to add initial nodes to the array, according to the document page number and avoiding the page where capture appears.

But still, the text tags feature might be a better solution in this use case.

Duo

Hi Duo

thanks for the reply.

I made the changes according to JSON provided by you and it works fine.

I may have found a label/text (company name)that appears on every page of the document and using the extract anchor method, positioning the signature field. But, the field appears only on 1st page. although, I have not mentioned the page no.

Currently the document which i am using for testing purpose consists of 2 pages. The 1st page should have the capture signature field(which is working fine) and both the pages should have initials at the bottomleft but only on the 1st page initials filed is appearing.

PFA screenshots. Red region is the anchor point for initials field.

JSON:

"documents": [
{
  "name": "Document name",
  "description": "Pdf File",
  "approvals": [
    {
      "fields": [
        {
          "value": "Tejaswi P",
          "name": "Tejaswi P",
          "type": "SIGNATURE",
          "id": "Tejaswi P",
          "page": 0,
          "left": 0,
          "extractAnchor": {
            "topOffset": 100,
            "characterIndex": 3,
            "anchorPoint": "BOTTOMLEFT",
            "index": 0,
            "text": "Signature:",
            "width": 200,
            "height": 50,
            "leftOffset": 20
          },
          "extract": false,
          "subtype": "CAPTURE",
          "width": 0,
          "top": 0,
          "height": 0
        }
      ],
      "role": "role1",
      "optional": false,
      "enforceCaptureSignature": true,
    },
    {
      "fields": [
        {
          "value": "Tejaswi P",
          "name": "Tejaswi P",
          "type": "SIGNATURE",
          "id": "Teja P",
          "left": 0,
          "extractAnchor": {
            "topOffset": -50,
            "characterIndex": 0,
            "anchorPoint": "TOPLEFT",
            "index": 0,
            "text": "Company Name:",
            "width": 200,
            "height": 50,
            "leftOffset": 0
          },
          "extract": false,
          "subtype": "CAPTURE",
          "top": 0
        }
      ],
      "role": "role1",
      "optional": false
    }
  ]
}
]

Hi Tejaswi,

Please note that the "index" refers to the number of occurrence that the text anchor appears in all pages. So if you set as 0, it only assotiates to the text anchor on the first page, not on every pages.

          "extractAnchor": {
            "topOffset": 100,
            "characterIndex": 3,
            "anchorPoint": "BOTTOMLEFT",
            "index": 0,
            "text": "Signature:",
            "width": 200,
            "height": 50,
            "leftOffset": 20
          }

So as I stated above, if you can't modify the PDF content at all to apply text tags, you can try upload the document with capture signature only. And retrieve the package JSON (GET /api/packages/{packageId}), the page number and the page sizes are recorded at "documents" array > "pages" array. Then you can create other initials at a separate API call.

Duo  

Hi Duo,

If I get the total no. of pages and the page no. on which capture signature exists, how this detail will be used in the initials (signature field)block of JSON?

Hi Tejaswi,

Once you know the total number and the number where capture exists, because the initials has a fixed position at bottom left, you actually don't have to use text anchors, but the x/y coordinates instead, so that you can specify the "page" explicitly like:
 

      "approvals": [
        {
          "fields": [
            {
            
              "name": "initials1",
              "type": "SIGNATURE",
              "id": "initials1",
              "page": 0,
              "left": 50,
              "extract": false,
              "subtype": "INITIALS",
              "width": 150,
              "top": 900,
              "height": 50
            }
          ],
          "role": "role1",
          "optional": false
        }
      ]

Or if you still use the text anchor, skip the page number of capture in "index".

          "extractAnchor": {
            "topOffset": 100,
            "characterIndex": 3,
            "anchorPoint": "BOTTOMLEFT",
            "index": 0,
            "text": "Signature:",
            "width": 200,
            "height": 50,
            "leftOffset": 20
          }

Duo

Hi Duo,

Thanks.

Using the x/y co-ordinates and specifying the "page", will the initial field appear on every page of the document? I didn't quite understand this.

If I specified the page no. as 5 ("page": 5), then the initials field will appear only on page 5 of the document, right?
 

I tried the text tags feature. It works fine and is a lot easier. I added the text tag in the footer section of PDF, as I want the initials field on every page of the document.

For e.g. the document is of 17 pages. On all 17 pages initials field is present.

But on 16th page capture signature is present. So I don't require initials field on this page. Is this possible?

"Using the x/y co-ordinates and specifying the "page", will the initial field appear on every page of the document?"

No, it won't add to all pages automatically, but since your application has the control to build the JSON, you can build the array accordingly. For example, if you have 5 pages, and capture on the third page, so you'll have an "approvals" array of 5 nodes, number 1,2,4,5 with x/y coordinates, the third with text anchor

"on 16th page capture signature is present. So I don't require initials field on this page. Is this possible?"

You need to manually exclude the text tags of initials on the 16th page. Or, you can give each initials a field ID/name (use the text tags syntax to specify) and delete the 16th initials afterwards.

Duo

Or, you can give each initials a field ID/name (use the text tags syntax to specify) and delete the 16th initials afterwards.

Are you referring to manually delete the initials? Is there any other way other than manual deletion? 

Hi Duo,

I extracted the page no., where capture field is present, from the documents json response. 

But I was unable to find the total no. pages in the response.  Can you please help on how to extract the total no. of pages?

Hi Tejaswi,

Check the "documents" array > "pages" array, the size of the pages array represnts the total page number.

Duo

Yes. I found the pages array. But there is no id in this. 

I have extracted this array manually using url : https://sandbox.esignlive.com/api/packages/{package_id}/?key={api_key}

"pages":[{"id":"","top":0.0,"width":1096.0,"height":1548.0,"left":0.0,"index":0,"version":0},{"id":"","top":0.0,"width":1096.0,"height":1548.0,"left":0.0,"index":1,"version":0},{"id":"","top":0.0,"width":1096.0,"height":1548.0,"left":0.0,"index":2,"version":0},{"id":"","top":0.0,"width":1096.0,"height":1548.0,"left":0.0,"index":3,"version":0},{"id":"","top":0.0,"width":1096.0,"height":1548.0,"left":0.0,"index":4,"version":0},{"id":"","top":0.0,"width":1096.0,"height":1548.0,"left":0.0,"index":5,"version":0},{"id":"","top":0.0,"width":1096.0,"height":1548.0,"left":0.0,"index":6,"version":0},{"id":"","top":0.0,"width":1096.0,"height":1548.0,"left":0.0,"index":7,"version":0},{"id":"","top":0.0,"width":1096.0,"height":1548.0,"left":0.0,"index":8,"version":0}]
 

Is there a way to only retrieve the pages array? 

I tried extracting the documents array. But it shows error :{"messageKey":"error.forbidden.signing.userSigningOrderViolation","code":403,"message":"User signing order has been violated.","name":"Access Denied"}

url: https://sandbox.esignlive.com/api/packages/{package_id}/documents/{document_id}?key={api_key}

Hi Tejaswi,

It's the same at my end that all page ids are empty strings, I assumed that it's not a problem since you don't need the ID to identify the page number, only the "index" matters.

For other API options, GET /api/packages/{packageId}/documents/{documentId} could give you more granular information:

(1)I can't reproduce the "403 violate signing order" error, and from the error description, it seems not relate to a GET call, more like from a bulk sign call.

(2)The "pages" array should also be returned at the documents json response, where you get the page number of capture. So essentially no need to invoke an extra API.

Duo

Can you please explain in detail the 1st point?

Running the below code for GET request, getting the same error -{"messageKey":"error.forbidden.signing.userSigningOrderViolation","code":403,"message":"User signing order has been violated.","name":"Access Denied"}

DECLARE  
  l_cert_path varchar2(240):= file:C:\wallet5;--
  api_url constant varchar2(240) := 'https://sandbox.esignlive.com/api/packages/packge_id/documents/document_id';
  api_key constant varchar2(240) := 'api_key';
  l_api_key varchar2(240) := 'Basic '||api_key;

  l_http_request utl_http.req;
  l_http_response utl_http.resp;
 
begim
 utl_http.set_wallet('file:C:\wallet5', 'Pwd');
 l_http_request := utl_http.begin_request(
                      url => api_url ,
                      method => 'GET',
                      http_version => 'HTTP/1.1'
                    );
  utl_http.set_header(l_http_request, 'Authorization', 'Basic ' || l_api_key); 
  utl_http.set_header(l_http_request, 'Accept', 'application/json');

  l_http_response := utl_http.get_response(l_http_request);
  dbms_output.put_line('Response> Status Code: ' || l_http_response.status_code);
  dbms_output.put_line('Response> Reason Phrase: ' || l_http_response.reason_phrase);
  dbms_output.put_line('Response> HTTP Version: ' || l_http_response.http_version);
 
  for i in 1 .. utl_http.get_header_count(l_http_response) loop
    utl_http.get_header(l_http_response, i, l_response_header_name, l_response_header_value);
    dbms_output.put_line('Response> ' || l_response_header_name || ': ' || l_response_header_value);
  end loop;
 
  utl_http.read_text(l_http_response, l_response_body, 32767);
  dbms_output.put_line('Response body>');
  dbms_output.put_line(l_response_body);
 
  if l_http_request.private_hndl is not null then
    utl_http.end_request(l_http_request);
  end if;
 
  if l_http_response.private_hndl is not null then
    utl_http.end_response(l_http_response);
  end if;
exception
  when others then
    if l_http_request.private_hndl is not null then
      utl_http.end_request(l_http_request);
    end if;
 
    if l_http_response.private_hndl is not null then
      utl_http.end_response(l_http_response);
    end if;
 
END:

Is it possible to delete the initials field via DELETE request?

If yes, how the json format should be passed?

Hi Tejaswi,

Yes, it's possible to delete a field, simply do:
DELETE /api/packages/{packageId}/documents/{documentId}/approvals/{approvalId}

Duo

Hi Duo,

If I mention the field name in text tags - {{esl_app1:role1:initials}}, the integration program goes into error as Status code 500 unhandled server error.

As per the text tags extraction syntax ,its correct. Then why am I getting the error?

In approvals array for initials field, can we pass page value as mentioned below?

"approvals": [
        {
          "fields": [
            {
            
              "name": "initials1",
              "type": "SIGNATURE",
              "id": "initials1",
              "page": [0,1,2,3,4,5],
              "left": 50,
              "extract": false,
              "subtype": "INITIALS",
              "width": 150,
              "top": 900,
              "height": 50
            }
          ],
          "role": "role1",
          "optional": false
        }
      ]