CloudConnect API (API documentation)


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.

Content

 Step-by-step guide


Authorization:

  1. You must retrieve your API-token from web.proteria.com in order to use the Proteria CloudConnect API

  2. Log in, and then in the top-right corner click on your name → “Your Proteria API Key




  3. 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”

API Flow

Additional APIs exists (see below)

Step

API

Comment

Step

API

Comment

1

GET /ShippingMethods/GetShippingMethodsForCustomer

Find relevant shipping methods for your user

1.2

GET /Templates/GetTemplatesForCustomer

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

POST /Shipping/CreateShipments

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

POST /label/GetLabel/{printFormat}

Get the available label

4

POST /print/Print

Print Label with CloudConnect printers (if workflow is not automated)

ShippingMethods API

 

GET /ShippingMethods/GetShippingMethodsForCustomer

With 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
[ { "id": 1240, "displayText": "BringV2: Pakke levert hjem", "carrier": "BringV2", "services": [ "service_evarsling", "service_enkelDelivery", "service_identification", "service_personalDelivery" ], "hasPickupPoints": false, "isReturnProduct": false, "isExpressProduct": false }, { "id": 12100, "displayText": "BringV2: Pakke til bedrift", "carrier": "BringV2", "services": [ "service_enkelDelivery" ], "hasPickupPoints": false, "isReturnProduct": false, "isExpressProduct": false }, { "id": 1220, "displayText": "BringV2: Pakke til hentested", "carrier": "BringV2", "services": [ "service_evarsling", "service_cod", "service_valgfrittHentested", "service_brevVarlsing", "service_identification", "service_personalDelivery" ], "hasPickupPoints": true, "isReturnProduct": false, "isExpressProduct": false }, ..., ]

 

URL Pattern:

URL Format
/ShippingMethods/GetShippingMethodsForCustomer

 

The fully constructed url:

URL Example - Single Shipment
https://cloudconnect.Proteria.com/ShippingMethods/GetShippingMethodsForCustomer

 

Templates API

 

GET /Templates/GetTemplatesForCustomer

With 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

 

Pick-Up Point API:

 

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.
Max 5 results.

 

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 NOpost 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 "carrier" field:

    • Must have the name of a carrier supported by Proteria.

    • As of Desember 2017, these are:

      • Bring

      • PostNord

  • The "countryCode" field:

  • The "postCode" field:

    • Must contain the value of a valid and existing post code.

    • Post code must exist in the country chosen in field countryCode.

  • The "street" field (optional):

    • Must be a valid street name.

    • Street name must exist in the post code chosen in field postCode.

  • The "streetNumber" field (optional):

    • Should be a valid street number.

 

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 NOpost 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 "carrier" field:

    • Must have the name of a carrier supported by Proteria.

    • As of Desember 2017, these are:

      • Bring

      • PostNord

  • The "countryCode" field:

  • The "postCode" field:

    • Must contain the value of a valid and existing post code.

    • Post code must exist in the country chosen in field countryCode.

  • The "street" field (optional):

    • Must be a valid street name.

    • Street name must exist in the post code chosen in field postCode.

  • The "streetNumber" field (optional):

    • Should be a valid street number.

 

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 NOpost code 1712

URL Example

 

Result:

JSON response

 

Shipment API

 

Label API

 

Order API

 

 

 Webhooks

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. 

ShipmentReceived webhook

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:

JSON structure

 

ValidationStatus webhook

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:

JSON structure

 

Field valid can be either true or false.

BookingOk webhook

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:

JSON structure

 

BookingFailed webhook

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:

JSON structure

 

LabelAvailable webhook

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:

JSON structure

 

TrackingStatus webhook

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:

JSON structure

 

PrintFailed webhook

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:

JSON structure



 Errors

Error code

Message

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/.

Norwegian province codes.

Currency codes and more info

IncoTerm information and codes

Norwegian post codes