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": 1and"productName": "helthjem standard"(Standard home delivery)
- Alternative 2:
"freightProductId": 3and"productName": "Hentepakke"(Hentepakke PUDO)
- Alternative 3:
"freightProductId": 55and"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": "53582094", "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": "53582094", "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
ASBand valueHHWMS
- 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,63for 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"