Welcome to the publicly accessible files, demo and documentation for the PostNord Shipping Module. To make sure that the shipping module used in your integration is always the latest version, please use direct links to the files listed below. The readme below the list provides information on how to implement the module. This page was generated on 2024-09-24 12:40:51 UTC.

{api-url}avarda-adapter.es?t=1727181651168

{api-url}postnord-shipping-module.es?t=1727181651168

{api-url}testsuite.es?t=1727181651168

DevMode is currently: {devmode-status}

Short Implementation Flow for devs

Scroll down for more details on the implementation, but in short the flow looks like this:

  1. Create a session by calling the create-session endpoint with the necessary payload and store the returned session ID on your side
  2. When data like the shipping address changes during this session, call the update-session endpoint with the updated data
  3. Load the shipping module script tag <script src="{api-url}/postnord-shipping-module.cjs" type="application/ecmascript" />
  4. Load the Shipping Module in the page <postnord-shipping-module language="en" session-id="[id]" /> with at least a language attr (en or se) and the session_id attr with the ID from step 1.
  5. When a shipping option is chosen this is stored in the session and also an onShippingUpdated event is fired.
  6. After a checkout is completed call the complete-session endpoint.

ShippingModule Component setup and usage

Add the webcomponent to a page by adding these lines to the body:

<!-- Add to body tag -->
<script 
  src="{api-url}/postnord-shipping-module.cjs"
  type="application/ecmascript">
</script>

<!-- Optional: integrator adapter file -->
<script 
  src="{api-url}/integrator-adaptor.cjs" 
  type="application/ecmascript">
</script>

<!-- Add to location where you want to render the shipping module -->
<postnord-shipping-module language="en" session-id="[id]"></postnord-shipping-module>

<!-- Optional: Event listeners -->
<script>
    const shippingModules = Array.from(document.getElementsByTagName('postnord-shipping-module'));

    // assign an event listener to each shipping module
    shippingModules.forEach((shippingModule) => {
        shippingModule.addEventListener("loaded", () => {
            console.log("[PostNord ShippingModule] onLoaded callback fired");
        });
        shippingModule.addEventListener("shippingUpdated", () => {
            console.log("[PostNord ShippingModule] onShippingUpdated callback fired");
        });
    });
</script>

Styling

The attribute external-styles accepts a JSON stringified object with the structure as found in the /src/styles/defaultStyles.ts file. Also a partial object can be sent in, since the code deep-merges the provided styles with the default styling object.

Settings

These settings are available as (non-value) attributes on the shipping module component:

language

Currently the shipping module support English (en) and Swedish (sv).

Session ID

Provide a valid session ID to the shipping module.

Modules

The modules prop can be used to pass a JSON stringified object containing extra data for the shipping module. Currently only sessionToken is supported and used to be sent in as Authorization key in all the API requests, if provided. The Auth key is returned by the create-session and update-session endpoint calls.

The session flow

Initialize session:

Update session:

Selecting a shipping option:

Completing a session:

PostNord API endpoint calls

Create Session:

curl --location '[API_URL]/create-session' \
--header 'Authorization: [KEY]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "purchaseId": "P1234",
    "language": "en-US",
    "checkoutSite": {
        "siteCode": "acmeSE",
        "countryCode": "SE",
        "currencyCode": "SEK"
    },
    "mode": 1,
    "items": [
        {
            "description": "Item 1 description",
            "amount": 50,
            "quantity": 3,
            "shippingParameters": {
                "width": null,
                "height": null,
                "length": null,
                "weight": null,
                "attributes": [
                    "something else"
                ]
            }
        }
    ],
    "deliveryAddress": {
        "address1": null,
        "address2": null,
        "street": null,
        "zip": "11451",
        "city": null,
        "type": null,
        "firstName": null,
        "lastName": null,
        "country": "SE"
    },
    "userInputs": {
        "email": "test@test.com",
        "phoneCountryTwoLetterIso": "SE",
        "phone": "+46123456789"
    }
}

Update session:

curl --location --request PUT '[API_URL]/update-session/[SESSION_ID]' \
--header 'Authorization: [KEY]' \
--header 'Content-Type: application/json' \
--data-raw '{
  "purchaseId": "string",
  "locale": "sv-SE",
  "mode": 0,
  "checkoutSite": {
    "siteCode": "acmeSE",
    "countryCode": "SE",
    "currencyCode": "SEK"
  },
  "items": [
    {
      "description": "Random Item",
      "notes": "string",
      "amount": 399.0,
      "taxCode": "25",
      "taxAmount": 79.8,
      "quantity": 1,
      "shippingParameters": null
    }
  ],
  "shippingSettings": {
    "vouchers": null,
    "attributes": null
  },
  "deliveryAddress": {
    "address1": "Address 12",
    "address2": "Acme Hotel",
    "street": "string",
    "houseNumber": "string",
    "zip": "11451",
    "city": "Stockholm",
    "type": "Company",
    "companyName": "Hello World",
    "firstName": "John",
    "lastName": "Doe",
    "country": "SE",
    "coordinates": {
      "lat": 0,
      "lng": 0
    }
  },
  "userInputs": {
    "email": "example@mail.com",
    "phoneCountryTwoLetterIso": "SE",
    "phone": "+46123456789"
  },
  "extraIdentifiers": {
    "orderReference": "ABCXYZ123"
  }
}'

Get Session:

curl --location '[API_URL]/get-session/[SESSION_ID]' \
--header 'Authorization: [KEY]' \
--data ''

Get shipping options:

curl --location '[API_URL]/shipping-options/[SESSION_ID]' \
--data ''

Set selected shipping option:

curl --location '[API_URL]/shipping-options/[SESSION_ID]' \
--header 'Content-Type: application/json' \
--data '{
    "shipmentOptionId": "[SHIPMEBNT_OPTION_ID]",
    "servicePointId": "[SERVICE_POINT_ID]", // this is optional, only for options with service point.
}'

Complete session:

curl --location --request PUT '[API_URL]/complete-session/[SESSION_ID]' \
--header 'Authorization: [KEY]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": "[SESSION_ID]",
    "checkoutSite": {
        "siteCode": "acmeSE",
        "countryCode": "SE",
        "currencyCode": "SEK"
    },
    "deliveryAddress": {
        "address1": "Strandvägen 1",
        "address2": "Apartment 123",
        "street": "hello",
        "zip": "11451",
        "city": "Stockholm",
        "type": "Private",
        "firstName": "First Name",
        "lastName": "Last Name",
        "country": "SE"
    },
    "userInputs": {
        "email": "receiver@email.com",
        "phoneCountryTwoLetterIso": "SE",
        "phone": "+46123456789"
    }
}'