CloudConnect API (API documentation)

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

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

[
    {
        "templateId": "freightshipmenttemplatedtos-65",
        "templateName": "Test",
        "isDefault": true,
        "module": "Fraktbrev",
        "displayName": "Fraktbrev - Test"
    },
    {
        "templateId": "freightshipmenttemplatedtos-97",
        "templateName": "test2",
        "isDefault": false,
        "module": "BringV2",
        "displayName": "BringV2 - test2"
    },
    {
        "templateId": "freightshipmenttemplatedtos-321",
        "templateName": "test 44",
        "isDefault": false,
        "module": "BringV2",
        "displayName": "BringV2 - test 44"
    },    
	...,
]

URL Pattern:

URL Format

/Templates/GetTemplatesForCustomer

The fully constructed url:

URL Example - Single Shipment

https://cloudconnect.Proteria.com/Templates/GetTemplatesForCustomer

GET /pickuppoint/GetPickUpPoints/{countryCode}/{postCode}/{carrier}

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: https://en.wikipedia.org/wiki/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

https://cloudconnect.Proteria.com/pickuppoint/GetPickUpPoints/{countryCode}/{postCode}/{carrier}/{street}/{streetNumber}

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

https://cloudconnect.Proteria.com/pickuppoint/GetPickUpPoints/NO/9991/Bring

Result:

JSON response

{
    "pickUpPoints": [
        {
            "id": "127390",
            "name": "Extra Båtsfjord",
            "address": "HAVNEGATA 2",
            "postcode": "9990",
            "city": "BÅTSFJORD",
            "countryCode": "NO",
            "latitude": 70.637387041799,
            "longitude": 29.726844386049567
        },
        {
            "id": "127373",
            "name": "Matkroken Berlevåg",
            "address": "STORGATA 7",
            "postcode": "9980",
            "city": "BERLEVÅG",
            "countryCode": "NO",
            "latitude": 70.85703147746338,
            "longitude": 29.086313368005154
        },
		. . . 
    ]
}

GET /pickuppoint/GetParcelBoxPoints/{carrier}/{countryCode}/{postCode}

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: https://en.wikipedia.org/wiki/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 url must be constructed using this format, although street and streetNumber are optional fields:

URL Pattern

https://cloudconnect.Proteria.com/pickuppoint/GetParcelBoxPoints/{countryCode}/{postCode}/{street?}/{streetNumber}

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

https://cloudconnect.Proteria.com/pickuppoint/GetParcelBoxPoints/BRING/NO/1712/

Result:

JSON response

{
    "pickUpPoints": [
        {
            "id": "113284",
            "name": "Pakkeboks Asvo Bruktmarked",
            "address": "GRÅLUMVEIEN 192",
            "postcode": "1712",
            "city": "GRÅLUM",
            "countryCode": "NO",
            "latitude": 59.285832499102114,
            "longitude": 11.058674538778082
        },
        {
            "id": "110428",
            "name": "Pakkeboks Esso Grålum",
            "address": "BJØRNSTADVEIEN 10",
            "postcode": "1712",
            "city": "GRÅLUM",
            "countryCode": "NO",
            "latitude": 59.295096557260848,
            "longitude": 11.065633980094994
        },
        ...
    ]
}

GET /pickuppoint/GetMannedPickupPoints/{carrier}/{countryCode}/{postCode}

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: https://en.wikipedia.org/wiki/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 url must be constructed using this format, although street and streetNumber are optional fields:

URL Pattern

https://cloudconnect.Proteria.com/pickuppoint/GetMannedPickupPoints/{carrier}/{countryCode}/{postCode}/{street?}/{streetNumber}

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

https://cloudconnect.Proteria.com/pickuppoint/GetMannedPickupPoints/BRING/NO/1712/

Result:

JSON response

