Booking API

PROD: https://api.helthjem.no/parcels/v1/bookings PRE-PROD: https://api.pre.helthjem.no/parcels/v1/bookings

The purpose of this API is to register a parcel shipment from a consignor (could be a private person or a shop) to a consignee ( private person or a shop).

You can use request examples below directly in your setup just by changing tranportSolutionId and ShopId

Coverage

Depending on the transportSolutionId you send in the request and address coverage, you will get either:

🟢 200 HTTP status code and "freightProductId" of available delivery method

🔴 400 HTTP status code and "no.carrier.support” message, which means that Helthjem can not deliver to a address with the chosen method, i.e. transportSolutionId

To avoid getting "no.carrier.support” when booking please make sure you always do the coverage check with 📍Single Address Check API before sending the booking request.

📘

Detailed documentation https://jira-di.atlassian.net/wiki/spaces/DIPUB/pages/68026370/Parcel+Booking+API

Example 1: booking with transportSolutionId:"1"

With transportSolutionId:"1", we have coverage throughout Norway. The response will include one of the following options, depending on selected address:

Alternative 1: "freightProductId": 1 and "productName": "helthjem standard"(Standard home delivery)

Alternative 2: "freightProductId": 3 and "productName": "Hentepakke"(Hentepakke PUDO)

