Develop custom solution

This section clarifies how to develop and integrate your own tailor-made shipping broker with our Partner Shipping solution.

You will have to create:

• An API
• A Widget

API

In the subsequent sections of this guide, we will use the term ‘Implementor’ to refer to you, the one integrating with our system.

Avarda will provide the client API, and also define the design and structure of both the requests and responses.

As the Implementor, you will be tasked with the development of an API. This API will receive and process requests from Avarda. It is crucial that your API adheres strictly to the design and structure set forth by Avarda to facilitate seamless interaction between the two components. As the Implementor, your primary responsibilities will include receiving request data, processing it in alignment with Avarda’s design, and returning the suitable response.

Overview

The Implementor API must include:

• All required endpoints: The endpoints must adhere strictly to the names and contracts as detailed in this documentation.

  • create-session
  • update-session
  • complete-session
  • get-session

• A single base URL for all required endpoints: customization, such as versioning, is permitted for the base URL, provided it remains consistent across all required endpoints.

• Bearer authorization: you will provide a secret for the customer that they will use in their Avarda checkout site configuration. Every request from the specific Avarda checkout site to your API will include this value in the authorization header, employing the bearer scheme.

View example of an implementation: https://partnershipping.azurewebsites.net/swagger (opens in a new tab)

create-session | required endpoint

This API endpoint is designated for initiating a new session, wherein a unique session ID must be generated by the Implementor. During this creation process, the Implementor should generate shipping options derived from the provided request data, which should be stored with some reference to the session. As the user has not yet interacted to select a shipping option, the response can include a pre-selected shipping option or remain void of any shipping selection.

Swagger example: https://partnershipping.azurewebsites.net/swagger/index.html#/Api/Api_CreateSession (opens in a new tab)

POST: {implementor_base_url}/create-session
Authorization: Bearer {access_token} // Implementor provides this token

Request body

{
  "purchaseId": "string",
  "locale": "sv-SE",
  "mode": 0, // B2C = 0, B2B = 1
  "checkoutSite": {
    "siteCode": "acmeSE",
    "countryCode": "SE",
    "currencyCode": "SEK"
  },
  "items": [
    {
      "description": "Random Item",
      "notes": "string",
      "amount": 399.0,
      "taxCode": "25",
      "taxAmount": 79.8,
      "quantity": 1,
      "shippingParameters": {
        "height": 1000,
        "length": 1000,
        "width": 100,
        "weight": 400,
        "attributes": ["string"]
      }
    }
  ],
  "shippingSettings": {
    "vouchers": ["string"],
    "attributes": ["string"]
  },
  "deliveryAddress": {
    "address1": "Address 12",
    "address2": "Acme Hotel",
    "street": "string",
    "houseNumber": "string",
    "zip": "12345",
    "city": "Stockholm",
    "type": "Private",
    "firstName": "Sven",
    "lastName": "Svensson",
    "country": "SE",
    "coordinates": {
      "lat": 0,
      "lng": 0
    }
  },
  "userInputs": {
    "email": "example@mail.com",
    "phoneCountryTwoLetterIso": "SE",
    "phone": "+46726417200"
  },
  "extraIdentifiers": {
    "orderReference": "string",
    "loyaltyNumber": "string",
    "productGroup": "string",
    "attachment": "string",
    "description": "string",
    "referenceName": "string"
  }
}

Response body

{
  "id": "unique-implementor-session-id-123",
  "status": "ACTIVE",
  "expiresAt": "2023-07-13T11:30:54.8018377+00:00",
  "selectedShippingOption": {
    "shippingMethod": "pn-pp123",
    "deliveryType": "pickup",
    "carrier": "PostNord",
    "product": "Postal Parcel",
    "price": 15,
    "currency": "SEK"
  },
  "modules": "string"
}

update-session | required endpoint

