With the Proteria CloudConnect API, you gain the ability to effortlessly import orders or shipments into Proteria Freight. You have the flexibility to decide whether these shipments or orders should be automatically dispatched to the transporters or if you prefer to utilize the web frontend to finalize the shipment process.
The Proteria CloudConnect API also provides support for Webhooks, enabling your system to receive real-time updates on the booking status of shipments. By leveraging automatic booking, you can conveniently retrieve the shipment label from the Proteria CloudConnect API and seamlessly integrate it into your own system. Furthermore, the API facilitates the updating of your system with accurate shipment tracking status information.
The base URL for the API is https://cloudconnect.proteria.com/, and the API-methods must be added to the end of this URL. |
You must retrieve your API-token from web.proteria.com in order to use the Proteria CloudConnect API
Log in, and then in the top-right corner click on your name → “Your Proteria API Key”
Copy the API key, and make sure that this is included in the header on every HTTP-request, in the 'Authorization'-tag. Remember to write the word Bearer before you include your API key.
Example. “Authorization: Bearer YOUR_API_KEY”
Additional APIs exists (see below)
Step | API | Comment |
---|---|---|
1 | Find relevant shipping methods for your user | |
1.2 | Get the available templates for your company. | |
1.3 | GET /pickuppoint/GetPickUpPoints/{countryCode}/{postCode}/{carrier} | Returns a list of available pickup points close to the given postcode |
1.4 | GET /pickuppoint/GetParcelBoxPoints/{carrier}/{countryCode}/{postCode} | Returns a list of available parcel boxes close to the given postcode |
2 | Make sure to set AutoSendShipments to true (or else you will need to use Proteria Freight GUI to manually send the shipments to transporter. | |
3 | Get the available label | |
4 | Print Label with CloudConnect printers (if workflow is not automated) |
GET /ShippingMethods/GetShippingMethodsForCustomerWith this method, you can get all shipping methods currently available for for you. This method requires authentication with the Proteria API key as bearer token. JSON Response
URL Pattern: URL Format
The fully constructed url: URL Example - Single Shipment
|
GET /Templates/GetTemplatesForCustomerWith this method, you can get all shipping methods currently available for for you. This method requires authentication with the Proteria API key as bearer token. JSON Response
URL Pattern: URL Format
The fully constructed url: URL Example - Single Shipment
|
GET /pickuppoint/GetAllPickUpPoints/{carrier}/{countryCode}/{postCode}/{street?}/{streetNumber?}This action returns a list of pick-up points close to the postcode that was sent to this action. Must contain country code, postcode and name of carrier.
The url must be constructed using this format, although street and streetNumber are optional fields: URL Pattern
Replace {countryCode} with a valid ISO2 country code, {postCode} with a valid and existing postcode, and {carrier} with the name of a carrier supported in the Proteria systems. Replace {street} with a valid street name in the currently selected {postCode}. For example, is you call this action with country code NO, post code 9991 and carrier Bring: URL Example
Result: JSON response
|
GET /pickuppoint/GetParcelBoxPoints/{carrier}/{countryCode}/{postCode}/{street?}/{streetNumber?}This action returns a list of parcel boxes close to the postcode that was sent to this action. Must contain name of carrier, country code, and postcode.
The url must be constructed using this format, although street and streetNumber are optional fields: URL Pattern
Replace {countryCode} with a valid ISO2 country code, {postCode} with a valid and existing postcode, and {carrier} with the name of a carrier supported in the Proteria systems. Replace {street} with a valid street name in the currently selected {postCode}. For example, is you call this action with carrier Bring, country code NO, post code 1712: URL Example
Result: JSON response
|
GET /pickuppoint/GetMannedPickupPoints/{carrier}/{countryCode}/{postCode}/{street?}/{streetNumber?}This action returns a list of manned pickup points close to the postcode that was sent to this action. Must contain name of carrier, country code, and postcode.
The url must be constructed using this format, although street and streetNumber are optional fields: URL Pattern
Replace {countryCode} with a valid ISO2 country code, {postCode} with a valid and existing postcode, and {carrier} with the name of a carrier supported in the Proteria systems. Replace {street} with a valid street name in the currently selected {postCode}. For example, is you call this action with carrier Bring, country code NO, post code 1712: URL Example
Result: JSON response
|
POST /shipment/CreateShipmentsWith this action, you can create one or more shipments in our systems. The JSON must be inside the "Body" of the request, and the header "Content-Type" should be set to "application/json".
The values for "PackageType", "CashOnDelivery" and "Services" are optional. The JSON must look like this: JSON request
If successful, you will get this response: JSON response
X will equal the amount of shipments successfully created. |
POST /shipment/CreateShipmentsForOrderWith this action, you can create one or more shipments to an order that has previously been created/placed in our systems. In other words, you must have run "POST /CreateNewOrder" before you can run this action. This action uses the orderid of an order that already exists in our systems, and this orderid will be used to connect a shipment to an order. The JSON must be inside the "Body" of the request, and the header "Content-Type" should be set to "application/json".
The values for "PackageType", "PickUpPointId", "CashOnDelivery" and "Services" are optional, however if they are set, the will override the corresponding values in the order. This means that The JSON must look like this: JSON request
|
POST /label/GetLabel/{printFormat}This action gets the label(s) of the shipment(s) within the shipmentIds parameter in the HTTP request body JSON, and returns it in the format specified by the parameter printFormat. Return labels fetched when IncludeReturnLabel is set to true must be created through the CreateShipment action with the GenerateReturn flag set to true.
URL Pattern: URL Format
This is a sample of a JSON that must be sent with the request (For more labels, add to ids to the array below): JSON Request - Single Shipment
For multiple shipments: JSON Request - Multiple Shipments
If you call this action with the JSON above and printFormat Label: https://cloudconnect.Proteria.com/label/GetLabel/Label, You will either be promped to download the returned label, or it will open up in a new tab in your browser. Calls with single or multiple shipmentIds will always |
POST /order/CreateNewOrderWith this action, you can create/upload an order in our systems by sending us a JSON containing your order. The JSON must be inside the "Body" of the request, and the header "Content-Type" should be set to "application/json".
The JSON must look like this: JSON request
|
GET /print/GetPrintersURL Format
JSON response
|
POST /print/PrintThis action print the label(s) of shipment(s) within the shipmentIds parameter, by sending a print job to the either
The shipmentIds parameter must contain (an) id(s) of a shipment previously created through the CreateShipment-action in the API, The fields inside the Printers field, namely A4PrinterId, LabelPrinterId, RFIDPrinterId and PiPPrinterId parameters must contain the id of a printer that is connected to your Proteria Cloud Print Box, thus making it When PrintReturnLabel is set to true, return shipments created with the CreateShipment action and the GenerateReturn flag set to true, will be printed out if available
JSON request
URL Pattern: URL Format
The fully constructed url: URL Example - Single Shipment
|
There are a couple of webhooks that should be implemented to ensure a seamless experience to the users.
These webhooks are:
Remember to provide a link/url/address to a script that we can send HTTP-request to regarding each of the webhooks listed above.
These are necessary, as we will be sending information about each of these events to these endpoints/urls/links.
Example:
After you have sent a HTTP-request to cloudconnect.Proteria.com/shipments/CreateShipment with a json containing data of your shipments,
and a link to a script in the ShipmentReceived-field, then we will send an HTTP-request to this link once we have received your request to notify
you that we have received that shipment.
We will send the shipmentId of a shipment that we successfully received to this link/url/address.
A request is sent for each shipment received.
The data that we send in the HTTP-request body will look like the following:
{ "Shipmentid": "A_SHIPMENT_ID" } |
We will send the shipmentId of a shipment that we have validated to this link/url/address.
A request is sent for each shipment validated.
The data that we send in the HTTP-request body will look like the following:
{ "Shipmentid": "A_SHIPMENT_ID", "Valid": true } |
Field valid can be either true or false.
We will send the shipmentId, tracking number and tracking url of a shipment that has been successfully booked at the transporter to this link/url/address.
A request is sent for each shipment successfully booked.
The data that we send in the HTTP-request body will look like the following:
{ "Shipmentid": "A_SHIPMENT_ID", "Trackingnumber": "A_TRACKING_NUMBER", "Trackingurl": "A_TRACKING_URL" } |
We will send the shipmentId of a shipment that failed to get booked at the transporter to this link/url/address.
A request is sent for each shipment that failed to get booked.
The data that we send in the HTTP-request body will look like the following:
{ "Shipmentid": "A_SHIPMENT_ID" } |
We will send the shipmentId of a shipment that has a label available for printing to this link/url/address.
A request is sent for each shipment that has a label available.
The data that we send in the HTTP-request body will look like the following:
{ "Shipmentid": "A_SHIPMENT_ID" } |
We will send the shipmentId, tracking number, tracking url and status of a shipment every time we receive
a updated tracking information regarding the shipment to this link/url/address.
A request is sent for each tracking update.
The data that we send in the HTTP-request body will look like the following:
{ "Shipmentid": "A_SHIPMENT_ID", "Status": "A_STATUS", //Possible status codes: // None = 0, // PartiallySubmitted = 1, // Submitted = 2, // PartiallyDelivered = 4, // Delivered = 5 "Trackingnumber": "A_TRACKING_NUMBER", "Trackingurl": "A_TRACKING_URL" } |
We will send the shipmentId of a shipment that failed to print to this link/url/address.
A request is sent for each shipment that failed to print.
The data that we send in the HTTP-request body will look like the following:
{ "Error": "AN_ERROR_MSG", "Shipmentid": "A_SHIPMENT_ID" } |
Error code | Message |
---|---|
E1001 | Token does not have CompanyId. User is either not logged in or does not have access to CloudConnect API. Might not have token. |
E1002 | User did not send an order with the request, thus making it impossible to create a new order. JSON of order must be added to the body of the HTTP request. |
E1003 | The order the user sent in his HTTP request did not contain required filed "OrderId". |
E1003-S | The shipment creation action did not receive an "OrderId". |
E1004 | The field "OrderId" in the order that was sent in the HTTP request does not contain a unique orderId. OrderId has been used before. Please use another OrderId. |
E1005 | Upload of new order/shipment failed when trying to save the order/shipment. Please contact Proteria for help. |
E1006 | Unexpected error when saving order or sending JSON response. Please contact Proteria for help. |
E1007 | The orderid that was sent with the action is not the orderid of an existing order in our system. Please run the "POST /CreateNewOrder" action to create an order, and then proceed to create shipments using the orderid of the created order. |
E1008 | Unexpected error when trying to start creation of shipments. Please contact Proteria for help. |
E1009 | The "CashOnDelivery" field was missing one or more fields, or had both the "KID" and "Message" fields set. Remember the all values here must be set, and that you can ONLY have a values in "KID" OR "Message". If both fields have value, it will result in an error, and an error will also occur if both fields do not contain a value. The field "Amount" can not be less than 1. |
E1010 | One or more of the required fields in "POST /CreateNewOrder" were empty or null. Please check if these were sent with the HTTP request. Remember that if "receiver" and "delivery" are the identical (think of "receiver" as the entity you send the invoice too, and "delivery" as the entity the shipment will be sent to), you must write the same values for both the "receiver" and "delivery" fields. |
E1011 | The field "PackageType" contained an invalid or unsupported id for package type. Please use the method /ShippingMethods/GetShippingMethodsForCustomer for a complete list of possible package type ids. |
E1012 | The field "Services" containded an id that is not valid. Please use the id of a service that is supported. See description above for valid services. |
E1013 | Currency code must be exactly three letters, all uppercase, and can only contain letters from A to Z. |
E1014 | Fields "Description" and "Quantity" were either missing values or had invalid values. Fields "Description" and "Quantity" must be set per item inside field "OrderLine". Quantity must also be over zero. |
E1015 | Date format wrong. Field "OrderCreationDate" must have the format "dd/mm/yyyy hh:mm:ss.ms", where dd/mm/yyyy is short for day/month/year, and hh:mm:ss.ms is short for hour:minute:seconds.milliseconds. |
E1016 | Date format wrong. Field "InvoiceCreatedAt" must have the format "dd/mm/yyyy hh:mm:ss.ms", where dd/mm/yyyy is short for day/month/year, and hh:mm:ss.ms is short for hour:minute:seconds.milliseconds. |
E1017 | Dates for "OrderCreationDate" could not be created. Please contact Proteria for help. |
E1018 | Date for "InvoiceCreatedAt" could not be created. Please contact Proteria for help. |
E1019 | Incoterm code must be exactly three letters, all uppercase, and can only contain letters from A to Z. |
E1020 | Field "CountryOfOrigin" must be a valid ISO2 country code. More on valid ISO2 codes here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. or here https://www.iso.org/obp/ui/#search/code/ under the column Alpha-2 code. |
E1021 | Field "CustomsTariffNumber" must be at least six characters. |
E1022 | Field "DangerousGoods" must be exactly four digits. |
E1023 | Field "Shipments" was either null or did not contain any shipments. Please add a shipment to this field. |
E1024 | Field "ShipmentId" was not included in the request. Please include this before sending the HTTP request, as each shipment must have a Shipment Id. |
E1025 | Field "ShipmentId" did not contain a unique ShipmentId, meaning that a shipment with the same shipment id has previously been uploaded/created. Please change this to a unique Shipment Id. |
E1026 | Field "PrintFormat" was not included in the requst. The print format must be attached to the end of the url, and cna have the values of A4 or Label. Ex: cloudconnect.Proteria.com/label/SH123/Label. This means that you want a the label of shipment SH123, where the label is optimizied for thermal-printers. |
E1027 | Field "ShipmentId" contained a shipment id for a shipment that does not, or does not yet, exist in our systems. Please use the id of a shipment that you have previously sent to Proteria via the api. |
E1028 | Field "countryCode" was not set in the url for the action. The value must be a valid ISO2 country code. More on valid ISO2 codes here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. or here https://www.iso.org/obp/ui/#search/code/ under the column Alpha-2 code. |
E1029 | Field "postCode" was not set in the url for the action. Must be a valid and existing post code. For Norwegian Postcodes, look here: https://adressesok.posten.no/nb/postal_codes/search |
E1030 | Field "carrier" was not set in the url for the action. Must be the name of a carrier supported by Proteria. Check the documentation for the GetPickUpPoints action for valid and supported carriers. |
E1031 | Field "carrier" does not contain a valid value. Must be the name of a carrier supported by Proteria. Check the documentation for the GetPickUpPoints action for valid and supported carriers. |
E1032 | Field "countryCode" is not supported by the chosen "carrier". Must be a country code supported by the chosen carrier. See the documentation for the GetPickUpPoints action for valid and supported country codes per carrier. |
E1033 | Something went wrong during the retrieval of pick-up-points from the carrier. Please contact Proteria for help with this issue. |
E1034 | Field "shipmentIds" did not contain any ids. Please add at least one id of an existing shipment in this parameter. |
E1035 | One of the shipmentIds in the field b "shipmentIds" did not contain any value. Please make sure that there are no empty values in the url. |
E1036 | No pick-up point was found for the chosen postcode/postnumber with the chosen carrier. This could be beause the carrier does not offer service to that area, or because the chosen postcode/postnumber is an invalid/non-existing. |
E1037 | The number of shipment ids in the HTTP url exceed the allowed limit, and the request stopped. See the /label/GetLabels action description in the documentation for more information about the limit. |
E1038 | If the package type of a order or shipment is a "Pakke i Postkassen"/"Small Packet", then Delivery.Email OR Delivery.PhoneNumber is required, since eVarsling is required by the transporter from these products. Please add a phone number or an email to the JSON. |
E1039 | Field "Waybills" was either null or did not contain any waybills. Please add a waybill to this field. |
E1040 | Field "SendAutoMailShipmentInfoToReceiver" was true. but Contact person did not have an email address |
E1041 | Field "SendTrackingInfoSMSToReceiver" was true, but Contact person did not have a phone number |
E1042 | No pick-up point was found for the chosen address with the chosen carrier. This could be because the address is invalid/doesn't exist. |
E1043 | No pick-up point was found for the chosen street with the chosen carrier. This could be because the street name is invalid/doesn't exist. |
List of United Nation Dangerous Goods Ids
Information related to ISO2 country codes and codes: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. and https://www.iso.org/obp/ui/#search/code/.
IncoTerm information and codes