Logistra Cargonizer API
Cargonizer API "One on one"
Grab a cup of coffee, a box of redbull, a cup of tea, or what ever gets you in the swing for understanding our API and let's get to it. We assume you have browsed through our API documentation so that you have the general idea, so we'll here describe more in detail what the specifics are, and why they are as they are.
We'll also try to give our opinion on what's the best practise in order to most efficiently use our API, but there's no way we can know what's the absolute best approach for your part, so even though it's a lengthy read, read through it and then decide for yourself if this is the optimal approach for your part. Worst case scenario is that you might have picked up a few "aha moments" that might be useful in your own module.
Contents and the very first initial work path
1) Get the available senders for your API key
2) Get the available online printers for your API key
3) Get available carriers for your API key and Sender ID combination
4) Generate a first simple shipment
5) Make a link to the xml response
6) Understand and handle the xml response
7) Print the shipping label
8) Adding more information to the shipment
8a) Complete the consignee information
8b) Add a return address
8c) Transfer the shipment to the carrier
8d) Add weight, volume and a description of the package
8e) Add a senders reference
8f) Add a service partner/pickup point if needed
8g) Add additional services
8h) Book a pickup with the carrier
9) End notes
Alrite, let's go!
1) Obtain the available senders for your API key
Requirements: Api key
When receiving an API key from a Cargonizer user, the first you should do is to obtain what Cargonizer senders this API key can administer. A "sender" is the company that ships the packages. This is done by sending a request to our webservice profile.xml which will return available senders for this API key, meaning; one api key can administer several senders in Cargonizer.
The Sender ID is found in the following path of your xml response:
Both API key and chosen Sender ID (Yes, "Managership ID" would be a better term, but as years have passed, "Sender ID" has become the common definition so we're sticking to the term.) should be stored, as both of these are required for most of our other webservices.
So the first step would be to give your users a settings page, where they can paste their API key from Cargonizer. You will then do the profile.xml request and present the different senders the api key can use, perhaps in a drop down box, and make the user pick one of them so you have a valid link between an api key and a sender ID (Managership ID) stored.
Tip; The xml response also include information about the subscription the user has in Cargonizer. As the subscriptions are based on a set number of collis (packages) the user will experience a stop if a subscription plan has reached it's limit. With the response from profile.xml you can present a note to the user if the plan has reached it's limit, or present a note if the user is closing in on it's subscription, giving them time to upgrade their subscription before a stop happens.
2) Obtain available online label printers, if any, for your API key
Requirements: Api key, DirectPrint
Through our DirectPrint functionality (Link in Norwegian only unfortunately) you can have full control over the label prints of the user, but in order to do so you will need to obtain the available printer ID's of your API key. This is done by sending a request to our webservice printers.xml, which will return available printers for your API key.
The printer ID's should be stored, as well as the description of the printers.
Note: DirectPrint is a physical computer, a RaspberryPi, connected between the label printer and internet. The majority of our customers has such a DirectPrint, but there are also many that don't. These will have to print the label through a downloaded pdf file of the label.
If DirectPrint is not connected to a network with a valid internet connection, it will not show up in your response. Do therefore not make this a requirement for your customers, give them the possibility to chose "Manual print", as well as the available online DirectPrints, in your setup. If your customer has chosen "Manual print" you will not send the print request later on.
3) Obtain available carriers, products and services for your API key
Requirements: Api key, Sender ID
A Cargonizer user can potentially have hundreds of different carriers available on his/hers account, and even several different agreements with the same carrier, but most users only have two or three different carriers available. All carriers have different products (freight methods) and within those products, most carriers also have additional services.
To obtain what available carriers, and transport agreements, the user has in Cargonizer you send a request to our transport_agreements.xml webservice using the API key and Sender ID.
This will give you a relatively large xml response from our API, depending on the number of carriers the user has available in his/hers Cargonizer account.
From the xml response, make sure to store the transport agreement id (There are several agreements), as well as the description of the agreement, the carrier name and also all product names for future use/mapping in your system.
The rest of the response contains all available rules of each product, such as maximum and minimum weight, if any, what countries one are allowed to send the package to as well as other carrier decided rules that might apply to the package. It also contains information on all available additional services that might be applied to the product. Many senders want to use some additional services applied to some products, so it's advisable to also store the available additional services that are found in this path:
More on how to add additional services later on.
Note on service partners/pickup points:
Some carriers have products that require pickup points, which are places where the end customer goes to pickup his/hers package. Weather or not a carrier product require such a pickup point added to the consignment (shipment) is found in the following path of the xml response:
This is a true/false segment, and if true, you will also have to add a service-partner part on your shipment.
More on this deal later, but take this path into notice for future use. If it's "true" you will need to make a second request and use that response when generating your shipment.
4) Generating the very first shipment, and keeping it simple for now
Requirements: Api key, Sender ID, transport agreement ID, product id
Now you should have all thats needed in order to generate your first shipment through our API. Generating a shipment is done by sending consignments.xml to our endppoint https://cargonizer.no.
Here is a step by step guide on how the consignments.xml file is built, starting with describing an absolute minimal example of such a xml:
<consignments> <consignment transport_agreement="12345" print="false">
This ID is obtained through our webservice transport_agreements.xml. The ID is unique for each sender. The print reference is needed in order to later control the print of the label. Automatic printing through consignments.xml will also be discontinued in a future update, so do not build an integration that relies on the feature of controlling the print through true or false here. Build it like it should, with our printers.xml webservice in mind instead.
This ID is obtained through our webservice transport_agreements.xml
A shipment can consist of many parts, the end customer is one, the return address is another, the pickup address might be a third, and the pickup point might be a fourth. And there are even more of them, but in the <parts> element you will define each one of them. For now, we'll just add the end customer part, the "consignee", but later on we'll explain how to add a pickup point for those freight products that require a "service partner".
A "Consignee" is the end customer, in other words where the package will be delivered unless specified in a different part. As this is a very minimalistic example it will for the purpose of this explanation not contain all fields that ususally is wanted on a shipment. Later on in this walk-through we'll give you a full set of standard elements to use in the consignee part, but if you wan't to add the rest right away, head on down here to grab the other elements: Complete the consignee information
<name>Juan Ponce de Leon</name>
Note: Again; this is a bare minimum of what is needed for a consignee, but in all cases regarding normal shipments, you would want to add more elements to the conisgnee, such as the street address. So if you want to add everything right away, just do it. More information on the different elements in the consignee part is found here.
Here you add what it is that's sent. You can add several <item> parts, defining each one, or you can add them all together in one <item> where amount is the number of packages sent. In the below example we send 2 packages with a total weight of 10 kg. The result will be two packages, each weighing 5 kg, but again, this could also have been added in two separate <item> elements if you want to better define each package.
<item type="package" amount="2" weight="10"/> </items>
Re. item "type": This is the identifier of the package type. "package" can be used as a standard, as we have added that type to absolutely all products in Cargonizer (There are more than a thousand..), but there are several package types available to the products that support them. Other package types can be pallets, colli and others. All available package types for a product is found in the response of transport_agreements.xml so if your user also send pallets, it might be wise to take these into consideration and perhaps include a possibility for the user to change the package type upon registering the shipment.
Most modules don't though, at least not when just creating a system for quick handling of shipments. Some systems have only implemented a "quick ship" functionality which sends the shipment only with default settings, while others have made both such a "quick ship" functionality, as well as a "advanced ship" functionality, giving the user more flexibility to override the default settings.
So that's it. That will generate a shipment in the users Cargonizer account, but you have not yet printed the label. More on that in a bit as you will first need to know the id of the shipment you just created.
5) Moving on, make a link to the xml response
Generating a shipment in Cargonizer through our API also generates a xml response that includes useful information, such as the id of the shipment which is needed in order to print the label through our print service, the track & trace link, the price of the shipment (if specified) and others.
The track & trace link most users of other systems wants to easily get to, and you also might want to add this link in an email that later is sent to the end customer, perhaps in an order confirmation?
Sending the above minimal example will however not give you very good possibilities to handle the xml response, as you have added none of your own values to match the xml response of the shipment with your request.
So to better be able to link the shipments xml response to your own system, you should add your own unique values in the <values> element of consignments.xml.
By using this element you will establish a connection between the information you send in and the information that is returned back to you. Look at it as the link between the XML request and the xml response.
To add a value, simply add the element(s) in your consignments.xml. There's no limits on how many value elements you can add, and please add a provider value as shown below, so we easier can get in touch with you if it should be needed.
<consignments> <consignment> <values> <value name="orderno" value="123" /> <value name="provider" value="Developer Inc." /> <value name="provider-email" value="Denne e-postadressen er beskyttet mot programmer som samler e-postadresser. Du må aktivere javaskript for å kunne se den." /> </values>
Adding this to your consignments.xml, under the <consignment> element, will in turn return the values in your xml response, creating your link.
6) Understand the xml response
When you send a successful consignments.xml request, you will get a xml response from our API. What you need to take notice of, and also store for display to your user, are the following parts:
This is a unique id for each shipment created in Cargonizer. It is later used for printing the label and should be stored.
Here's your link back to your own system. Pick the value you created and link the shipment back to the request.
This tells the user what carrier is used. Often presented in e-mail sent to end-customers.
Same as above if you want to tell your user, or end customer, what freight alternative was used.
Regardless of the carrier, you will here get a url to track & trace the shipment. Well, if the carrier support track & trace, not all do, but the most used carriers have this.
7) Printing the label
In the xml response you'll get your shipment id, and this is used to send a specific print request to a specific printer. It is advisable to let the user define a default printer in his/hers settings while giving the user the possibility to override the default printer with other available printers when generating the shipment. Pehaps add a user setting where the user can activate "Multiple printers" which will enable a dropdown in the users production environment where one can override the default?
Some systems give the user the possibility to map a printers to specific transport methods. This is very useful if your customer use Bring as a carrier with a specific freight product called "Pakke i postkassen med RFID" as this product require a specific RFID printer to print the labels. This RFID printer can not be used for all other products, regardless of carrier. It is also very usefull for larger companies which have several packing stations.
So, you should have stored the users printer id's earlier, to send a print request you send, as an example, a request like this:
This will print the label of shipment ID 6551236 on printer ID 986
If you want to print several shipments at once, you add them all in one request. This makes sure we get the complete print job which we in turn can send to the DirectPrint/printer.
This example will print labels for four shipments. (Note: A shipment can contain many packages ("amount" in consignments.xml remember), so even though this might look like four labels to you, the reality might be that it's many more labels that will be printed.
Tip: Through our print web service you can print any pdf file you want, meaning you can also generate a package slip and print it just before you print the transport label.
8) Mixing it up, adding more and requesting a more completed consignments.xml
Our API support advanced shipment handling, such as handling of dangerous goods or electronic invoice to certain carriers for use in customs management, but we will not dive into that now. Contact us by email or phone if you need more information than you can find in our standard API documentation on this.
We will however cover what most users expect from your integration and these are all things that's added in your consignments.xml file, the shipment it self.
a) Complete information about the end customer.
Most senders, and most carriers, want all possible information about the receiver of the package. Make sure you send both name and complete address of the end customer as well as e-mail address and mobile phone. If the end customer is a business, also include <contact-person>. A more complete <consignee> part looks like this:
<name>A Company Inc.</name> <address1>Street 5</address1> <address2>Second floor</address2>
<country>NO</country> <email>Denne e-postadressen er beskyttet mot programmer som samler e-postadresser. Du må aktivere javaskript for å kunne se den.</email>
<contact-person>Juan Ponce De Leon</contact-person>
Note: A common mix-up is to use the available <customer-number> element in the consignee part as the customer number of the consignee. And quite frankly, logically it makes perfect sense to mix up this due to the naming, but this element, <customer-number>, is only used when defining the freight payer of the shipment.
If the consignee is the freight payer of the shipment, instead of the sender which is the normal, then the consignees customer number with the carrier needs to be added here, as well as a <freight_payer>true</freight_payer> element, but in, by far, the most regards, you can skip implementing support for this in your module.
So, you should absolutely add the customer number of the consignee (end customer), but use the <number> element when doing it.
b) The return address
If you don't specify the return address, it will be registered with none, aka blank. The carrier usually returns a shipment to the senders address if they can't find the end-customers address, but a setting for registering their own specified return address should be present for your user, where they can specify the return addres themselves. This as many wants that potential returns are delivered at another location. Adding a return address is done by adding a separate part in your consignments.xml and here as well, add as much information as possible. A customer number for this part (the <number> element) is not needed.
<return_address> <name>Senders Inc</name> <address1>Street 1</address1> <address2></address2> <postcode>0068</postcode> <city>Oslo</city> <country>NO</country> <email>Denne e-postadressen er beskyttet mot programmer som samler e-postadresser. Du må aktivere javaskript for å kunne se den.</email> <mobile>98989898</mobile> <phone>20202020</phone> <contact-person>Juan</contact-person> </return_address>Tip: When you did the very first profile.xml request, you also got the senders address in the xml response. Many systems use this information to populate the default return address settings, while giving the user the possibility to change it.
c) Transferring the shipment to the carrier
When creating a shipment in Cargonizer you are not automatically telling us to transfer the information on to the carrier. It is important that a shipment information is transferred to the carrier before the shipment is physically sent, if not, the sender will get penalized by the carrier. Due to this most users prefer to automatically transfer the shipments to the carrier and this can easily be done by adding the <transfer>true</transfer> element to the shipment (consignments.xml).
Place it in the root of the <consignment> element, like this:
<consignments> <consignment transport_agreement="12345" print="false"> <transfer>true</transfer>
It's pretty standard to give the user the possibility to activate or deactivate this true/false element through their settings, as some wants it automatically transferred, while others don't.
The back side of automatically transferring a shipment to the carrier is that it cannot later be changed by the user in his Cargonizer UI before the shipment is sent. We have blocked that possibility as the information of the shipment has been transferred to the carriers systems, meaning it's out of our control. Some carriers also treat an EDI file as a booking, meaning they will send their trucks out to get the package if they receive the transfer, though the most used carriers have separate services for this.
A user wanting to change the shipment after it's created happens now and then as a sender occasionally notices that the shipment is larger than what he/she though when generating the shipment, or the address is wrong or they want to add additional services that perhaps you haven't implemented the possibility for yet.
Therefore it's possible for you to create a setting for your user where they set a time of the day where the transfer is done, this gives the user the chance to edit the shipment manuelly in Cargonizer before the information is sent to the carrier.
When it's time for the transfer you send a transfer request including what shipment id's you want transferred. Potentially this might be a verylong string, but that's ok. However, if it's very, very long (100+ shipments), please split it into two, or three requests.
If using this last transferring method, make sure your consignments.xml does not include
as it will transfer the shipment to the carrier right away. So change it to false if your user wants their transfers done at a specific time of the day.
d) Adding weight, volume and a description to the shipment
The weight of the shipment can easily be calculated if the system owner has added the weight of each product they carry by adding them all together, but the volume is bit tricky to get 100% correct. This as most systems do not have the measurements of the boxes used for packaging in their systems which makes it impossible for you unable to send it to us. It might however work fine for those who only send single products, where they have the measurements added to their products, but if a sender adds several product in one package, they will have to use another box when sending their products, and it's this box that's relevant to the shipment volume.
So, if you don't have a specific "box registry" in your system, this information will be a "best guess" where you add together the volumes of the packages of the order.
To add weight, volume and what is sent in a package you specify it in the <item> element, as an example like this.
<item type="package" amount="1" weight="10" height="20" length="50" width="40" volume="40" description="Item# 345 - Blue shoes, size 43, Item# 342 - Red shoes, size 42"/>
Weight is registred in kilograms, while length, width and height are in cm. Volume is in dm3. (length x width x height / 1000)
e) Adding the order number or the invoice number as a reference
In order to better recognize the shipment in Cargonizer, for the sender that is, your customer, add the order number or the invoice number, as the consignors reference, like this.
<references> <consignor>Order no. 151413</consignor> <consignee>Products from Sender Inc.</consignee>
You can also add a reference for the end customer (the consignee) like shown here, but this is seldom used as the senders name most often identify the sender for the end customer.
f) Pickup points / Service Partners
A pick point, or a service partner which is nothing more than different words for the same (the carriers use different definitions), is a postal office, or a store, close by the end customer where the end customer goes to pick up his package(s). He or she will get a notification from the carrier when it's ready to be picked up. We will for the sake of explaining refer to this as a service partner from now on.
This is a crucial part for many senders who ship to private customers and should be implented rather sooner than later. This as some of Norways largest carriers require this information sent with the rest of the information of the end customer, most B2C packages sent in Norway also use these service partner methods. It's also necessary to include this information if the end customer want to specify the pickup point, regardless of carrier.
But let's troddle back to the response from transport_agreements.xml. When getting the xml response from our transport_agreements.xml you got this response under every <product> received:
If this is 'true' you will have to include a <service_partner> element as a <part> in your consignments.xml when creating the shipment. To find what service partner to use, you will either have to get the service partner information directly from the carriers API, or use our own service, service_partner.xml, for this.
To use our resource, you send the postal number of the end customer, as well as the country code and the carrier, to our API, and you will get a list of the closest service partners for that address in return. The service partners are sorted from closest to furthest away of the end customer so normally you would take the first service partner and add it to your consignments.xml as a separate part.
To better explain this, click this link to look at the response from our API. There is no need for authenticaton.
This will list all service partners for postal number 6300 in Norway, for the carrier PostNord.
The one on the top, is the closest service partner for the postal number given in the request, and we need the following information from response of a service partner in order to complete such a shipment (consignments.xml), meaning a freight "product" that requires a service partner:
<name>POSTNORD AS ÅNDALSNES PICK UP POINT</name>
This information is then added to the shipment request (consignments.xml) before you send your request. This will then give you two <parts> in your consignments.xml file. Or even three parts if you've already added the return address mentioned above:
<parts> <consignee> <number>10001</number> <name>End Customer</name> <address1>Street 5</address1> <address2>Second floor</address2> <postcode>6300</postcode> <city>Åndalsnes</city> <country>NO</country> <email>Denne e-postadressen er beskyttet mot programmer som samler e-postadresser. Du må aktivere javaskript for å kunne se den.</email> <mobile>98989898</mobile> <phone>20202020</phone> <contact-person>Juan</contact-person> </consignee> <service-partner> <number>3807674</number> <name>POSTNORD AS ÅNDALSNES PICK UP POINT</name> <address1>ØRAN VEST</address1> <address2/> <postcode>6300</postcode> <city>ÅNDALSNES</city> <country>NO</country>
</service-partner> <return_address> <name>Senders Inc</name> <address1>Street 1</address1> <address2></address2> <postcode>0068</postcode> <city>Oslo</city> <country>NO</country> <email>Denne e-postadressen er beskyttet mot programmer som samler e-postadresser. Du må aktivere javaskript for å kunne se den.</email> <mobile>98989898</mobile> <phone>20202020</phone> <contact-person>Juan</contact-person>
g) Adding additional services
In some cases the users would want to add additional services to a shipment. Additional services might be such as notification services, cash on delivery, special pickup point or others.
If you give the end customer the possibility to chose his/her own pickup point in the check out (This is pretty normal to do) with the carrier Bring, you will as an example need to add an additional service to the shipment.
Additional services are definied in the <services> element of consignments.xml. Most additional services are simple services, meaning you just have them added like shown below, but there are additional services that might require more information.
"Cash on delivery" is such an example as it requires the amount and an account number in order for the carrier to know how much money, and to what account the money should be paid to and there are a few others as well, but for now, keep it simple and just add a simple notification service if it's available.
In order to add a service, you create a <services> element which will contain one, or more <service> elements. Here is an example where we have added an additional service called "SMS Varsling" with the carrier PostNord. This will tell the carrier, PostNord, that they are to notify the end customer, the consignee, by sms when the package are ready for pickup.
More information on additional services which require more information are found here: Additional Requirements for Products and Services
h) Add a "booking" to the shipment.
A "booking" is a message to the carrier that they are to come to the sender to pick up the packages. Most carriers charge extra for this, while some senders has it included in their agreement. Not all carriers support booking through EDI, but as the largest carriers do, we'll include a small note on this in this guide as well.
This is a feature that should be presented in a checkbox to your customer when they are to generate the shipment(s). If you decide to include this feature in your module, add this element to your consignments.xml.
Set it to false by default, if your user has it ticked off, change it to true.
9) End notes
If you have gotten yourself through all this you should now have a good understanding of our API and how to work it. There are probably still many questions you might have, and you'll probably also get requests from your customer that we haven't covered here, but you should by following this guide be able to cover by far the most requests.
And for those other requests our standard API docs should cover them, but also keep in mind that support is free of charge here at Logistra, also for developers, so feel free to either send us an email at Denne e-postadressen er beskyttet mot programmer som samler e-postadresser. Du må aktivere javaskript for å kunne se den. or give us a call at +47 40002312.