{
    "pickUpPoints": [
        {
            "id": "121518",
            "name": "Extra Grålum",
            "address": "VESTERHEIMVEIEN 2",
            "postcode": "1712",
            "city": "GRÅLUM",
            "countryCode": "NO",
            "latitude": 59.294283208743941,
            "longitude": 11.064603165110883
        },
        {
            "id": "121635",
            "name": "Extra Tune",
            "address": "LILLETUNEVEIEN 3",
            "postcode": "1711",
            "city": "SARPSBORG",
            "countryCode": "NO",
            "latitude": 59.287693555888843,
            "longitude": 11.082480232984947
        },
        ...
    ]
}

POST /shipment/CreateShipments

With 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".

• All values are strings.

• Field "AutoSendShipments":

  • If this field is set to true, the shipments created will automatically sent to the transporter, such as Bring, PostNord, etc, if the shipment is valid. 

  • This option will be applied to all the shipments sent with the HTTP request. 

• Field "AutoPrint":

  • If this field is set to true, the shipments created will automatically send a print job to a printer after the label has been created.

  • The printers in the users Cloud Print-settings in Proteria Freight will be used.  

  • This option will be applied to all the shipments sent with the HTTP request. 

• Field “DefaultTemplateId”:

  • Optional field.

  • Set the id of the template you want to use on all shipments in the call if none other are specified on the shipment.

  • Use the method /Templates/GetTemplatesForCustomer for a complete list of possible template ids.

• Field "Webhooks":

  • Fill the fields inside Webhooks with links to scripts you want us to sendt HTTP requests to with updated information regarding your shipments,
    such as when they have been validated, if the label is ready, and the tracking status of a shipment. See section Webhooks for more information
    about the data in the HTTP requests sent to the webhook links.

• Field "Shipments":

  • Array of shipments.

  • Must contain at least one shipment item.

  • Field "OrderId":

    • Optional, but good to have for sorting and getting shipments later. 

  • Field "ShipmentId":

    • Required.

    • This field must be set to ensure that the customer has an id to get the status of the shipment and the label of a shipment in later HTTP calls. 

  • Field “TemplateId”:

    • Optional.

    • If a template id is set in this field, it will override the default template.

    • Use the method /Templates/GetTemplatesForCustomer for a complete list of possible template ids.

    • Use id “NO_TEMP” to completely omit using a template on this shipment

  • The "Delivery", "Sender" and "ReturnTo" fields:

    • The "Delivery" field is related to the the person/entity that will receive the order/package.

    • The "ReturnTo" filed is the actor/entity that will receive the return-package. Use the same information for the Sender and ReturnTo fields if the two entities are identical.

    • "IsCompany" is optional, but we can provide a better validation if this value is set, and issues such as those regarding mismatches between the
      package type and the Delivery-entity can be avoided (e.g. a package type only sends to companies, etc).  

    • You must fill the required fields.

    • If the there is no street address (just postbox), then use the postbox/zip-code in the Address1 field.  

    • The "Country" field:

      • Must be a valid ISO2 country code. 

      • More about ISO2 country codes here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2  and https://www.iso.org/obp/ui/#search/code/.

    • The "ContactPerson" field:

      • Required. 

      • A contact person must have a Name.

      • A contact person must have a PhoneNumber.

      • Email is optional.

  • Field "PackageType"

    • This field must be set to ensure an automated process from creating on order with this http request, to creating a shipment at Proteria Frakt.

    • If this value is not set, the user must go to the Proteria Frakt interface and search and import orders individually.

    • Use the method /ShippingMethods/GetShippingMethodsForCustomer for a complete list of possible package type ids.

  • Field "GenerateReturn":

    • The value of this field will determine if a return-label is created right after the original consignment has been sent.

    • Value must be true or false, i.e boolean values.

    • The return-label will have it's own shipmentId, which will follow this format: RETURN_ORIGINAL-SHIPMENT-ID. E.g. if a shipmentId is SH123, then the shipmentId of the return-label will be RETURN_SH123. 

  • Field "PickUpPointId": 

    • We use the term PickUpPoint to refer to the place where the customer must pick up their package. 

    • Is used for package types that required the customer to pick up their package, such as PostNord MyPack Collect.

    • PostNord ServicePoint is also a PickUpPoint.

    • The Id of a pickup point can be aquired by using our PickUpPoint API.

    • Must contain a valid PickUpPoint Id. 

  • Field "CashOnDelivery":

    • This field is optional, but if used must contain either "KID" OR "Message". Both can not have a value, and both can not be empty. The remaining fields are required. 

    • The field "Amount" must be above 1.

    • The filed "AccountNumber" must be set. Shipments containing invalid account numbers will still be created, but must be corrected before officially sending the shipment to a transporter. 

  • Field "Services":

    • An array of strings.

    • Each string contains the name/id of the service you want.

    • Valid and supported names/ids are found in the GetShippingMethodsForCustomer method. 

  • Field "SendAutoMailShipmentInfoToReceiver":

    • This field is optional, and will default to false.

    • If true will send tracking info to receiver by mail

    • Will use the email template created on web.Proteria.com or a default template if not created.

  • Field "SendTrackingInfoSMSToReceiver":

    • This field is optional, and will default to false.

    • If true will send tracking info to receiver by SMS

  • Field "DeliveryInstruction":

    • This field is optional.

    • Contains any specific instructions regarding the delivery.

  • Field "Parcels":

    • Array of parcels.

    • Fields "LengthCM", "WidthCM" and "HeightCM" are integers, "WeightKG" is a decimal, and "Reference" is a string. 

