Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Expand
titleGET /pickuppoint/GetPickUpPoints/{countryCode}/{postCode}/{carrier}

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:

  • 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
Code Block
languagejs
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 NOpost code 9991 and carrier Bring

URL Example
Code Block
languagejs
https://cloudconnect.Proteria.com/pickuppoint/GetPickUpPoints/NO/9991/Bring

Result:

JSON response
Code Block
languagejs
{
    "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
        },
		. . . 
    ]
}

Expand
titleGET /pickuppoint/GetParcelBoxPoints/{carrier}/{countryCode}/{postCode}

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:

  • 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
Code Block
languagejs
https://cloudconnect.Proteria.com/pickuppoint/GetPickUpPointsGetParcelBoxPoints/{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 carrier Bring, country code NOpost code 1712

URL Example
Code Block
languagejs
https://cloudconnect.Proteria.com/pickuppoint/GetParcelBoxPoints/BRING/NO/1712/

Result:

JSON response
Code Block
languagejs
{
    "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
        },
        ...
    ]
}

Expand
titleGET /pickuppoint/GetMannedPickupPoints/{carrier}/{countryCode}/{postCode}

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:

  • 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
Code Block
languagejs
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 NOpost code 1712

URL Example
Code Block
languagejs
https://cloudconnect.Proteria.com/pickuppoint/GetMannedPickupPoints/BRING/NO/1712/

Result:

JSON response
Code Block
languagejs
{
    "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
        },
        ...
    ]
}

Shipment API

Expand
titlePOST /shipment/CreateShipments

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:

      • 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
Code Block
languagejs
{
	"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
Code Block
languagejs
"Success: X"

X will equal the amount of shipments successfully created. 

Expand
titlePOST /shipment/CreateShipmentsForOrder

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 to5555 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
Code Block
languagejs
{
	"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"
				},
				. . .
			]
		},
		. . .
	]
}

...

Expand
titleGET /print/GetPrinters

GET /print/GetPrinters

URL Format
Code Block
languagejs
/print/GetPrinters


Example Result:

JSON response
Code Block
languagejs
{
	{
        "Id": "12345",
        "Name": "PrinterName",
        "State": "online"
    },
    {
        "Id": "67890",
        "Name": "PrinterName",
        "State": "offline"
    },
    . . . 
}


Expand
titlePOST /print/Print

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
Code Block
languagejs
{
	"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
Code Block
languagejs
/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
Code Block
languagejs
https://cloudconnect.Proteria.com/print/Print


...