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

1 Step-by-step guide
- 1.1 Authorization:
- 1.2 API Flow
2 ShippingMethods API
- 2.1 GET /ShippingMethods/GetShippingMethodsForCustomer
3 Templates API
- 3.1 GET /Templates/GetTemplatesForCustomer
4 Pick-Up Point API:
5 Shipment API
- 5.1 POST /shipment/CreateShipments
- 5.2 POST /shipment/CreateShipmentsForOrder
6 Label API
- 6.1 POST /label/GetLabel/{printFormat}
7 Order API
- 7.1 POST /order/CreateNewOrder
8 Print API
- 8.1 GET /print/GetPrinters
- 8.2 POST /print/Print
9 Webhooks
- 9.1 ShipmentReceived webhook
- 9.2 ValidationStatus webhook
- 9.3 BookingOk webhook
- 9.4 BookingFailed webhook
- 9.5 LabelAvailable webhook
- 9.6 TrackingStatus webhook
- 9.7 PrintFailed webhook
10 Errors
11 Related articles

Step-by-step guide

Authorization:

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”

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 "countryCode" field:
- Must be a valid ISO2 country code.
- More about ISO2 country codes here: ISO 3166-1 alpha-2 . and https://www.iso.org/obp/ui/#search/code/.
- Supports only certain countries, and the support varies with the carrier.
  - If carrier is Bring:
    - Allowed values are SE, NO, DK and FI.
  - If carrier is PostNord:
    - Allowed values are SE, NO, FI, DK, DE, BE, NL and LU.
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 "carrier" field:
- Must have the name of a carrier supported by Proteria.
- As of Desember 2017, these are:
  - Bring
  - PostNord
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 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 "carrier" field:
- Must have the name of a carrier supported by Proteria.
- As of Desember 2017, these are:
  - Bring
  - PostNord
The "countryCode" field:
- Must be a valid ISO2 country code.
- More about ISO2 country codes here: ISO 3166-1 alpha-2 . and https://www.iso.org/obp/ui/#search/code/.
- Supports only certain countries, and the support varies with the carrier.
  - If carrier is Bring:
    - Allowed values are SE, NO, DK and FI.
  - If carrier is PostNord:
    - Allowed values are SE, NO, FI, DK, DE, BE, NL and LU.
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 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 "carrier" field:
- Must have the name of a carrier supported by Proteria.
- As of Desember 2017, these are:
  - Bring
  - PostNord
The "countryCode" field:
- Must be a valid ISO2 country code.
- More about ISO2 country codes here: ISO 3166-1 alpha-2 . and https://www.iso.org/obp/ui/#search/code/.
- Supports only certain countries, and the support varies with the carrier.
  - If carrier is Bring:
    - Allowed values are SE, NO, DK and FI.
  - If carrier is PostNord:
    - Allowed values are SE, NO, FI, DK, DE, BE, NL and LU.
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 NO, post code 1712:

URL Example

Result:

JSON response

Shipment API

Label API

Order API

Print API

Webhooks

There are a couple of webhooks that should be implemented to ensure a seamless experience to the users.
These webhooks are:

1 ShipmentReceived webhook
2 ValidationStatus webhook
3 BookingOk webhook
4 BookingFailed webhook
5 LabelAvailable webhook
6 TrackingStatus webhook
7 PrintFailed webhook

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.