Quick-start guide

Learn about the basic steps for setting up a standard Business to Consumer integration.

Integration for a basic B2C parcel

This quick-start guide outlines the basic steps to set up a simple integration. We recommend to start on the testing environment where you can Authenticate, book a parcel and retrieve a label in less than 30 minutes.

All examples below use the test environment and the test shop. Replace your-client-id and your-client-secret with the test credentials you received from our Integrations Team.

STEP 1: Authorize

Use the Authorization endpoint to get a JWT token and authorize in our system.

Request

curl -X POST "https://api.pre.helthjem.no/auth/oauth2/v1/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "grant_type": "client_credentials"
  }'

Response

{
  "token": "xxxxxxxxxxxxxxxx",
  "expires_in": 86400,
  "token_type": "Bearer"
}

This Bearer token needs to be in the header of all subsequent requests: Authorization: Bearer <token>. The examples below use $TOKEN for it.

Cache the token

A token is valid for 24 hours ( expires_in is in seconds). Store it and reuse it for all requests, and fetch a new one shortly before it expires or when a request returns 401 . Do not request a new token for every API call.

STEP 2: Check delivery methods

Use Single Address Check endpoint to check coverage and available delivery options for an address.

Request

curl -X POST "https://api.pre.helthjem.no/parcels/v1/addresses/find/single" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shopId": 16,
    "transportSolutionId": 1,
    "customerName": "Ola Nordmann",
    "address": "Kongsberggata 18",
    "zipCode": "0468",
    "postalName": "Oslo",
    "countryCode": "NO",
    "weight": 1000
  }'

Response (trimmed)

{
  "productName": "HELTHJEM",
  "routeName": "21507",
  "routing": "16-0-x21507x1466",
  "routingDescription": "TÅSEN"
}

"productName": "HELTHJEM" confirms that home delivery is available for this address. If the address is not covered, the API responds with 400 and "errorKey": "no.carrier.support".

STEP 3: Register a booking

Use Booking endpoint to create a booking. Send an idempotency-key header with a unique value for each shipment, so you can safely retry the request without creating a duplicate.

Request

curl -X POST "https://api.pre.helthjem.no/parcels/v1/bookings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: 3f1b2c9e-8a7d-4e21-9c55-0a1b2c3d4e5f" \
  -d '{
    "shopId": 16,
    "transportSolutionId": 1,
    "parties": [
      {
        "type": "consignee",
        "name": "Ola Nordmann",
        "countryCode": "NO",
        "postalName": "Oslo",
        "zipCode": "0468",
        "address": "Kongsberggata 18",
        "phone1": "12345678",
        "email": "ola@example.com"
      },
      {
        "type": "consignor",
        "name": "Test shop",
        "countryCode": "NO",
        "postalName": "Oslo",
        "zipCode": "0480",
        "address": "Sandakerveien 121",
        "phone1": "12345678"
      }
    ],
    "items": [
      {
        "itemNumber": 1,
        "weight": 1000,
        "width": 12,
        "height": 12,
        "length": 12,
        "contents": "Shoes"
      }
    ]
  }'

Response (trimmed)

{
  "orderId": 89828037,
  "shipmentId": "(401)70724762337121945",
  "freightProductId": 1,
  "items": [
    {
      "itemNumber": 1,
      "trackingReference": "(00)370724762337121953"
    }
  ]
}

Save the shipmentId and trackingReference. When you use them in a URL in the next steps, remove the (401) and (00) prefixes.

Use an idempotency key

If the booking request times out or returns a 5xx error, retry it with the same idempotency-key . You will get the original booking back instead of a duplicate shipment. Use one unique key per shipment (max 40 characters, a UUID is recommended), and store it with your order before you send the request.

STEP 4: Print a label

Use Label endpoint to obtain a label for a parcel.

Request

curl -X GET "https://api.pre.helthjem.no/parcels/v1/labels/70724762337121945/unified-large" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/pdf" \
  -o label.pdf

The response is a PDF file with one 102 x 192 mm label per item in the shipment.

STEP 5: Track your delivery

Use Events tracking endpoint to retrieve tracking events on a parcel.

Request

curl -X GET "https://api.pre.helthjem.no/parcels/v1/tracking/fetch/70724762337121945/EN/false" \
  -H "Authorization: Bearer $TOKEN"

Response (trimmed)

[
  {
    "shipmentNumber": "70724762337121945",
    "shopId": 16,
    "items": [
      {
        "trackingNumber": "370724762337121953",
        "freightProductId": 1,
        "parcelStatus": "WAITING_FOR_PACKAGE",
        "events": [
          {
            "eventTime": "2025-10-13 13:46:07",
            "eventTimeUtc": "2025-10-13T11:46:07.028470Z",
            "eventType": {
              "apiKey": "001",
              "description": "Transport of parcel has been booked."
            }
          }
        ]
      }
    ]
  }
]

Each event has an apiKey that identifies what happened. See the tracking events reference for the meaning of each code.

Last updated Oct 9, 2026

Welcome

Environments