The values for "PackageType", "CashOnDelivery" and "Services" are optional.

The JSON must look like this:

JSON request

{
	"AutoSendShipments": false,								/* Required, Set to true to automatically send valid shipments */
	"AutoPrint": false,										/* Requiered, set to true to automatically print when label is ready */
	"DefaultTemplateId": "templateid-1",						/* Optional, set to use a template on all shipments in call, unless the shipment has set its own template */
	"Webhooks": {
  		"ShipmentReceived":"",
  		"ValidationStatus":"",
		"BookingOk":"",
		"BookingFailed":"",
		"LabelAvailable":"",
		"TrackingStatus":"",
		"PrintFailed":""
  	},
	"Shipments": [											/* Required, and must have at least one shipment */
		{
			"OrderId": "OR123",								/* Optional */
			"ShipmentId": "SH123123",						/* Required */
			"TemplateId": "template-22",						/* Optional */
			"Sender": {
				"Name": "Ole Brum",							/* Required */
				"Address1": "Hundremeterskogen 100",		/* Required */
				"Address2": null,
				"PostCode": "0100",							/* Required */
				"City": "Hundremeterskogen",				/* Required */
				"Country": "HM",							/* Required */
				"ContactPerson": {
					"Name":"Jan Teigen",
					"Email": null,
					"PhoneNumber": "12345678"
				}
			},
			"Delivery": {
				"IsCompany": true,							/* Optional, set this to avoid validation errors regarding mismatch with package type */
				"Name": "Hercules",							/* Required */
				"Address1": "Olympusveien 10",				/* Required */
				"Address2": null,	
				"PostCode": "2020",							/* Required */
				"City": "Athen",							/* Required */
				"Country": "GR",							/* Required */
				"ContactPerson": {
					"Name":"Jan Teigen",
					"Email": null,
					"PhoneNumber": "12345678"				/* Required */
				}
			},
			"ReturnTo": {									/* Optional */
				"IsCompany": true,							/* Optional, set this to avoid validation errors regarding mismatch with package type */
				"Name": "Simba",							/* Required if return-label must be created */
				"Address1": "Fjell 10",						/* Required if return-label must be created */
				"Address2": null,	
				"PostCode": "2020",							/* Required if return-label must be created */
				"City": "Athen",							/* Required if return-label must be created*/
				"Country": "GR",							/* Required if return-label must be created*/
				"ContactPerson": {
					"Name":"Jan Teigen",
					"Email": null,
					"PhoneNumber": "12345678"				/* Required if return-label must be created*/
				}
			},
			"SendersReference": "sr",
			"ReceiversReference": "rr",
			"DeliveryInstruction": "I am a message",		/*Optional, used to give specific instructions for the delivery. */
			"MsgToReceiver": "mtr",
			"PackageType": "1220",
			"GenerateReturn": true,							/* Optional */
			"PickUpPointId": "PUP123",
			"CashOnDelivery": {    						
				"AccountNumber": "12345678999",				/* Required if CashOnDelivery is going to be used */ 
				"Amount": 123.45,							/* Required if CashOnDelivery is going to be used */ 
				"Message": "I am message.",					/* Required if CashOnDelivery is going to be used. Must be empty if "KID" is going to be used. */
				"KID": "I am KID."							/* Required if CashOnDelivery is going to be used. Must be empty if "Message" is going to be used. */
			},
			"Services": [								
				"service_evarsling",
				"service_cod",
				. . .
			],				
			"SendAutoMailShipmentInfoToReceiver": false,
			"SendTrackingInfoSMSToReceiver": false,		
			"Parcels": [
				{
					"LengthCM": 12,
					"WidthCM": 34,
					"HeightCM": 56,
					"WeightKG": 123.45,
					"Reference": "I am reference"
				},
				. . .
			]
		},
		. . .
	]
}

