<

Errand Code API

Create Helposti-code

Errand code API is used to create a Helposti-code for the shipment. Parcel can be shipped without the address label if the Helposti-code has been clearly handwritten on the parcel. Helposti-code is 6 characters long string including digits from 0 to 9 and letters from A to F.

API Endpoints

Environment Protocol Host Endpoint
Production HTTPS connect.posti.fi /parcel/v1/errandCodes

Use cases

Get Helposti-code for one shipment:

  • errandCodes/{parcelId}
  • Path parameter
  • parcelId – 12-21 characters (A-Z or numbers)
  • errandCodes?id={comma separated list of ParcelID’s)
  • query parameter

ParcelID is the unique id of the parcel (tracking code). Shipment ID shall be created before the Helposti-code can be created.

Example requests:

GET https://connect.posti.fi/parcel-uat/v1/errandCodes/JJFI6543210000012345

Codes for several parcels can be also retrieved by submitting following request

GET https://connect.posti.fi/parcel-uat/v1/errandCodes?id=JJFI6543210000012345,JJFI6543210000012346

Authentication

Consumption of the service requires Posti oAuth token authentication. Instructions are described in https://api.posti.fi/api-authentication.html

Response Message Structure

Example response 

{
  "ErrandCodeResult": [
    {
      "ParcelID": " JJFI6543210000012345","ErrandCode": "D5BB44","ResultText": "OK"
    }
  ]
}

Example response for multiple parcelIds 

{
  "ErrandCodeResult": [
    { "ParcelID": " JJFI6543210000012345", "ErrandCode": "D5BB44", "ResultText": "OK" },
    { "ParcelID": " JJFI6543210000012346", "ErrandCode": "8B9599", "ResultText": "OK" }
  ]
}

Shipment information

Shipment data shall be available before the Helposti-code can be created for the parcel. It is recommended to use either OmaPosti Pro API (https://api.posti.com/api-omaposti.html) or Postra (https://api.posti.com/api-postra.html) to create the shipment data to minimize the delay in creation of the shipment data in Posti’s systems. Request of the Helposti-code for the shipment which does not exist in Posti’s systems results error. Parcel with Helposti-code can be left to Posti’s parcel lockers with touch screen. The default locker size is S (small) if locker size hasn’t been set. Include also real dimensions for the parcel in the shipmen data.

You can set up the locker size with package type information.

Locker size Dimension Code for the package type
S - small 11 x 32 x 42 cm S2
M - medium 19 x 36 x 60 cm M2
L - large 37 x 36 x 60 cm L2
XL - extra large 59 x 36 x 60 cm XL2

Example for the Postra (look specification for the GoodsItem-data) 

<PackageQuantity type="S2">1</PackageQuantity>

Example for the OmaPosti Pro 

"parcels": [
  {
    "copies": 1,
    "valuePerParcel": true,
    "packageCode": "S2"
  }
]