DokuWiki

You've loaded an old revision of the document! If you save it, you will create a new version with this data.

==== Web Service: ValidateBase64DocumentChecksum ====

CeRTNA formatted XML transactions contain PRIA_DOCUMENT nodes that contain TIFF documents that are formatted as Base64 character strings.

The ValidateBase64DocumentChecksum is intended to be used by a client (agent and/or county) to verify that a document-level checksum calculated locally matches the document-level checksum that was supplied by the alternate party.

A ‘soft-token’ is required to call the ValidateBase64DocumentChecksum web service. Please refer to the Login web service documentation for additional details.

<color #7092be>Request Endpoint</color>

{{tablelayout?colwidth="100px,500px"&rowsFixed=1&rowsVisible=10&float=center}}
^ Method ^ URL ^
| POST | <nowiki>https://apex-prd.certna.org/ValidateBase64DocumentChecksum</nowiki> |

<color #7092be>Request Body</color>

This endpoint accepts request body parameters using an application/json format.

<color #7092be>Request Headers</color>

{{tablelayout?colwidth="100px,500px"&rowsFixed=1&rowsVisible=10&float=center}}
^ Key ^ Value ^
| Content-Type | application/json |
| access_token | [string] |

<color #7092be>JSON Request Parameters</color>

{{tablelayout?colwidth="100px,75px,125px,75px,200px"&rowsFixed=1&rowsVisible=10&float=center}}
^ Parm Name ^ Req/Opt ^ Allowed Values ^ Default ^ Description ^
| transaction_type | Required | [string] | n/a | Request or Response |
| submitter_id | Required | [numeric] | n/a | Numeric submitter id enclosed in double-quotes. |
| primary_reference | Required | [string] | n/a | Primary reference number. |
| document_order_index | Required | [numeric] | n/a | Document sequence number enclosed in double-quotes. |
| checksum_algorithm | Required | [string] | n/a | Currently supporting SHA384. |
| checksum_value | Required | [string] | n/a | Locally calculated checksum value represented as a Base64 string.
See comments for example of how to calculate a SHA3 checksum and convert it to a Base64 string.
 |

<color #7092be>JSON Response Parameters</color>

{{tablelayout?colwidth="125px,100px,375px"&rowsFixed=1&rowsVisible=10&float=center}}
^ Parm Name ^ Data Type ^ Description ^
| result | [string] | If transaction/document is found <color #7092be>true</color> or <color #7092be>false</color> will be returned. Note: Counties and/or agents may only query transactions/documents associated with their county and/or agent. |
| code | [string] | Exception conditions will result in code/message being returned. |
| message | [string] | Longer description of exception condition. |

As noted, any exception condition, for example, missing soft-token, invalid parameters, etc, will result in a JSON formatted response with a code and message property populated. Successful queries will result in either <color #7092be>true</color> or <color #7092be>false</color> being returned. True means the checksum supplied matches the checksum on file for the requested document.

<color #7092be>Sample Request</color>

**Endpoint:**

<nowiki>https://apex-prd.certna.org/ValidateBase64DocumentChecksum</nowiki>

**Headers:**

Content-Type: application/json \\
access_token: 2fb25264-2739-4db5-895e-db4369256a4a  (sample)

**Body:**

<code json>
{
  "transaction_type" : "Request",
  "submitter_id" : "99",
  "primary_reference" : "SAMPLE-20180816-001",
  "document_order_index" : "3",
  "checksum_algorithm" : "SHA384",
  "checksum_value" : "be+gn1NM+AZQ+8yC1RBpRuiHOZOGYPBSiDHzZw9OFzonaVNOHzob2n6GxArCaojs"
}
</code>

**Sample Response:**

Status Code: 200

or

Status Code: 500  (When an error occurs.)

<code json>
{
    "result": true
}
</code>

or  (example 1)

<code json>
{
    "Exception": {
        "Code": "DatabaseError",
        "Message": "No transaction found"
    }
}
</code>

or  (example 2)

<code json>
{
    "Exception": {
        "Code": "InvalidTransactionStatus",
        "Message": "Invalid transaction type. Alowed values are - Request,Response"
    }
}
</code>

<color #7092be>Additional Comments</color>

Comments and sample code are provided for reference purposes only and are not intended to show all exception handling conditions and/or completed code blocks.

**Comment 1:**

The ValidateBase64DocumentChecksum web service requires a Base64 encoded SHA384 checksum to be provided as one of the parameters.
Following is a C# / .NET sample code snippet that shows how to generate a SHA3 checksum and convert the hash to a Base64 string:

<code C#>
// The following strBase64DocValue value is retrieved from the DOCUMENT child node of the EMBEDDED_FILE node in the XML document.