If successful, you will get this response:

JSON response

"Success: X"

X will equal the amount of shipments successfully created. 

POST /shipment/CreateShipmentsForOrder

With 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".

• All values are strings.

• Field "OrderId":

  • This OrderId is the one that the user has given to an order in their respective systems.

  • This field is required, and must be the orderid of an order previously uploaded to the system. 

  • All the shipments in this HTTP action will be connect to the order with id OrderId. 

• Field "AutoSendShipments":

  • If this field is set to true, the shipments created will automatically sent to the transporter, such as Bring, PostNord, etc, if the shipment is valid. 

  • This option will be applied to all the shipments sent with the HTTP request. 

• Field "AutoPrint":

  • If this field is set to true, the shipments created will automatically send a print job to a printer after the label has been created.

  • The printers in the users Cloud Print-settings in Proteria Freight will be used.  

  • This option will be applied to all the shipments sent with the HTTP request. 

• Field “DefaultTemplateId”:

  • Optional field.

  • Set the id of the template you want to use on all shipments in the call if none other are specified on the shipment.

  • Use the method /Templates/GetTemplatesForCustomer for a complete list of possible template ids.

• Field "Webhooks":

  • Fill the fields inside Webhooks with links to scripts you want us to sendt HTTP requests to with updated information regarding your shipments,
    such as when they have been validated, if the label is ready, and the tracking status of a shipment. See section Webhooks for more information
    about the data in the HTTP requests sent to the webhook links.

• Field "Shipments":

  • Array of shipments.

  • Must contain at least one shipment item.

  • Field "ShipmentId":

    • Required.

    • This field must be set to ensure that the customer has an id to get the status of the shipment and the label of a shipment in later HTTP calls. 

  • Field “TemplateId”:

    • Optional.

    • If a template id is set in this field, it will override the default template.

    • Use the method /Templates/GetTemplatesForCustomer for a complete list of possible template ids.

    • Use id “NO_TEMP” to completely omit using a template on this shipment

  • Field "PackageType"

    • This field must be set to ensure an automated process from creating on order with this http request, to creating a shipment at Proteria Frakt.

    • If this value is not set, the user must go to the Proteria Frakt interface and search and import orders individually.

    • Use the method /ShippingMethods/GetShippingMethodsForCustomer for a complete list of possible package type ids.

  • Field "PickUpPointId": 

    • We use the term PickUpPoint to refer to the place where the customer must pick up their package. 

    • Is used for package types that required the customer to pick up their package, such as PostNord MyPack Collect.

    • PostNord ServicePoint is also a PickUpPoint.

    • The Id of a pickup point can be aquired by using our PickUpPoint API.

    • Must contain a valid PickUpPoint Id. 

  • Field "CashOnDelivery":

    • This field is optional, but if used must contain either "KID" OR "Message". Both can not have a value, and both can not be empty. The remaining fields are required. 

    • The field "Amount" must be above 1.

    • The filed "AccountNumber" must be set. Shipments containing invalid account numbers will still be created, but must be corrected before officially sending the shipment to a transporter. 

  • Field "Services":

    • An array of strings.

    • Each string contains the name/id of the service you want.

    • Valid and supported names/ids are found in the GetShippingMethodsForCustomer method.

  • Field "SendAutoMailShipmentInfoToReceiver":

    • This field is optional, and will default to false.

    • If true will send tracking info to receiver by mail

    • Will use the email template created on web.Proteria.com or a default template if not created.

  • Field "SendTrackingInfoSMSToReceiver":

    • This field is optional, and will default to false.

    • If true will send tracking info to receiver by SMS

  • Field "DeliveryInstruction":

    • This field is optional.

    • Contains any specific instructions regarding the delivery.

    • Will overwrite any delivery instructions placed on the creation of the order

    • Set value to null to use the one set on the creation of the order

  • Field "Parcels":

    • Array of parcels.

    • Fields "LengthCM", "WidthCM" and "HeightCM" are integers, "WeightKG" is a decimal, and "Reference" is a string. 

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
if you set the value for, for example, "PackageType" to 1100 in the "POST /CreateNewOrder" call, and set the value for "PackageType" in one of the shipments to 5555 in the "POST /CreateShipmentsForOrder" call,
then 5555 is the value for "PackageType" that will be used for that specific shipment. If the "PackageType" field is left empty, the shipment will use the "PackageType" found in the order.