This API endpoint is utilized to modify an existing session. The update operation includes the session ID (that Implementor generated during create-session), which is passed in both the route and the request body as “id”. As part of this update process, you are required to update the shipping options, taking into account the information present in the request body.

Swagger example: https://partnershipping.azurewebsites.net/swagger/index.html#/Api/Api_UpdateSession (opens in a new tab)

PUT: {implementor_base_url}/update-session/{id}
Authorization: Bearer {access_token} // Implementor provides this token

Request body

{
  "id": "unique-implementor-session-id-123",
  "purchaseId": "string",
  "locale": "sv-SE",
  "mode": 0, // B2C = 0, B2B = 1
  "checkoutSite": {
    "siteCode": "acmeSE",
    "countryCode": "SE",
    "currencyCode": "SEK"
  },
  "items": [
    {
      "description": "string",
      "notes": "string",
      "amount": 0,
      "taxCode": "string",
      "taxAmount": 0,
      "quantity": 0,
      "shippingParameters": {
        "height": 0,
        "length": 0,
        "width": 0,
        "weight": 0,
        "attributes": ["string"]
      }
    }
  ],
  "shippingSettings": {
    "vouchers": ["string"],
    "attributes": ["string"]
  },
  "deliveryAddress": {
    "address1": "string",
    "address2": "string",
    "street": "string",
    "houseNumber": "string",
    "zip": "string",
    "city": "string",
    "type": "string",
    "firstName": "string",
    "lastName": "string",
    "country": "SE",
    "coordinates": {
      "lat": 0,
      "lng": 0
    }
  },
  "userInputs": {
    "email": "string",
    "phoneCountryTwoLetterIso": "SE",
    "phone": "string"
  },
  "extraIdentifiers": {
    "orderReference": "string",
    "loyaltyNumber": "string",
    "productGroup": "string",
    "attachment": "string",
    "description": "string",
    "referenceName": "string"
  }
}

Response body

{
  "id": "unique-implementor-session-id-123",
  "status": "ACTIVE",
  "expiresAt": "2023-07-13T11:30:54.8018377+00:00",
  "selectedShippingOption": {
    "shippingMethod": "string",
    "deliveryType": "string",
    "carrier": "string",
    "product": "string",
    "price": 0,
    "currency": "SEK"
  },
  "modules": "string"
}

complete-session | required endpoint

This API endpoint is designated for finalizing an existing session. The completion operation includes the session ID (that Implementor generated during create-session), which is passed in both the route and the request body as “id”.

As part of the completion procedure, a transport ID must be generated by the Implementor and saved within the session. After a successful completion, Avarda will not make any further updates to the shipping session.

Swagger example: https://partnershipping.azurewebsites.net/swagger/index.html#/Api/Api_CompleteSession (opens in a new tab)

PUT: {implementor_base_url}/complete-session/{id}
Authorization: Bearer {access_token} // Implementor provides this token

Request body

{
  "id": "unique-implementor-session-id-123",
  "deliveryAddress": {
    "address1": "string",
    "address2": "string",
    "street": "string",
    "houseNumber": "string",
    "zip": "string",
    "city": "string",
    "type": "string",
    "firstName": "string",
    "lastName": "string",
    "country": "SE",
    "coordinates": {
      "lat": 0,
      "lng": 0
    }
  },
  "userInputs": {
    "email": "string",
    "phoneCountryTwoLetterIso": "string",
    "phone": "string"
  }
}

Response body

{
  "id": "unique-implementor-session-id-123",
  "status": "COMPLETED",
  "transportId": "unique-implementor-transport-id-123",
  "expiresAt": "2023-07-13T11:30:54.8018377+00:00",
  "selectedShippingOption": {
    "shippingMethod": "string",
    "deliveryType": "string",
    "carrier": "string",
    "product": "string",
    "price": 0,
    "currency": "SEK"
  },
  "modules": "string"
}

get-session | required endpoint