Alternative 3: "freightProductId": 55 and "productName": "MyPack Collect"((Postnord MyPack Collect PUDO)

Request example 1

json
{
    "shopId": 1,
    "transportSolutionId": 1,
    "shipmentId": "",
    "parties": [
        {
            "type": "consignee",
            "name": "Test Customer",
            "countryCode": "NO",
            "postalName": "Oslo",
            "zipCode": "0566",
            "address": "Fjellgata 48",
            "phone1": "48398438",
            "email": "testcustomer@test.com",
            "reference": "cust_ref",
            "contact": "contact2"
        },
        {
            "type": "consignor",
            "name": "Test shop",
            "countryCode": "NO",
            "postalName": "Oslo",
            "zipCode": "0480",
            "address": "Sandakerveien 121",
            "phone1": "",
            "contact": "contact1",
            "reference": "shop_ref",
            "email":""
        }
    ],
    "items": [
        {
            "itemNumber": 1,
            "trackingReference": "",
            "weight": 1000,
            "width": 12,
            "height": 12,
            "length": 12,
            "contents": "test item"
        }
    ]
}

Response example 1

json
{
    "shipmentId": "(401)70724762337121945",
    "freightProductId": 1,
    "parties": [
        {
            "type": "consignee",
            "id": null,
            "name": "Test Customer",
            "countryCode": "NO",
            "postalName": "Oslo",
            "zipCode": "0566",
            "address": "Fjellgata 48",
            "phone1": "48398438",
            "phone2": null,
            "email": "testcustomer@test.com",
            "reference": "cust_ref",
            "contact": "contact2",
            "coaddress": null
        },
        {
            "type": "consignor",
            "id": null,
            "name": "Test shop",
            "countryCode": "NO",
            "postalName": "Oslo",
            "zipCode": "0480",
            "address": "Sandakerveien 121",
            "phone1": "",
            "phone2": null,
            "email": "",
            "reference": "shop_ref",
            "contact": "contact1",
            "coaddress": null
        }
    ],
    "items": [
        {
            "itemNumber": 1,
            "trackingReference": "(00)370724762337121953",
            "returnCode": null,
            "linkedParcelType": null,
            "linkedTrackingReference": null,
            "weight": 1000,
            "volume": null,
            "length": 12.0,
            "height": 12.0,
            "width": 12.0,
            "contentValue": null,
            "externalSupplierId": null,
            "contents": "test item",
            "properties": {
                "shortItemIdentifier": "...1953"
            },
            "articles": [],
            "externalOrderId": null
        }
    ],
    "properties": {
        "areaId": "59",
        "freightProductName": "helthjem",
        "mainCarNumber": "14",
        "pickupZipString": "0556 OSLO",
        "productName": "helthjem standard",
        "regionId": "189",
        "routeAddress": "TOFTES GATE 21 B",
        "routeDescription": "BUDSENTRAL RINGNES PARK",
        "routeName": "22140",
        "routeSeq": "121",
        "routeZipAndCity": null,
        "routing": "14-0-x22140x121",
        "routingCode": "1",
        "routingDescription": "RINGNES PARK",
        "routingDetailed": "14 - RINGNES PARK",
        "shopName": "Testbutikken",
        "transportCompanyId": "1",
        "transportNetId": "223"
    },
    "additionalServices": [],
    "orderId": 89828037
}

Example 2: booking delivery to a service point

If you need to make a booking of a delivery to a service-point (PUDO), you have an option to select a service-point in advance with 📮Nearby Service Points API and add it to a booking request. Booking request has to be done with "transportSolutionId": 62 and selected service-point at “parties” object of a request.

Request example 2

json
{
    "shopId": 1,
    "transportSolutionId": 62,
    "shipmentId": "",
    "parties": [
        {
            "type": "consignee",
            "name": "Test Customer",
            "countryCode": "no",
            "postalName": "Oslo",
            "zipCode": "0195",
            "address": "Fjellgata 48",
            "phone1": "75476618",
            "email": "testcustomer@test.com",
            "reference": "cust_ref"
        },
        {
            "type": "consignor",
            "name": "Testbutikken",
            "countryCode": "NO",
            "postalName": "OSLO",
            "zipCode": "0180",
            "address": "Akersgata 55",
            "phone1": "75476618",
            "contact": "testcustomer@test.com",
            "reference": "shop_ref"
        },
        {
            "type": "servicePoint",
            "id": "30694",
            "countryCode": "NO"
        }
    ],
    "items": [
        {
            "itemNumber": 1,
            "trackingReference": "",
            "weight": 35,
            "width": 0,
            "height": 12.0,
            "length": 35.0,
            "contents": "en pakke"
        }
    ]
}

Response example 2

json
{
    "shipmentId": "(401)70724762337122546",
    "freightProductId": 55,
    "parties": [
        {
            "type": "consignee",
            "id": null,
            "name": "Test Customer",
            "countryCode": "no",
            "postalName": "Oslo",
            "zipCode": "0195",
            "address": "Fjellgata 48",
            "phone1": "75476618",
            "phone2": null,
            "email": "testcustomer@test.com",
            "reference": "cust_ref",
            "contact": null,
            "coaddress": null
        },
        {
            "type": "consignor",
            "id": null,
            "name": "Testbutikken",
            "countryCode": "NO",
            "postalName": "OSLO",
            "zipCode": "0180",
            "address": "Akersgata 55",
            "phone1": "75476618",
            "phone2": null,
            "email": null,
            "reference": "shop_ref",
            "contact": "testcustomer@test.com",
            "coaddress": null
        },
        {
            "type": "servicePoint",
            "id": "30694",
            "name": "Joker Toftes Gate",
            "countryCode": "NO",
            "postalName": "OSLO",
            "zipCode": "0556",
            "address": "TOFTES GATE 12",
            "phone1": null,
            "phone2": null,
            "email": null,
            "reference": null,
            "contact": null,
            "coaddress": null
        }
    ],
    "items": [
        {
            "itemNumber": 1,
            "trackingReference": "(00)370724762337122554",
            "returnCode": null,
            "linkedParcelType": null,
            "linkedTrackingReference": null,
            "weight": 35,
            "volume": null,
            "length": 35.0,
            "height": 12.0,
            "width": 0.0,
            "contentValue": null,
            "externalSupplierId": null,
            "contents": "en pakke",
            "properties": {
                "shortItemIdentifier": "...2554"
            },
            "articles": [],
            "externalOrderId": null
        }
    ],
    "properties": {
        "areaId": null,
        "deliveryPointCarId": "8064",
        "distributionDate": "20230202",
        "freightProductName": "Helthjem Hentepakke",
        "mainCarNumber": "103",
        "pickupZipString": "",
        "productName": "Hentepakke",
        "regionId": null,
        "retailerId": "30694",
        "routeAddress": "TOFTES GATE 12",
        "routeDescription": null,
        "routeName": "",
        "routeSeq": "",
        "routeZipAndCity": null,
        "routing": "103-5",
        "routingDescription": " ",
        "routingDetailed": null,
        "shopName": "Testbutikken",
        "transportNetId": "204"
    },
    "additionalServices": [
        {
            "key": "RNL",
            "value": "Legitimasjonskontroll"
        }
    ],
    "orderId": 89828099
}

Example 3: booking a fulfilment order

When booking a fulfilment order to be picked by Helthjem, additional information is required in the booking request. After a successful booking is made, the order will be transferred to the WMS within 5 minutes. The booking request must include:

Additional service with key ASB and value HHWMS

Article name, article ID and quantity

Request example 3

json
{
    "shopId": 1,
    "transportSolutionId": 1,
    "additionalServices": [
        {
            "key": "ASB",
            "value": "HHWMS"
        }
    ],
    "shipmentId": "",
    "parties": [
        {
            "type": "consignee",
            "name": "Test Customer",
            "countryCode": "NO",
            "postalName": "Oslo",
            "zipCode": "0566",
            "address": "Fjellgata 48",
            "phone1": "48398438",
            "email": "testcustomer@test.com",
            "reference": "cust_ref",
            "contact": "contact2"
        },
        {
            "type": "consignor",
            "name": "Test shop",
            "countryCode": "NO",
            "postalName": "Oslo",
            "zipCode": "0480",
            "address": "Sandakerveien 121",
            "phone1": "",
            "contact": "contact1",
            "reference": "shop_ref",
            "email": ""
        }
    ],
    "items": [
        {
            "itemNumber": 1,
            "trackingReference": "",
            "weight": 1000,
            "width": 12,
            "height": 12,
            "length": 12,
            "contents": "test item",
            "articles": [
                {
                    "articleNumber": "100200300",
                    "articleName": "Testitem",
                    "quantity": 1
                }
            ]
        }
    ]
}

Response example 3

json
{
    "shipmentId": "(401)70724762687981480",
    "freightProductId": 1,
    "parties": [
        {
            "type": "consignee",
            "id": null,
            "name": "Test Customer",
            "countryCode": "NO",
            "postalName": "Oslo",
            "zipCode": "0566",
            "address": "Fjellgata 48",
            "phone1": "48398438",
            "phone2": null,
            "email": "testcustomer@test.com",
            "reference": "cust_ref",
            "contact": "contact2",
            "coaddress": null
        },
        {
            "type": "consignor",
            "id": null,
            "name": "Test shop",
            "countryCode": "NO",
            "postalName": "Oslo",
            "zipCode": "0480",
            "address": "Sandakerveien 121",
            "phone1": "",
            "phone2": null,
            "email": "",
            "reference": "shop_ref",
            "contact": "contact1",
            "coaddress": null
        }
    ],
    "items": [
        {
            "itemNumber": 1,
            "trackingReference": "(00)370724762687981498",
            "returnCode": null,
            "linkedParcelType": null,
            "linkedTrackingReference": null,
            "weight": 1000,
            "volume": null,
            "length": 12.0,
            "height": 12.0,
            "width": 12.0,
            "contentValue": null,
            "externalSupplierId": null,
            "contents": "test item",
            "properties": {
                "shortItemIdentifier": "...1498"
            },
            "articles": [
                {
                    "articleNumber": "100200300",
                    "quantity": 1,
                    "articleName": "Testitem"
                }
            ],
            "externalOrderId": null
        }
    ],
    "properties": {
        "areaId": "59",
        "freightProductName": "helthjem",
        "mainCarNumber": "14",
        "pickupZipString": "0556 OSLO",
        "productName": "helthjem standard",
        "regionId": "189",
        "routeAddress": "TOFTES GATE 21 B",
        "routeDescription": "BUDSENTRAL RINGNES PARK",
        "routeName": "22111",
        "routeSeq": "536",
        "routeZipAndCity": null,
        "routing": "14-0-x22111x536",
        "routingCode": "1",
        "routingDescription": "RINGNES PARK",
        "routingDetailed": "14 - RINGNES PARK",
        "shopName": "Testbutikken",
        "transportCompanyId": "1",
        "transportNetId": "223"
    },
    "additionalServices": [
        {
            "key": "ASB",
            "value": "External Packaging System"
        }
    ],
    "orderId": 133370472
}

Return parcels

Booking request for return products is the same as for a regular outgoing booking. The difference are:

You should to use one of transportSolutionId:17,21,33,63 for return.

Your shop name have to be written under parties.type: "consignee"

Customer info who sends the return has to be under parties.type: "consignor"