The JSON must look like this:

JSON request

{
	"OrderId": "1001",									/* Required */
	"AutoSendShipments": false,							/* Required, Set to true to automatically send valid shipments */
	"AutoPrint": false,										/* Requiered, set to true to automatically print when label is ready */
	"DefaultTemplateId": "templateid-1",						/* Optional, set to use a template on all shipments in call, unless the shipment has set its own template */
	"Webhooks": {
  		"ShipmentReceived":"",
  		"ValidationStatus":"",
		"BookingOk":"",
		"BookingFailed":"",
		"LabelAvailable":"",
		"TrackingStatus":"",
		"PrintFailed":""
  	},
	"Shipments": [										/* Required, and must have at least one shipment */
		{
			"ShipmentId": "SH123123",					/* Required */
    		"TemplateId": "template-22",				/* Optional */
			"SendersReference": "sr",
			"ReceiversReference": "rr",
			"DeliveryInstruction": "I am a message",	/*Optional, used to give specific instructions for the delivery. */
			"MsgToReceiver": "mtr",
			"PackageType": "1220",
			"PickUpPointId": "PUP123",					
			"CashOnDelivery": {    						
				"AccountNumber": "12345678999",			/* Required if CashOnDelivery is going to be used */ 
				"Amount": 123.45,						/* Required if CashOnDelivery is going to be used */ 
				"Message": "I am message.",				/* Required if CashOnDelivery is going to be used. Must be empty if "KID" is going to be used. */
				"KID": "I am KID."						/* Required if CashOnDelivery is going to be used. Must be empty if "Message" is going to be used. */
			},
			"Services": [								
				"service_evarsling",
				"service_cod",
				. . .
			],
			"SendAutoMailShipmentInfoToReceiver": false,
			"SendTrackingInfoSMSToReceiver": false,			
			"Parcels": [
				{
					"LengthCM": 12,
					"WidthCM": 34,
					"HeightCM": 56,
					"WeightKG": 123.45,
					"Reference": "I am reference"
				},
				. . .
			]
		},
		. . .
	]
}

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.
The shipmentIds parameter in the JSON must contain (an) id(s) of a shipment previously created through the CreateShipment-action in the API,
hence the shipmentId(s) will be the id(s) that the user has set for the shipment(s) in their own systems.

Return labels fetched when IncludeReturnLabel is set to true must be created through the CreateShipment action with the GenerateReturn flag set to true.

A maximum of 100 shipment ids allowed per request. 

URL Pattern:

URL Format

/label/GetLabel/{printFormat}

Replace {printFormat} with the format of the label you want, and attach the id(s) of the shipment(s).
Valid values for printFormat are: A4 and Label, where the latter is optimized to fit into thermal-printers. 

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

