Transcript
In this video, we're going to talk about how to make use of the OnTime online API that's available as a SOAP-based XML Web Service. We're going to make use of Visual Studio in order to show how we can integrate OnTime with other systems and applications online and in real-time. That affects the desktop software, as well.
To do this, I'm going to show you the endpoints and how we can discover those. You may need to contact Customer Support if you'd like to get the exact URL, but oftentimes you'll know that the OnTime API is an extension to your Enterprise subscription and the Customer Web Portal. I'm going to bring up one of those endpoints, Orders.asmx. As we look at this, it's a very simple service. It gives methods for being able to create an order and gives status on a current order. This is a very safe endpoint to give out to customers or other third party partners that need to integrate with you in some aspect. For instance, a customer may need to be able to send over delivery and pick up orders every day and this is a safe and easy way to do this through the API.
Another endpoint is orders_internal.asmx. As you can see, that includes many more different methods that are a little closer to your company records, allows the person to put in information, pull out information, and make changes to orders. So, this particular endpoint is reserved for tighter integration when you really trust the other system or partner. What we discuss here has also been secured, so it is all being done through SSL encryption. In addition to that, you can employ keys that will further control access to these particular endpoints and methods.
That's what the endpoints look like. Now let's see how we might integrate that API with another application. I'll start Visual Studio 2013. We'll create a new project and, for demonstration purposes, I'm going to use a Windows Forms Application. This is going to very basic, easy to understand view of an application. You can use these same techniques in virtually any other .NET application, console applications, WPF, Windows Story applications, mobile applications, it really doesn't matter. You can also use this online API connection with virtually any other programming language, including Javascript and PHP, because we built on open standards.
In this example, though, we'll use the Windows Form Application. That will be created for us and we see our form here. What I'm going to do in this example is demonstrate getting the status on an order that's already in the system. To do that, I'm going to drop in a button, a label, and a text box. I'll lay these out and "Tracking Number" will be the label. That will go right above the text box, so the user will put the number in that box. And then we'll put the caption on the button as "Get Status." The expection is going to be, when we run this, we'll get whatever tracking number in there submitted to the API and the API will give us back the status of the order in question.
Let's go ahead and get this hooked up to the API. To do that, I'll go to my Solution Explorer in Visual Studio, right-click on the project name, and choose Add Service Reference. I'll click on Advanced, Add Web Reference, and put in the URL to the endpoint. It's going to find it, so I will give this a name. I'll call it "OrdersAPI" and add the reference. Visual Studio then made the connection between the OnTime API and this little application, it's ready to go. Now let's hook up the button so that when a user clicks it, it connects to the API and does what it's supposed to do. I'll double-click the button to go into the code view. The first thing to do in Visual Basic is set an instance to this API, so I'll type in:
Dim myAPI As New Orders.API.OnTimeOrders.
That declares the new instance and now we're ready to use that API:
myAPI.GetStatus()
When we start to enter the parameters, notice how Visual Studio has been given the information to display what is necessary. So, we fully support IntelliSense in this way. We'll say that it needs an account number, as well as a tracking number. The account number represents the customer's account. That prevents just any customer from getting tracking number results; they have to have a valid acocunt number. I'll leave that blank for now. We also need to feed in the tracking number. That's gonna come from the text box that we put on the form. Let's go over to Management Suite really quick and find a customer. I'll use DS Labs and it looks like their account number is 123456. I'm going to copy this and put that as the customer number:
myAPI.GetStatus("123456", TextBox1.Text)
That means, when I call this, not only does the customer account number need to match up, but it has to be on the order that I'm querying as well. This prevents me, as a customer, from getting the status on orders that do not belong to me. Let me display this in a text box, so we're going to say:
Dim result = myAPI.GetStatus("123456", TextBox1.Text)
And then in a message box, we will display what the results are:
MsgBox(result)
That's all the code we need. Let's run our application and see what happens. We'll put in a random tracking number and notice that we get "-1" in response. That's the API's way of saying it's an invalid response: there's no information to be had about this because it's either not a valid tracking number or it's not a tracking number that belongs to me, as the customer I specified. To test this out, let's get a valid tracking number. I'll go back into Management Suite and search for orders that I have set to this particular customer. I'll get the tracking number off of one and notice what the current status is: this says it's in the Submitted state. Let's see what happens when we put this into our application. Now we get a "1" back. What does the 1 mean? If we look at documentation in the endpoint, we see that this GetStatus method is coming back with numbers that represent what the current status is. The 0 or the 1 can mean that the order is in the Submitted state. Just to verify that, let's go back to OnTime Management Suite and manually change the status to In Transit. When I do that, I will notice that if I hit Get Status, the result changes to "2," so the number is changing.
Something I can do in my program to make this a little more user friendly is change what the result appears to be:
Dim statusName As String
Select Case result
Case 0, 1
statusName = "Submitted"
Case 2
statusName = "In Route"
End Select
And change "MsgBox(result)" to:
MsgBox(statusName)
Now, let's run our application and see the results. I'll go back to Management to copy that tracking number again. We'll paste in the tracking number, Get Status, and now we're showing "In Route." So, we see how we can start to manipulate the API in the way that we need to.
Let's tap into that other endpoint, orders_internal. I'll go back to my browser, copy that endpoint, and, in my Solution Explorer, Add a New Service Reference. We will reference this one as "OrdersInternalAPI." Now we have referenced both services in our project. Let's make a slight change here. Beside Get Status, let's drop in another button that we'll call "Get Order as XML." This is going to bring back all of the details of an order in XML format so that my third party program or system can parse that and do a lot with that information. I want to make a reference for this button:
Dim myAPI As New OrdersInternalAPI.orders_internal
myAPI.GetOrderAsXML
In this case, we just need to pass two things: a security key and a tracking number. We'll leave the security key blank for just a moment and reference the textbox for the tracking number. When it's done, we'll put the results of this into a variable and display that in a message box. Now this security key, what is it and where does it come from? If we go back to the Management Suite, we'll notice in General Options, Connections, that there's a section for the API here. As an administrator of your account, you can decide to allow anonymous access to these APIs. We strongly suggest that you do not allow anonymous access because, if you do, anybody that found out about your API could tap into those. By default, OnTime accounts have this API locked down to anonymous access and only people with keys can access these successfully. As you can see, we have a series of keys and you can have as many as you need. We recommend creating a new key for each customer that has potential access to the API. That way everybody has their own and, if you are no longer working with a partner, you can de-activate or remove just their key without disrupting anyone else. In this case, I have anonymous access turned off, which is good, and I've got a series of keys. Let me use the Test key, so I'll double-click on it and copy the key. I'll go back to the application and put that in as the key being used:
Dim results As String = myAPI.GetOrderAsXML("KEY", TextBox1.Text)
MsgBox(results)
Incidentally, OnTime tracks and logs all key activity. If there is a problem with someone abusing the API, we can know who is doing that, what IP address is being used, and what key is being used, so that we can alert you to that problem.
This should be good to go, so let me run our application. We'll grab the tracking number that we were working with earlier. Try Get Status again and it still says In Route. If we choose Get Order As XML, that work, as well. You can seean XML representation of all of the data in that particular order. There is a lot of information there that we can parse and use.
Those sare just two brief examples of how to tap into two API endpoints, to make calls using Visual Studio (in this case), and to start integrating them with our applications. Of course, with these methods you can both read information and put information into OnTime. Explore those endpoints to do what you need to do to make your system communicate effectively with OnTime. I hope this has been of benefit to you. We appreciate you using OnTime courier software. If you having any questions about how to use the API or any details, please feel free to contact the Customer Support team and they will be glad to help you. Thank you.