Errand Code API

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 (service.id PO2108 is for the return shipments).

{
    "pdfConfig": {
        "target1Media": "laser-a5"
    },
    "shipment": {
        "sender": {
            "name": "Firstname Lastname",
            "address1": "Homestreet 1",
            "zipcode": "00100",
            "city": "HELSINKI",
            "country": "FI",
            "phone": "0407654321",
            "email": "firstname.lastname@example.com"
        },
        "senderPartners": [
            {
                "id": "POSTI",
                "custNo": "{Replace this with your contract ID}"
            }
        ],
        "receiver": {
            "name": "Company name",
            "address1": "Business street 1",
            "zipcode": "00230",
            "city": "HELSINKI",
            "country": "FI",
            "phone": "0401234567",
            "email": "example@companyname.com"
        },
        "senderReference": "sales order reference",
        "service": {
            "id": "PO2108",
            "addons": [
                {
                    "id": "3196"
                }
            ]
        },
        "parcels": [
            {
                "copies": "1",
                "height":"0.1",
                "width":"0.2",
                "length":"0.3",
                "packageCode": "S2",
                "valuePerParcel": true
            }
        ]
    }
}