{
	"shipmentids": [
		"SH1525780262_96_6"
	],
	"IncludeReturnLabel": false //Optional. Set to true to fetch return label if available. Return label must be generated to be fetched
}

For multiple shipments: 

JSON Request - Multiple Shipments

{
	"shipmentids": [
		"SH1525780262_96_6",
		"SH123_123_123"
	],
	"IncludeReturnLabel": false //Optional. Set to true to fetch return label if available. Return label must be generated to be fetched
}

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 
result in one single pdf, which contains all the labels of the shipments stated in the url. (Return type: FileStreamResult)

POST /order/CreateNewOrder

With 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".

• All values are strings.

• Field "OrderId":

  • This OrderId is the one that the user has given to the order in their respective systems.

  • This field is required, and must be unique to the order. This means that the order must have an order id that has not been used previously. 

• The "Receiver", "Delivery" and "ReturnTo" fields:

  • The fields within the "Receiver" field are related to the person/entity that will pay for the order.

  • The "Delivery" fields are related to the the person/entity that will receive the order/package.

  • The "ReturnTo" filed is the actor/entity that will receive the return-package. Use the same information for the Sender and ReturnTo fields if the two entities are identical.

  • "IsCompany" is optional, but we can provide a better validation if this value is set, and issues such as those regarding mismatches between the
    package type and the Delivery-entity can be avoided (e.g. a package type only sends to companies, etc).  

  • If these to are set to the same person/entity in your order, the field for "Receiver" and "Delivery" can be equal, i.e. they represent the same entity, thus they can be identical.

  • The "Country" field:

    • Must be a valid ISO2 country code. 

    • More about ISO2 country codes here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2  and https://www.iso.org/obp/ui/#search/code/.

  • The "ContactPerson" field:

    • Required. 

    • A contact person must have a Name.

    • A contact person must have a PhoneNumber.

    • Email is optional.

  • You must fill the required fields, as stated in the point above. 

• Field "PackageType":

  • This field must be set to ensure an automated process from creating on order with this http request, to creating a shipment at Proteria Frakt.

  • If this value is not set, the user must go to the Proteria Frakt interface and search and import orders individually.

  • Use the method /ShippingMethods/GetShippingMethodsForCustomer for a complete list of possible package type ids.
    

• Field "PickUpPointId": 

  • We use the term PickUpPoint to refer to the place where the customer must pick up their package. 

  • Is used for package types that required the customer to pick up their package, such as PostNord MyPack Collect.

  • PostNord ServicePoint is also a PickUpPoint.

  • The Id of a pickup point can be aquired by using our PickUpPoint API.

  • Must contain a valid PickUpPoint Id. 

• Field "InvoiceNumber":

  • InvoiceNumber the number of the invoice related to this order, in the users systems.

  • This field can be set to NULL is there is no InvoiceNumber. 

• Field "DeliveryInstruction":

• • This field is optional.

  • Contains any specific instructions regarding the delivery.

• Fields "OrderCreationDate":

  • This field must have a string that matches this 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. 

• Field "InvoiceCreatedAt": 

  • This field must have a string that matches this 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.

• Field "CurrencyCode":

  • Must be exactly three letters, all uppercase, and can only contain letters from A to Z. 

  • For more information about valid currency codes, etc, visit this page: http://www.xe.com/iso4217.php .

• Field "IncoTerm":

  • Must be exactly three letters, all uppercase, and can only contain letters from A to Z.

  • IncoTerm is short for International Commercial Terms.

  • For more information about IncoTerm, please visit this page: https://www.freightos.com/portfolio-items/incoterms-plain-english-freight-shipping-guide/ .

• Field "CashOnDelivery":

  • This field is optional, but if used must contain either "KID" OR "Message". Both can not have a value, and both can not be empty. The remaining fields are required. 

  • The field "Amount" must be above 1.

  • The filed "AccountNumber" must be set. Shipments containing invalid account numbers will still be created, but must be corrected before officially sending the shipment to a transporter. 

