This is an old revision of the document!
Transaction
The transaction web service is a REST structured service that derives its functionality based on syntax used when calling the web service. There are two parameters required to uniquely identify a transaction, submitter_id and primary_reference. An additional optional parameter can be supplied to instruct the web service to include the transaction history along with the transaction details.
Purpose: Get Transaction Status And History
Request Endpoint
| Method | URL |
|---|---|
| GET | https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/transaction?submitter_id={submitter_id}&primary_reference={primary_reference}&include_history={true or false} |
Arguments:
| Variable | Usage | Description |
|---|---|---|
| {submitter_id} | Required | Submitter ID number. |
| {primary_reference} | Required | Primary_Reference for the transaction. |
| {include_history} | Optional | True or False |
Request Body
N/A
Request Headers
| Key | Value |
|---|---|
| access_token | {soft-token} |
JSON Request Parameters
N/A
Notes:
Any condition that results in an unsuccessful call to the payloads web service will produce a JSON formatted response with a code and message property populated.
Sample Request - No History
Endpoint:
https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/transaction?submitter_id=35&primary_reference=TESTAGENT1-202007140415-00013.1.1
Sample Response
Status Code: 200
{
"result": {
"TRANSACTION_ID": 4256051,
"PRIMARY_REFERENCE": "TESTAGENT1-202007140415-00013.1.1",
"SECONDARY_REFERENCE": "3453453453",
"COUNTY_NAME": "TestCountyCER1",
"SUBMITTER_ID": 35,
"AGENT_ID": 6,
"CREATOR_USER_NAME": "apexsvc65",
"CREATED": "2020-07-23T14:23:56",
"LAST_MODIFIED": "2020-07-23T15:14:46",
"TRANSACTION_STATUS_ID": 32,
"TRANSACTION_STATUS": "Archived"
}
}
OR
Status Code: 500 (When an error occurs.)
{
"Exception": {
"Code": "Undefined",
"Message": "Submitter ID and Primary Reference must not be empty or null."
}
}
Sample Request - With History
Endpoint:
https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/transaction?submitter_id=35&primary_reference=TESTAGENT1-202007140415-00013.1.1&include_history=true
Sample Response
Status Code: 200
{
"result": {
"TRANSACTION_ID": 4256051,
"PRIMARY_REFERENCE": "TESTAGENT1-202007140415-00013.1.1",
"SECONDARY_REFERENCE": "3453453453",
"COUNTY_NAME": "TestCountyCER1",
"SUBMITTER_ID": 35,
"AGENT_ID": 6,
"CREATOR_USER_NAME": "apexsvc65",
"CREATED": "2020-07-23T14:23:56",
"LAST_MODIFIED": "2020-07-23T15:14:46",
"TRANSACTION_STATUS_ID": 32,
"TRANSACTION_STATUS": "Archived",
"TRANSACTION_STATUS_HISTORY": [
{
"TRANSACTION_STATUS_ID": 1,
"TRANSACTION_STATUS": "Draft",
"TIMESTAMP": "2020-07-23T14:23:56"
},
{
"TRANSACTION_STATUS_ID": 128,
"TRANSACTION_STATUS": "Submitting",
"TIMESTAMP": "2020-07-23T14:23:57"
},
{
"TRANSACTION_STATUS_ID": 2,
"TRANSACTION_STATUS": "Submitted",
"TIMESTAMP": "2020-07-23T14:23:58"
},
{
"TRANSACTION_STATUS_ID": 512,
"TRANSACTION_STATUS": "RetrievingByCounty",
"TIMESTAMP": "2020-07-23T14:30:35"
},
{
"TRANSACTION_STATUS_ID": 4,
"TRANSACTION_STATUS": "RetrievedByCounty",
"TIMESTAMP": "2020-07-23T14:30:40"
},
{
"TRANSACTION_STATUS_ID": 2048,
"TRANSACTION_STATUS": "ReturningByCounty",
"TIMESTAMP": "2020-07-23T14:53:31"
},
{
"TRANSACTION_STATUS_ID": 8,
"TRANSACTION_STATUS": "ReturnedByCounty",
"TIMESTAMP": "2020-07-23T14:53:32"
},
{
"TRANSACTION_STATUS_ID": 8192,
"TRANSACTION_STATUS": "RetrievingBySubmitter",
"TIMESTAMP": "2020-07-23T15:14:41"
},
{
"TRANSACTION_STATUS_ID": 32,
"TRANSACTION_STATUS": "Archived",
"TIMESTAMP": "2020-07-23T15:14:46"
}
]
}
}
OR
Status Code: 500 (When an error occurs.)
{
"Exception": {
"Code": "DatabaseError",
"Message": "Not Authorized To Access This Transaction."
}
}
Comment 1:
Following is a C# / .NET sample code snippet that shows how to call the transaction web service. This example shows the syntax for calling the web service with or without transaction history, processing the transaction details that are returned and processing the history records that are returned, if history was requested.
This snippet was derived from Web Service Toolbox that is available on the CeRTNA Wiki. The sample application is intended for easy to read demonstration purposes and not production quality code. The Web Service Toolbox application is documented, on the CeRTNA Wiki, to aid in understanding the code snippet shown below.
private void btnGetStatus_Click(object sender, RoutedEventArgs e) { RestClient client = null; RestRequest request = null; IRestResponse response = null; ResetTransactionPanels(); string strURL = "https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/user/login"; // Password has to be hashed. // New convention uses a Salt value from the user record // See login web service for more detail. string strSalt = GetSalt(tbUserName.Text); string strPassword = tbPassword.Password.ToString(); string strHashedPassword = HashPassword(strPassword, strSalt); string strParms = "{\n\t\"user_name\" : \""; strParms += tbUserName.Text; strParms += "\",\n\t\"password\" : \""; strParms += strHashedPassword; strParms += "\"\n}"; client = new RestClient(strURL); request = new RestRequest(Method.POST); request.AddHeader("Cache-Control", "no-cache"); request.AddHeader("Content-Type", "application/json"); request.AddParameter("Login", strParms, ParameterType.RequestBody); response = client.Execute(request); if (response.IsSuccessful) { var jsonResult1 = JsonConvert.DeserializeObject<dynamic>(response.Content); string token = jsonResult1.access_token; if (chkTransactionHistory.IsChecked == true) { strURL = "https://" + getHost() + "/APEX/Service/APEXPublicServer.svc/transaction?submitter_id=" + tbSubmitterID.Text + "&primary_reference=" + tbPrimaryReference.Text + "&include_history=true"; } else { strURL = "https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/transaction?submitter_id=" + tbSubmitterID.Text + "&primary_reference=" + tbPrimaryReference.Text + "&include_history=false"; } client = new RestClient(strURL); request = new RestRequest(Method.GET); request.AddHeader("Cache-Control", "no-cache"); request.AddHeader("access_token", token); response = client.Execute(request); if (response.IsSuccessful) { if (chkTransactionHistory.IsChecked == true) { panelTranDetails.Visibility = Visibility.Visible; panelTranHistory.Visibility = Visibility.Visible; } else { panelTranDetails.Visibility = Visibility.Visible; panelTranHistory.Visibility = Visibility.Hidden; } var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content); tbTransactionID.Text = jsonResult2.result.TRANSACTION_ID; tbPrimaryRef.Text = jsonResult2.result.PRIMARY_REFERENCE; tbSecondaryRef.Text = jsonResult2.result.SECONDARY_REFERENCE; tbCountyName.Text = jsonResult2.result.COUNTY_NAME; tbSubID.Text = jsonResult2.result.SUBMITTER_ID; tbAgentID.Text = jsonResult2.result.AGENT_ID; tbCreatorUserName.Text = jsonResult2.result.CREATOR_USER_NAME; tbDateCreated.Text = jsonResult2.result.CREATED; tbLastModified.Text = jsonResult2.result.LAST_MODIFIED; tbStatusID.Text = jsonResult2.result.TRANSACTION_STATUS_ID; tbStatusName.Text = jsonResult2.result.TRANSACTION_STATUS; if (chkTransactionHistory.IsChecked == true) { JObject joResponse = JObject.Parse(response.Content); JArray jaHistory = (JArray)joResponse["result"]["TRANSACTION_STATUS_HISTORY"]; // Load the grid historyGrid.Children.Clear(); historyGrid.RowDefinitions.Clear(); historyGrid.RowDefinitions.Add(new RowDefinition()); if (jaHistory.Count == 0) { tbMessageLine.Text = "*** No Transaction History Available ***"; } else { TextBlock[] txtStatusCode = new TextBlock[jaHistory.Count + 1]; TextBlock[] txtStatusName = new TextBlock[jaHistory.Count + 1]; TextBlock[] txtTimeStamp = new TextBlock[jaHistory.Count + 1]; // Header row txtStatusCode[0] = new TextBlock(); txtStatusCode[0].Padding = new Thickness(0, 5, 25, 5); txtStatusCode[0].Text = "Code"; Grid.SetRow(txtStatusCode[0], 0); Grid.SetColumn(txtStatusCode[0], 0); historyGrid.Children.Add(txtStatusCode[0]); txtStatusName[0] = new TextBlock(); txtStatusName[0].Padding = new Thickness(0, 5, 25, 5); txtStatusName[0].Text = "Status"; Grid.SetRow(txtStatusName[0], 0); Grid.SetColumn(txtStatusName[0], 1); historyGrid.Children.Add(txtStatusName[0]); txtTimeStamp[0] = new TextBlock(); txtTimeStamp[0].Padding = new Thickness(0, 5, 25, 5); txtTimeStamp[0].Text = "Timestamp"; Grid.SetRow(txtTimeStamp[0], 0); Grid.SetColumn(txtTimeStamp[0], 2); historyGrid.Children.Add(txtTimeStamp[0]); for (int i = 1; i <= jaHistory.Count; i++) { historyGrid.RowDefinitions.Add(new RowDefinition()); txtStatusCode[i] = new TextBlock(); txtStatusCode[i].Padding = new Thickness(0, 5, 25, 5); txtStatusCode[i].Text = (String)jaHistory[i - 1]["TRANSACTION_STATUS_ID"]; Grid.SetRow(txtStatusCode[i], i); Grid.SetColumn(txtStatusCode[i], 0); historyGrid.Children.Add(txtStatusCode[i]); txtStatusName[i] = new TextBlock(); txtStatusName[i].Padding = new Thickness(0, 5, 25, 5); txtStatusName[i].Text = (String)jaHistory[i - 1]["TRANSACTION_STATUS"]; Grid.SetRow(txtStatusName[i], i); Grid.SetColumn(txtStatusName[i], 1); historyGrid.Children.Add(txtStatusName[i]); txtTimeStamp[i] = new TextBlock(); txtTimeStamp[i].Padding = new Thickness(0, 5, 25, 5); txtTimeStamp[i].Text = (String)jaHistory[i - 1]["TIMESTAMP"]; Grid.SetRow(txtTimeStamp[i], i); Grid.SetColumn(txtTimeStamp[i], 2); historyGrid.Children.Add(txtTimeStamp[i]); } } } } else { var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content); string strMessage = jsonResult2.Exception.Message; tbMessageLine.Text = strMessage; } } else { var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content); tbMessageLine.Text = jsonResult2.ToString(); } return; }