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-11-01 10:33:18 UTC.

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

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

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

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:

• option-logos shows a small Postnord logo for each shipping option, instead of one big logo as header above the options.

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:

• The integrators checkout initiates and has a session ID.
• Integrator backend calls the [API_URL]/create-session endpoint to create a PostNord session with the provided recipient and cart details. This session ID is needed to initialize the shipping widget.
• When the Shipping Widget is loaded, the onLoaded event listener triggered. This can be used to notify the checkout or any other component that the shipping widget is ready for use.
• When the checkout is initialized and the Shipping Widget is loaded the widgets calls [API_URL]/shipping-options/[session_id] to fetch all available shipping options for the store connection assosiacted with the session
• One of the returned options has an isSelected flag to indicate the default selected option. When the session is not new it will be the last selected option in this session

Update session:

• If something changes in the receiver data (any of the fields in the session data) the update-session endpoint should be called with the new data.
• When the update-session endpoint resolves succefully a sessionHasUpdated call to the shipping module should be fired.
• The shipping module will then suspend, reload the available shipping options and then resume.

Selecting a shipping option:

• When selecting one of the options the Shipping Widget posts the selected option ID to the [API_URL]/shipping-options/[session_id] endpoint. It can optionally also contain a selected service point ID (same for service points and parcel lockers).
• When the update call to the PostNord API is finished, the onShippingUpdated event listener is triggered. This can be used to notify the checkout component that the selected shipping option has succesfully changed.
• The checkout component re-fetches the session after selecting a shipping option, to re-fetch the session and get the latest shipping prices.

Completing a session:

• After completing the checkout the integrators backend calls [API_URL]/complete-session/[session_id] to end the 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"
    }
}'