• Field "Services":

  • An array of strings.

  • Each string contains the name/id of the service you want.

  • Valid and supported names/ids are found in the GetShippingMethodsForCustomer method.

• Field "OrderLines":

  • Array of orderlines.

  • Fields "Description", "ArticleNumber", "CustomsTariffNumber", "DangerousGoods", "CountryOfOrigin" and "ProvinceOfOrigin" are strings, while the rest are all decimals. 

  • Field "Description":

  • Field "ArticleNumber":

  • Field "CustomsTariffNumber":

  • Field "Quantity":
    

    • The quantity, i.e. how many of the same item sold/part of the same orderline.

    • Must be more than zero.

  • Field "DangerousGoods":

    • Accepts values of exactly four or six letters.

    • In the case of a four character string:

      • The string must only contain digits, e.g. 1234.

    • In the case of a six character string:

      • The string must contain the letters UN follwed by exactly four digits, e.g. UN1234.

      • Any string missing the UN affix will result in an error. 

    • For more information about dangerous goods and which value to use for this field, go to this page: https://en.wikipedia.org/wiki/Lists_of_UN_numbers .

  • Field "CountryOfOrigin":

    • Must be a valid ISO2 country code. 

    • More about ISO2 country codes here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2  and  https://www.iso.org/obp/ui/#search/code/.

  • Field "ProvinceOfOrigin":

    •  For Norwegian province codes, look here: https://www.toll.no/Imagedocument/summary?imageBlockId=353&contentPageId=197#34%20Varens%20opprinnelses-%2Fproduksjonsfylke.

  • Field "VATRate":

    • Specifies how many percent the VAT amounts to.

The JSON must look like this:

JSON request

{
	"Sender": {
		"Name": "Ole Brum",						/* Required */
		"Email": null,
		"PhoneNumber": null,
		"Address1": "Hundremeterskogen 100",	/* Required */
		"Address2": null,
		"PostCode": "0100",						/* Required */
		"City": "Hundremeterskogen",			/* Required */
		"Country": "HM",						/* Required */
		"ContactPerson": {
			"Name":"Jan Teigen",
			"Email": null,
			"PhoneNumber": "12345678"
		}
	},
	"Receiver": {
		"Name": "Aladdin",					/* Required */
		"Email": null,
		"PhoneNumber": "12345678",			/* Required */
		"Address1": "Agrabaveien 10",		/* Required */
		"Address2": null,
		"PostCode": "1010",					/* Required */
		"City": "Agraba",					/* Required */
		"Country": "AG",					/* Required */
		"ContactPerson": {
			"Name":"Jan Teigen",
			"Email": null,
			"PhoneNumber": "12345678"
		}
	},
	"Delivery": {
		"IsCompany": true,					/* Optional, set this to avoid validation errors regarding mismatch with package type */
		"Name": "Hercules",					/* Required */
		"Email": null,
		"PhoneNumber": "12345678",			/* Required */
		"Address1": "Olympusveien 10",		/* Required */
		"Address2": null,	
		"PostCode": "2020",					/* Required */
		"City": "Athen",					/* Required */
		"Country": "GR",					/* Required */
		"ContactPerson": {
			"Name":"Jan Teigen",
			"Email": null,
			"PhoneNumber": "12345678"
		}
	},
	"ReturnTo": {									/* Optional */
		"IsCompany": true,							/* Optional, set this to avoid validation errors regarding mismatch with package type */
		"Name": "Simba",							/* Required if return-label must be created */
		"Address1": "Fjell 10",						/* Required if return-label must be created */
		"Address2": null,	
		"PostCode": "2020",							/* Required if return-label must be created */
		"City": "Athen",							/* Required if return-label must be created*/
		"Country": "GR",							/* Required if return-label must be created*/
		"ContactPerson": {
			"Name":"Jan Teigen",
			"Email": null,
			"PhoneNumber": "12345678"				/* Required if return-label must be created*/
		}
	},
	"OrderId": "1001",								/* Required, and must be unique */
	"OrderCreationDate": "07/07/2007 7:7:7.7",
	"DeliveryInstruction": "Delivery instructions",
	"PackageType": "1220",							/* Required */
	"PickUpPointId": "PUP123",
	"InvoiceNumber": null,
	"InvoiceCreatedAt": "08/08/2008 8:8:8.8",
	"CurrencyCode": "NOK",
	"IncoTerm": "nuk",
	"CashOnDelivery": {    						
		"AccountNumber": "12345678999",				/* Required if CashOnDelivery is going to be used */ 
		"Amount": 123.45,							/* Required if CashOnDelivery is going to be used */ 
		"Message": "I am message.",					/* Required if CashOnDelivery is going to be used. Must be empty if "KID" is going to be used. */
		"KID": "I am KID."							/* Required if CashOnDelivery is going to be used. Must be empty if "Message" is going to be used. */
	},
	"Services": [ 
		"service_evarsling",
		"service_cod",
		. . .
	],
	"OrderLines": [
		{
			"Description": "I am description.",		/* Required if OrderLines is going to be used */
			"ArticleNumber": null,
			"CustomsTariffNumber": "123456",
			"Quantity": 1.0,						/* Required if OrderLines is going to be used */
			"DangerousGoods": "1234",				/* Not required, but must be 4 digits or UN plus four digits, e.g. 1234 or UN1234 */ 
			"CountryOfOrigin": "he",
			"ProvinceOfOrigin": null,
			"UnitPriceExcludingVAT": 0.0,
			"UnitPriceIncludingVAT": 0.0,
			"TotalPriceExcludingVAT": 0.0,
			"TotalPriceIncludingVAT": 0.0,
			"VATAmount": 0.0,
			"VATRate": 0.0,
			"UnitGrossWeightKG": 0.0,
			"TotalGrossWeightKG": 0.0,
			"UnitNetWeightKG": 0.0,
			"TotalNetWeightKG": 0.0
		},
		. . .
	],
	"OrganizationNumber": null,
	"VATNumber": 0.0,
	"VATAmount": 0.0,
	"VATRate": 0.0,
	"TotalPriceExcludingVAT": 0.0,
	"TotalPriceIncludingVAT": 0.0
}