This API endpoint is purposed for retrieving an existing session, encompassing both active and completed sessions. The get operation includes the session ID (that Implementor generated during create-session), which is passed in both the route and the request body as “id”.

Swagger example: https://partnershipping.azurewebsites.net/swagger/index.html#/Api/Api_GetSession (opens in a new tab)

GET: {implementor_base_url}/get-session/{id}
Authorization: Bearer {access_token} // Implementor provides this token

Request body

Empty

Response body

{
  "id": "unique-implementor-session-id-123",
  "status": "string",
  "transportId": "string",
  "expiresAt": "2023-07-13T11:30:54.8018377+00:00",
  "selectedShippingOption": {
    "shippingMethod": "string",
    "deliveryType": "string",
    "carrier": "string",
    "product": "string",
    "price": 0,
    "currency": "SEK"
  },
  "modules": "string"
}

Object Reference

Mode

DeliveryAddressType

Coordinates

CheckoutSite

Item

ShippingParameters

ShippingSettings

DeliveryAddress

UserInputs

ExtraIdentifiers

SelectedShippingOption

Widget

Register an interface called avardaShipping globally available on window object. This interface defines a set of methods for interacting with a shipping module. It includes methods for initializing the module, suspending and resuming its operation, registering event listeners, and unmounting the module.

• init: Initialize widget inside the provided HTMLElement. Use session_id for rendering a correct shipping session. Use any modules data previously provided from create-session response, CustomStyles object for styling of the widget and language for selecting the same language as in the Checkout Form.

  • It should be possible to call init even after it was previously called.

• unmount: Remove the shipping module from the page.

  • Module should be removed from the page and only a new init call should again make it visible.

• suspend: Based on actions in Checkout – have ability to suspend the module to prevent any interaction from the user in the browser.

• resume: Opposite of suspend

• on: Allows us to attach event listener on the avardaShipping object, with specific type

• dispatchEvent: Required for dispatching events that will be handled by Checkout Form

• setLanguage: Change language to selected language by the Checkout. Language string will contain ISO 639 – 2 letter language code of one of the supported languages of Checkout.

• sessionHasUpdated: When the shipping session has updated (due to change in delivery address - country, zip, etc.) this function will be called, check the status of the shipping and trigger shipping_option_changed if necessary.

It is required that the interface implements EventTarget interface to allow attaching and removing EventListeners and dispatching Event or CustomEvent.

Expected type contract

declare global {
  interface Window {
    avardaShipping?: AvardaShippingApi;
  }
}
 
export type CustomStyles = {
  fontFamily: string[];
  label: { selectedColor: string; unselectedColor: string };
  radio: { selectedColor: string; unselectedColor: string };
  borderRadius: number;
  amountColor: string;
};
 
export type Config = {
  modules: object | null;
  styles: CustomStyles | null;
  language: string;
  locale: string;
}
 
export type AvardaShippingInitObject = {
  element : HTMLElement;
  session_id: string;
  config: Config;
}
 
export interface AvardaShippingApi {
  init: (initObject:AvardaShippingInitObject) => void;
  suspend: () => void;
  resume: () => void;
  on(
    type: string,
    listener: EventListenerOrEventListenerObject,
    options?: boolean | AddEventListenerOptions
  ): void;
  dispatchEvent(event:Event) => boolean;
  unmount: () => void;
  setLanguage: (language:string) => void;
  sessionHasUpdated: () => void;
};

Checkout application is using WebComponent and ShadowDOM additionally, we also use WebComponent and ShadowDOM for the shipping module to prevent any unintentional leaking of CSS etc. To achieve this, we create a custom WebComponent on our side with all necessary work around it – and provide an HTMLElement in the init function.

Events

After the module is loaded into the page, we will attach 2 event listeners to the AvardaShippingApi

window.avardaShipping?.on('loaded', () => {
  // Checkout3 handles the event
});

window.avardaShipping?.on('shipping_option_changed', () => {
  // Checkout3 handles the event
});