The OnTime SOAP and REST API provide the ability to create, read, and update objects in an OnTime account. The following explains how these operations are carried on in both the OnTime SOAP and REST API.

Data Access in the OnTime SOAP API

Create, Read, and Update Functions

The OnTime SOAP API contains create, read, and update functions for objects in an OnTime account. The following VB.NET code demonstrates how to create a new location using the OnTime SOAP API. Please consult the OnTime SOAP API ASP.NET Guide for more information about the Service and ServiceReference objects.

Dim location As New ServiceReference.Location
location.AddressLine1 = "123 Business Park Dr"
location.City = "Medford"
location.State = "OR"
location.PostalCode = "97504"
location.Phone = "555-123-9876"
location.CompanyName = "Ben's Auto Parts"
location.ContactName = "Ben"
location.Email = "ben@example.com"
Dim returnedLocation As ServiceReference.Location = Service.CreateLocation(location)

Notice that the function CreateLocation is called. This function will add or update the location that is passed to it, and return the created or updated location. The next example demonstrates how to get an order with a specific tracking number, update the order's weight and dimensions, and persisting the changes to the database.

Dim order As ServiceReference.Order = Service.GetOrderListWhere(ServiceReference.OrderColumn.TrackingNumber, "4478").FirstOrDefault()
If order IsNot Nothing Then
     order.Weight = 100.0
     order.Width = 10
     order.Length = 7.5
     order.Height = 2.3
     Dim returnedOrder As ServiceReference.Order = Service.UpdateOrder(order)
End If

The previous example uses the GetOrderListWhere function to find an order by tracking number. An order can also be retrieved if the Guid that identifies the order in the database is known. For example, an order can be retrieved with the following VB.NET code.

Dim order As ServiceReference.Order = Service.GetOrder(New Guid("dacb41f8-6e11-441f-89f3-9b357bdb74f4"))

Extra Functions

Aside from the standard create, read, and update functions illustrated in the previous section, there are extra functions that provide specialized functionality. These functions have the following signatures.

Function UpdateOrderPrices(order As Guid) As Boolean
Function GetOrderTotalCost(order As OnTime.Online.API.Order) As Decimal
Function UpdateOrderSignatureRequirement(trackingNumber As String, requireCollectionSignature As Boolean, requireDeliverySignature As Boolean) As Boolean
Function UpdateOrderCODRequirement(trackingNumber As String, amountToCollect As Decimal, requireCollectionCOD As Boolean, requireDeliveryCOD As Boolean) As Boolean
Function GetOrderFileAttachmentList(trackingNumber As String) As List(Of Guid)
Function CreateFileAttachmentProxy(fileName As String, contents As Byte()) As OnTime.Online.API.Order.FileAttachment
Function GetOrderSignature(trackingNumber As String, signatureLocation As OnTime.Extensions.SDK.OrderBase.SignatureTypes) As Byte()
Function UpdateOrderStatus(ByVal trackingNumber As String, ByVal statusLabel As String, ByVal statusDetail As Status.OrderStatusBase, ByVal statusDate As Date) As Boolean
Function UpdateUserPosition(userID As Guid, latitude As Decimal, logitude As Decimal, timeStamp As Date) As Boolean
Function GetUserPosition(userID As Guid, startDate As Date, endDate As Date) As List(Of OnTime.Online.API.User.UserPosition)
Function AuthenticateUser(userName As String, password As String) As Guid?
Function AuthenticateCustomer(userName As String, password As String) As Guid?
Function AuthenticateContact(userName As String, password As String) As Guid?

You may find more information about these specialized functions by vieweing the documentation for the OnTime SOAP API Functions.

Data Access in the OnTime REST API

Create, Read, and Update Functions

The OnTime REST API contains endpoints that allow for the creating, reading, and updating of objects in an OnTime account. The following is an example of an HTTP request and response to create a new location using the OnTime REST API. Notice that there is no value supplied for the ID property of the location. This is because the OnTime REST API will automatically generate an identifier for the new location and return it in the response.

POST /api/location/post HTTP/1.1
Host: www.example.com
Authorization: YOUR-API-KEY
Content-Type: application/json
Cache-Control: no-cache
{
    "ContactName": "Ben",
    "CompanyName": "Ben's Auto Parts",
    "AddressLine1": "123 Business Park Dr",
    "City": "Medford",
    "State": "OR",
    "PostalCode": "97504",
    "Email": "ben@example.com",
    "Phone": "555-123-9876"
}

The previous HTTP request will return the following JSON object.

{
    "Zone": null,
    "ID": "fb573fac-8a10-47ba-aa60-f1c4159cad92",
    "ContactName": "Ben",
    "CompanyName": "Ben's Auto Parts",
    "AddressLine1": "123 Business Park Dr",
    "AddressLine2": "",
    "City": "Medford",
    "State": "OR",
    "PostalCode": "97504",
    "Country": "",
    "Comments": "",
    "Email": "ben@example.com",
    "Phone": "555-123-9876",
    "Category": "",
    "LatitudeLongitude": ""
}

Objects can be retrieved through the OnTime REST API through a number of endpoints. The following is an example of an HTTP request that will retrieve an order by its identifier. An explanation of query and filtering for object identifiers is explained in the article Querying and Filtering of Object Identifiers.

GET /api/orders/5e230ce1-6fd3-4186-9949-969b4d67fba2 HTTP/1.1
Host: www.example.com
Authorization: YOUR-API-KEY
Content-Type: application/json
Cache-Control: no-cache

Automatic Number Generation

The OnTime SOAP and REST API allow for the automatic generation of order tracking numbers and customer account numbers. In order for the OnTime SOAP and REST API to generate these numbers automatically, the proper settings must be configured in OnTime Management Suite. If the proper settings have been configured, then tracking numbers and customer account numbers will be automatically generated if the TrackingNumber or AccountNumber property on the order or customer being created is null or an empty string.