GET /print/GetPrinters

URL Format

/print/GetPrinters

Example Result:

JSON response

{
	{
        "Id": "12345",
        "Name": "PrinterName",
        "State": "online"
    },
    {
        "Id": "67890",
        "Name": "PrinterName",
        "State": "offline"
    },
    . . . 
}

POST /print/Print

This action print the label(s) of shipment(s) within the shipmentIds parameter, by sending a print job to the either
the default printers specified for A4, Label, RFID and PiPLabel, (default printers set in Frakt Web Settings)
or the printer with id matching the value of the printerId parameter.

THIS REQUIRES AN ACTIVATED Proteria CLOUD PRINT ACCOUNT.
More about Cloud Print: https://www.Proteria.no/Proteria-frakt/Proteria-frakt-web/skrivere-og-etiketter/

The shipmentIds parameter must contain (an) id(s) of a shipment previously created through the CreateShipment-action in the API,
hence the shipmentId(s) will be the id(s) that the user has set for the shipment(s) in their own systems.

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
possible for us to find the printer and send print jobs to it. These ids are used to shipments to the appropriate printers, as each label has a different size and format.

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

A maximum of 100 shipment ids allowed per request. 

JSON request

{
	"Printers": {
		"A4PrinterId": "IAmA4",
		"LabelPrinterId": "IAmLabel",
		"RFIDPrinterId": "IAmRFID",
		"PiPPrinterId": "IAmPiPLabel"
	},
	"ShipmentIds": [
		"SH123",
		"SH456",
		..,
	],
	"PrintReturnLabel": false //Set to true to also print out the return label if available
}

URL Pattern:

URL Format

/print/Print

If the printerId parameters above are set to null, our system will use the default printers selected by the user on our website
under the Cloud Print settings.

The fully constructed url:

URL Example - Single Shipment

https://cloudconnect.Proteria.com/print/Print