string strBase64DocValue = " SUkqALLnAAAtVZDKI+R4jhk…";  // Get your Base64 string from the XML doc.

string strBase64HashValue = getBase64Hash(strBase64DocValue);  // Use this value in your web service call

public static string getBase64Hash(string strB64Source)
{
Encoding u8 = Encoding.UTF8; // We use UTF8 encoding

byte[] b64Bytes = u8.GetBytes(strB64Source); // Put the Document B64 string into a byte array

byte[] b64HashBytes = SHA384.Create().ComputeHash(b64Bytes);  // Compute the SHA384 hash

//Convert the SHA384 hash to a Base64 string

string strB64Value = System.Convert.ToBase64String(b64HashBytes, 0, b64HashBytes.Length);

return strB64Value;
}
</code>

**Comment 2:**

Following is a C# / .NET sample code snippet that shows how to call the ValidateBase64DocumentChecksum web service. Your code will supply the values for the various parameters based on the following:

{{tablelayout?colwidth="150px,450px"&rowsFixed=1&rowsVisible=10&float=center}}
^ Parameter ^ Source ^
| strTransactionType | Counties will typically be verifying a Request XML and Agents would typically be verifying a Response XML. |
| strSubmitterID | The _Identifier property in the REQUESTING_PARTY node. |
| strPrimaryRef | The _Value property of the RECORDING_TRANSACTION_IDENTIFIER node. |
| strDocIndex | DocumentSequenceIdentifier property from the PRIA_DOCUMENT node. |
| strAlgorithm | CeRTNA currently is requiring SHA384. |
| strChecksumValue | The value returned by using a function similar to what is shown in Comment1. |

<code C#>
Public static void ValidateBase64DocumentChecksumExample()
{
string strTransactionType = "Request";
string strSubmitterID = "99";
string strPrimaryRef = "SAMPLE-20180816-001";
string strDocIndex = "3";
string strAlgorithm = cbAlgorithm.Text;
string strChecksumValue = tbB64Value.Text;

// The following value was obtained from your call to the Login web service.

string token = "ab34xyz3...";

strURL = null;
client = null;
request = null;
response = null;

strURL = "https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/ValidateBase64DocumentChecksum";

client = new RestClient(strURL);
request = new RestRequest(Method.POST);

string strParms = "{\n\t\"transaction_type\" : \"";
strParms += strTransactionType;
strParms += "\",\n\t\"submitter_id\" : \"";
strParms += strSubmitterID;
strParms += "\",\n\t\"primary_reference\" : \"";
strParms += strPrimaryRef;
strParms += "\",\n\t\"document_order_index\" : \"";
strParms += strDocIndex;
strParms += "\",\n\t\"checksum_algorithm\" : \"";
strParms += strAlgorithm;
strParms += "\",\n\t\"checksum_value\" : \"";
strParms += strChecksumValue;
strParms += "\"\n}";

request.AddHeader("Cache-Control", "no-cache");
request.AddHeader("Content-Type", "application/json");
request.AddHeader("access_token", token);
request.AddParameter("ValidateBase64DocumentChecksum", strParms, ParameterType.RequestBody);

response = client.Execute(request);

if (response.IsSuccessful)
{
var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content);
string strResult = jsonResult2.result;

// Do something with the result.

}
else
{
var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content);
string str_ErrorCode = jsonResult2.ToString();

// Do something with the error result
}
}
</code>

**Comment 3:**

Please note that before calling the CeRTNA web services you must establish the SecurityProtocol in your ServicePointManager. An example is shown below. The currently recommended protocol is Tls12.

<code C#>
public MainWindow()
{
            InitializeComponent();
            System.Net.ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls |
                                                  SecurityProtocolType.Tls11 |
                                                  SecurityProtocolType.Tls12 |
                                                  SecurityProtocolType.Ssl3;
}
</code>

**Comment 4:**

CeRTNA has posted a simple Visual Studio 2015 WPF/C# project the CeRTNA Wiki that demonstrates how to look up values in an XML file and how to use the Login & ValidateBase64DocumentChecksum web services. The project can be downloaded from the Wiki. As stated earlier, the purpose of the code samples is not to demonstrate well structured code, but rather to provide a very simple, functional sample, that you can use for reference in adding CeRTNA web service calls to your existing application. The code sample is provided as is, however, your production code would be expected to contain more extensive error handling, etc.

**Comment 5:**

A nice utility for experimenting with web service calls is POSTMAN. You can download a free version of POSTMAN from the following URL: https://www.getpostman.com/apps

Edit summary

Note: By editing this page you agree to license your content under the following license: CC Attribution-Noncommercial-Share Alike 4.0 International