GuideAPI reference

Label guide

Learn about Helthjem labels. Here you can also find information about creating custom labels.

Overview

We recommend using the Label API for retrieving shipping labels. However, you can make custom labels with the custom labels guide below, all information needed to create a label is provided in the booking response. This guide will outline some basic formats for our label API and also provide you with what you need to create your own.

We must confirm that labels are ok before sending. Please contact us at the integrations email.

 NOTE! The response for Helthjem and Mypack Collect differs when it comes to transport information. Also, when a Mypack Collect is booked, there will also be information about the servicepoint (pick up point) in the response that also must be placed on the label

Technical Specifications

  • Barcode Format: All barcodes are in GS1-128 format.

  • Label dimensions: Standard large labels are 102mm x 192mm.

Standard labels

The labels below are standard outbound labels, retrieved from the label API using the shipmentID in the booking response.

Outbound labels

FreightProductId: 1 - “Helthjem standard” label

See the example below to understand where properties are mapped on this label type.

FreightProductId: 5 - “Helthjem ekspress” uses the same layout.

{
    "shipmentId": "(401)70724763283719873",
    "freightProductId": 1,
    "parties": [
        {
            "type": "consignee",
            "id": null,
            "name": "Ola Nordmann",
            "countryCode": "NO",
            "postalName": "Oslo",
            "zipCode": "0457",
            "address": "Vøyensvingen 10A H0201",
            "detailedAddress": null,
            "phone1": "12345678",
            "phone2": null,
            "email": "test@gmail.com",
            "reference": "cust_ref",
            "contact": "contact2",
            "coaddress": null
        },
        {
            "type": "consignor",
            "id": null,
            "name": "Test shop",
            "countryCode": "NO",
            "postalName": "Vestby",
            "zipCode": "1540",
            "address": "Toveien 19",
            "detailedAddress": null,
            "phone1": "12345678",
            "phone2": null,
            "email": "",
            "reference": "shop_ref",
            "contact": "contact1",
            "coaddress": null
        }
    ],
    "items": [
        {
            "itemId": null,
            "itemNumber": 1,
            "trackingReference": "(00)370724763283719881",
            "returnCode": null,
            "linkedParcelType": null,
            "linkedTrackingReference": null,
            "weight": 1000,
            "volume": null,
            "length": 12,
            "height": 12,
            "width": 12,
            "contentValue": null,
            "externalSupplierId": null,
            "contents": "test item",
            "properties": {
                "shortItemIdentifier": "...9881"
            },
            "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": "22125",
        "routeSeq": "1656",
        "routeZipAndCity": null,
        "routing": "14-0-x22125x1656",
        "routingCode": "1",
        "routingDescription": "RINGNES PARK",
        "routingDetailed": "14 - RINGNES PARK",
        "shopName": "Testbutikken",
        "transportCompanyId": "1",
        "transportNetId": "223"
    },
    "additionalServices": [],
    "orderId": 204585942
}
FreightProductId: 55 - “Helthjem Hentepakke” label

See the example below to understand where properties are mapped on this label type.

{
    "shipmentId": "(401)70724763283720077",
    "freightProductId": 55,
    "parties": [
        {
            "type": "consignee",
            "id": null,
            "name": "Ola Nordmann",
            "countryCode": "NO",
            "postalName": "Oslo",
            "zipCode": "0457",
            "address": "Vøyensvingen 10A H0201",
            "detailedAddress": null,
            "phone1": "12345678",
            "phone2": null,
            "email": "test@gmail.com",
            "reference": "cust_ref",
            "contact": "contact2",
            "coaddress": null
        },
        {
            "type": "consignor",
            "id": null,
            "name": "Test shop",
            "countryCode": "NO",
            "postalName": "Vestby",
            "zipCode": "1540",
            "address": "Toveien 19",
            "detailedAddress": null,
            "phone1": "12345678",
            "phone2": null,
            "email": "",
            "reference": "shop_ref",
            "contact": "contact1",
            "coaddress": null
        },
        {
            "type": "servicePoint",
            "id": "43108",
            "name": "Circle K Kiellands Plass",
            "countryCode": "NO",
            "postalName": "OSLO",
            "zipCode": "0175",
            "address": "UELANDS GATE 55",
            "detailedAddress": null,
            "phone1": null,
            "phone2": null,
            "email": null,
            "reference": null,
            "contact": null,
            "coaddress": null
        }
    ],
    "items": [
        {
            "itemId": null,
            "itemNumber": 1,
            "trackingReference": "(00)370724763283720085",
            "returnCode": null,
            "linkedParcelType": null,
            "linkedTrackingReference": null,
            "weight": 1000,
            "volume": null,
            "length": 12,
            "height": 12,
            "width": 12,
            "contentValue": null,
            "externalSupplierId": null,
            "contents": "test item",
            "properties": {
                "shortItemIdentifier": "...0085"
            },
            "articles": [],
            "externalOrderId": null
        }
    ],
    "properties": {
        "areaId": null,
        "deliveryPointCarId": "10507",
        "distributionDate": "20251120",
        "freightProductName": "Helthjem Hentepakke",
        "mainCarNumber": "520",
        "pickupZipString": "",
        "productName": "Hentepakke",
        "regionId": null,
        "retailerId": "43108",
        "routeAddress": "UELANDSGT 55",
        "routeDescription": null,
        "routeName": "",
        "routeSeq": "",
        "routeZipAndCity": null,
        "routing": "520-6",
        "routingDescription": " ",
        "routingDetailed": "520",
        "shopName": "Testbutikken",
        "transportNetId": "270"
    },
    "additionalServices": [],
    "orderId": 204586033
}
FreightProductId: 3 - “Hent i butikk” (Postnord) label

See the example below to understand where properties are mapped on this label type.

This freight product contains a mission code.

The mission code contains a unicode separator special character 0X1D in the middle.

Often Unicode characters are not visible (depends on configuration). But it must be excluded when you add the code into the barcode on all Postnord labels.

The mission code value is found at properties.missionCode object in Booking API response: 

  • Initial string: 4215780468<0x1d>9013000355691719

  • Unicode character <0x1d> is placed after the first 10 characters. 

  • Make sure that you exclude it before turning it to a bar code (GS1-128 format) 

  • The result value should contain only 26 characters

{
    "shipmentId": "(401)70724763283720138",
    "freightProductId": 3,
    "parties": [
        {
            "type": "consignee",
            "id": "1",
            "name": "Ola Nordmann",
            "countryCode": "NO",
            "postalName": "Oslo",
            "zipCode": "0457",
            "address": "Vøyensvingen 10A H0201",
            "detailedAddress": null,
            "phone1": "12345678",
            "phone2": null,
            "email": "test@gmail.com",
            "reference": "cust_ref",
            "contact": "contact2",
            "coaddress": null
        },
        {
            "type": "consignor",
            "id": "3556917",
            "name": "Test shop",
            "countryCode": "NO",
            "postalName": "Vestby",
            "zipCode": "1540",
            "address": "Toveien 19",
            "detailedAddress": null,
            "phone1": "12345678",
            "phone2": null,
            "email": "",
            "reference": "shop_ref",
            "contact": "contact1",
            "coaddress": null
        },
        {
            "type": "servicePoint",
            "id": "6381776",
            "name": "Rema1000 Ila",
            "countryCode": "NO",
            "postalName": "OSLO",
            "zipCode": "0171",
            "address": "Waldemar Thranes Gate 25",
            "detailedAddress": null,
            "phone1": null,
            "phone2": null,
            "email": null,
            "reference": null,
            "contact": null,
            "coaddress": null
        }
    ],
    "items": [
        {
            "itemId": null,
            "itemNumber": 1,
            "trackingReference": "(00)370724763283720146",
            "returnCode": null,
            "linkedParcelType": null,
            "linkedTrackingReference": null,
            "weight": 1000,
            "volume": null,
            "length": 12,
            "height": 12,
            "width": 12,
            "contentValue": null,
            "externalSupplierId": null,
            "contents": "test item",
            "properties": {},
            "articles": [],
            "externalOrderId": null
        }
    ],
    "properties": {
        "customerNumber": "3556917",
        "freightProductName": "Hent i butikk",
        "issuerNumber": "13",
        "missionCode":"42157804579013000355691719",
        "productCode": "19",
        "productName": "MyPack Collect",
        "routingCode": "ALF",
        "shopName": "Testbutikken"
    },
    "additionalServices": [],
    "orderId": 204586134
}

Return labels

FreightProductId: 4 - “Helthjem retur” label

See the example below to understand where properties are mapped on this label type.

There is a QR code on the label.

The QR code contains the link to https://helthjem.no/retur/aktiver/{trackingReference}

The shop should have “passive return” active.

{
    "shipmentId": "(401)70724763283720190",
    "freightProductId": 4,
    "parties": [
        {
            "type": "consignee",
            "id": null,
            "name": "Test Shop",
            "countryCode": "NO",
            "postalName": "Vestby",
            "zipCode": "1540",
            "address": "Toveien 19",
            "detailedAddress": null,
            "phone1": "12345678",
            "phone2": null,
            "email": "test@gmail.com",
            "reference": "cust_ref",
            "contact": "contact2",
            "coaddress": null
        },
        {
            "type": "consignor",
            "id": null,
            "name": "Test consumer",
            "countryCode": "NO",
            "postalName": "Oslo",
            "zipCode": "0457",
            "address": "Vøyensvingen 10",
            "detailedAddress": null,
            "phone1": "12345678",
            "phone2": null,
            "email": "test@gmail.com",
            "reference": "shop_ref",
            "contact": "contact1",
            "coaddress": null
        }
    ],
    "items": [
        {
            "itemId": null,
            "itemNumber": 1,
            "trackingReference": "(00)370724763283720207",
            "returnCode": null,
            "linkedParcelType": null,
            "linkedTrackingReference": null,
            "weight": 1000,
            "volume": null,
            "length": 12,
            "height": 12,
            "width": 12,
            "contentValue": null,
            "externalSupplierId": null,
            "contents": "test item",
            "properties": {
                "shortItemIdentifier": "...0207"
            },
            "articles": [],
            "externalOrderId": null
        }
    ],
    "properties": {
        "areaId": "59",
        "freightProductName": "helthjem retur",
        "mainCarNumber": "14",
        "pickupZipString": "0556 OSLO",
        "productName": "Retur hjemmefra",
        "regionId": "189",
        "routeAddress": "TOFTES GATE 21 B",
        "routeDescription": "BUDSENTRAL RINGNES PARK",
        "routeName": "22125",
        "routeSeq": "1656",
        "routeZipAndCity": null,
        "routing": "14-0-x22125x1656",
        "routingCode": null,
        "routingDescription": "RINGNES PARK",
        "routingDetailed": "14 - RINGNES PARK",
        "shopName": "Testbutikken",
        "transportCompanyId": "1",
        "transportNetId": "223"
    },
    "additionalServices": [],
    "orderId": 204586147
}

Custom labels

When developing the smaller-sized shipping labels, while we generally maintain flexibility regarding strict formatting, adherence to the following guidelines is essential for successful integration.

Design & Content

  • Design Preference: The optimal approach is to design your labels to closely mirror the subsequent visual examples provided.

  • Data Source: All dynamic data displayed on the labels is sourced directly from the Booking API response.

  • Static Elements: The following elements are considered static and must be incorporated by your design:

    • Logos and Icons

    • Field Names

    • Date format/layout

Technical Specifications

  • Barcode Format: The required barcode format is GS1 128.

  • Preferred Fonts: Please use Arial, Helvetica, or similar sans-serif fonts for maximum readability.

Collaboration & Process

  • Media Assets: Helthjem will provide all necessary media files (logos and icons) in addition to the design presentation.

  • Design Validation: To ensure quick validation and approval, maintain close contact with our Integration team at Helthjem throughout the custom label design process.

  • Production Timeline: A typical design process involves 2-3 iterations of the labels before final approval and deployment into a Production environment.