Keypoints
- This tutorial introduces the basics of using the Lobo API for creating orders through Postman, a popular API development and testing tool.
- It guides users on how to obtain an API key, set up authentication, and use specific API endpoints to manage product orders and customer interactions.
- Additionally, the tutorial covers the process of verifying addresses, creating orders with specified customer and product details, and setting up webhooks for receiving updates on order dispatch events.
- Links:
- Official documentation: https://api.lobo.at
- Postman (Download): https://www.postman.com/downloads/
Transcript
Hello and welcome to this quick start on how to use the Lobo API. For this tutorial you will need Postman. It’s a software for API development and testing. You could of course use any other API dev software. You most probably have already received the link to our official documentation api.lobo.at where you can find all the details and you should have received a collection of endpoints for Postman and that we will use in this tutorial to go through of the t ypical use case of creating an order.
And finally, you should have also received an API key which consists of a URL and the username and password. These were created within our backend via system API dashboard. You don’t have access to this. This is only accessible for the courier service and there they can create new API keys, or in our case we have already prepared one and they can set all the scopes that you can access, the valid E-password, etc..
But let’s get started with the fun part. I switched back to Postman. I’ve loaded the examples that you should have received already. And what I did, I created an environment where I saved all the success data, name, username, password, and so on to speed up this tutorial. Of course, you can enter this information manually.
Let’s open the token root. This is the basic route to get access to all the other endpoints. You need your username, your API username and your API password here. You already see I’ve masked them with variables. And you should have received this URL. again, you notice the URL here that you can enter manually.
So let’s get us a token. It’s a POST request and we get back this token that you need to use for the authentication of the other routes. I actually just opened the next route, which is products. I’m interested in which products I can order. Last time it’s a bearer authentication. So you should put the bearer token here.
In my case, it’s a variable content, so I don’t need to make this manually. If I click send, I received a list of products that I can order. I remember for our example, the ID one, which is the bike product in this case that I will use later. Next, I query the customers actually, as you’ve seen before, this API key is limited to this customer number.
So there’s only one hit. And again, I will remember this values because I need it later. To simplify the process of address search, actually the API expects a well structured format of the addresses. We provide an endpoint that parses the address. So in our case, in this address, autocomplete streets route, I put the query string to a special address Markgasse 37 in Wien, and if I click send, you’ll see that the address will be parsed into different fields, namely: street, house number or city.
And enter or actually I’ve prepared it, entered the result of the autocomplete here. So I put here the Marktgasse which is the street name, the house number and the city, Vienna here. And here I can see if the address really exists in Lobo. I’ll check and yes, it’s there. Let’s do something nasty and enter an address that doesn’t exist for sure in Vienna at least.
And in this case, the verify route returns a zero result because we couldn’t GEO locate this address. Okay, so up to now, we know which products we can order, we have a customer number, and we have a verified address. So let’s do or create an order. You find this example also in the API docs.
I’ve al ready prepared some structure that we will fill in right now. So what we need, we need the customer number. You remember, we got this from this route. So this is our customer number. Actually, if you make an API client for just one customer, you can even hard code this customer number.
Then we need a product ID for fkproduct. This is explained in very detail in the API. We get this number from a product route and we want to order by product. So we use the number one here. Actually, this field is reserved for you. You can save information there that is associated with your database.
It’s optional. You can also leave it blank or omit it. And then we have an array of stops. And what you can do here is different things. First of first of all, if we want to start at the customer, so maybe let’s leave the notepublic. So I assume that I want to start at groupnet. That’s the address we queried here.
I can use this fkplace to directly identify this place. So this would be a pickup at the customer’s address or alternatively, we remember that we’ve just queried in the address Marktgasse 37 that’s where the the order should go to, so the second stop, the drop off will have the Marktgasse 37 in 1090 Wien and there’s, yeah, maybe just in short note, and we also need a contact.
And let’s see. Say, we want to contact Martin there. So basically this should be, should it. So I click send and what I receive is a response of about the details. By the way, you typically can’t access the backend, but for a dispatches, this would mean that they have this new order here and there. Dispatching software Lobo and we’ll be able to dispatch this. By the way, of course, this is not mandatory to verify the addresses before, it’s just optional.
So we could make another order where we go into Marktgasse 15 and click send and create a second order. What happens if I do an address that doesn’t exist, I’ll get an error message that there wasn’t, yeah, that this address could not be found. So if you just want to push orders to your local messenger partner, that’s it.
If you want to also receive updates, you can use our webhooks. So there is a get request on the webhook events where you can see what events are available. Probably we want to listen to the dispatch event. So what we would need is to register a webhook. Let’s see if there are any registered at the moment.
No. So I will use this post request to register for one. Okay. Here’s the stops visited or signed, but I will change this to the dispatch events, wherever. An order is dispatched, I want to be notified on this URL. So that’s your URL, the endpoint for your web hook. You could even add additional parameters to this web hook.
The, the standard parameters that are automatically sent by Lobo are explained in the API, so as soon as I register…okay, that’s interesting. Expired token, we have to refresh because a token is already more than 10 minutes old. I will refresh my token as you know, it’s in the background in a variable, so I can just hit send again. I’ve got an error most probably because I’ve misspelled the event.
Let’s look it up here It’s called dispatched and not dispatch so , as soon as I register this web hook, I have a web hook. So what happens now is that whenever an order is dispatched to a courier, this web hook will be triggered and you get a push notification on this specific URL. And of course can then query the actual status why the orders get grouped.
So I hope I could give you a quick overview on how to get started with Lobo API. You find all the details about the documentation here and all the available routes and we wish you happy coding. See you soon. Bye.