Core API dev guides

Container

25min

Introduction to Containers
In the context of logistics, a Container is a physical component with a unique ID. It is the smallest entity unit to represent a shipment. In other words, a Container is an identifier of one or more physical boxes (or items﻿), including the Containers themselves.
All physical items within a Container are identified by their individual scannable IDs externally but they all also share the Container’s scannable ID. Every Container has its own  lifecycle﻿ and set of Attributes﻿.
The process of grouping multiple Containers together into one Container is called containerization﻿; the opposite of this is de-containerization.
In the event that a Container is added to another Container, the relationship becomes a parent-child relationship. In this case, the Container which is housing the other Container is the parent. A Container might or might not have children.
A Container marked as a leaf Container will only contain items in it. Moreover, a Container can be automatically or manually disposed of if required.
Before diving into the types of Containers, let's understand what an item is.
What is an Item?
An item is an atomic (indivisible) physical object that does not contain any items or objects within. An item might or might not have a tracking ID.
An item can have the following properties:
Name: Name of the item (example: Microfibre Reversible Quilt Blanket).
Description: A short description of the item (example: Microfibre reversible quilt blanket for a single bed (120 GSM) in walnut brown color).
Cost: Total money that you have to pay for the item. Amount (float with 2 precision points) & Currency (string).
Quantity: The total number of items (default value: 1).
Measurement:
Value: A number quantifying measurement
Unit: A unit of measurement (cm/m/L/mL).
For a quick start guide on creating Containers, see Creating Containers.
Types of Container
Containers are the structures that store various items that need to be moved from point A to point B using. Some of the Container types are:
Bag
Package
Pallet
Trolley
Box
The Platform Tenant has the option to modify the custom Attributes of the default Container types and/or create additional Container types. In configurations, the Tenant will need to define the size(s) that each Container type can take and also if the particular Container is reusable.
Creating a Container Type
To create a Container Type, call the Create a new container type endpoint and pass the following parameters in the request body:
Member
Description
Validation
Data type
name
A unique name that represents a Container of this Container type
pattern: ^[a-zA-Z]{3,16}$   minLength: 3   
maxLength: 64   
example: bag
string
isLeaf
Defines whether this container-type will have actual physical items or not. Such types of Containers are termed leaf Containers.
default: false
boolean
allowedParent
Rules defining the allowed Container types as the parent of a Container type.
minProperties: 1
﻿
oneOf
List of Container types allowed as the parent of this Container type.
minItems: 1   
maxItems: 16  
 pattern: ^[a-z]{1,16}$   minLength: 3   
maxLength: 64
string
callback
Specifies a callback URL that is used to notify the calling of the result status of the call.
pattern: https?:\/\/(www\.)?[-a-zA-Z0-9@:%.\+~#=]{2,256}\.[a-z]{2,4}\b([-a-zA-Z0-9@:%\+.~#?&//=]*)
string
entityCode
Unique code of an entity.
pattern: ^(?!0000^$)([0-9][0-9][0-9][0-9])$
string
🚧 NOTE﻿
After a Container type is created it cannot be deleted and its name and isLeafattributes are immutable.
Request bodies are specified in JSON format. The following examples show a request body for creating a Container Type and a request body for updating a Container Type:
Create Container Type
Update Container Type
{
  "name": "bag",
  "isLeaf": false,
  "allowedParent": {
    "oneOf": [
      "trolley"
    ],
    "not": [
      "bag"
    ]
  },
  {
   "ttl": "99d",
    "callback": {
        "url": "https://examplecallbackurl.com",
        "meta": {
            "key1": "Post ptp type"// Optional. Meta object can not exceed 256 Bytes.
        }
    }
}
  "entityCode": "E-0001"
}
{
  "name": "bag",
  "isLeaf": false,
  "allowedParent": {
    "oneOf": [
      "trolley"
    ],
    "not": [
      "bag"
    ]
  },
  {
   "ttl": "99d",
    "callback": {
        "url": "https://examplecallbackurl.com",
        "meta": {
            "key1": "Post ptp type"// Optional. Meta object can not exceed 256 Bytes.
        }
    }
}
  "entityCode": "E-0001"
}
﻿
Attributes of a Container
Attributes of a Container can be divided into one of the following categories:
Base: These are the attributes mandated by the platform for the Container. Some of these attributes are mandatory.
Custom: These are the attributes that the Tenant defines for the Containers, to enhance their usability.
Tenants can define custom validations, and also specify for them to be indexed (if it is to be used in filtering APIs) or non-indexed.
In the case of a leaf Container, custom will have a mandatory attribute named items and non-leaf Containers will not be allowed to have this attribute.
Attribute Name
Category
Purpose
Data Type Expected
Tenant ID
Base
The ID of the tenant to whose data domain the Container belongs.
UUID
Container ID
Base
A system-generated unique ID for the Container.
VarChar
Scannable Tracking ID
Base
This is a physically affixed tracking ID (such as a Barcode) present on the Container for tracking it during a logistical process. This is to be used by the Tenant and Operators internally. There can be multiple barcodes on a Container, generated by the Client, the Operator, and the Tenant, and hence it will be stored as a list. The Participant ID of the creator of the code also needs to be stored with the tracking ID. This Tracking ID needs to be reusable. For Containers like Trolleys and Cold Storage Boxes, their tracking IDs will be reusable. Since multiple Containers may have sequentially used this tracking ID, a search on this tracking ID should return the Container that is in either Created, Opened, or Closed states (unless the completed Containers are specifically asked). The completed state would imply that the Container is no longer in use.
List
Container Type  (Optional)
Base
This is a type of Container in use by the Tenant. For example, “Bag” packed at a PC, “Box” carrying a Book purchased from Amazon.
VarChar
Parent Container ID  (Optional)
Base
The ID of the parent Container inside which this Container is placed.
VarChar
Is Hazmat  (Optional)
Base
Specifies whether the Container can contain hazardous materials or not. Default value: False.
Boolean
isContainerizable  (Optional)
Base
Specifies whether the Container can be put into other Containers. Default value: False.
Boolean
Attributes 1 to n (Indexed)
Custom
Custom attributes for a Container with indexing. The tenant will be able to configure validations, if required, for these attributes.
Key-value
Attributes 1 to n (Non-indexed)
Custom
Custom attributes for a Container without indexing. The tenant will be able to configure validations, if required, for these attributes.
Key-value
📘 NOTE﻿
Attributes such as the Capacity of a Container, or Container Temperature controlled, while essential to certain businesses, are not required to define a Container, and hence they have not been listed under Base attributes. The attributes can be defined in the Custom Attributes section by the Tenant if needed.
Creating a Container
To create a Container of a particular Container Type, call the Create a container﻿ endpoint and pass the following parameters in the request body:
Member
Description
Validation
Data type
trackingDetails
A tracking ID (such as AWB) for a Container is usually pasted on the Container and used for scanning it. There can be multiple tracking IDs for a Container, owned by different operators, and hence it will be stored as a list.
﻿
﻿
operator
Specifies the owner of the tracking ID.
minLength: 3   maxLength: 64   example: Delhivery
string
trackingId
ID to track the Container.
minLength: 1   maxLength: 128   example: 13212123
string
isPrimary
Indicates whether it is a primary tracking ID or not. If not defined, the first tracking ID is used as the primary tracking ID.
default: false
boolean
items
The list of items that can be added to a Container only if the Container type is a leaf.
﻿
﻿
cost
The cost of the item.
﻿
﻿
unit
The unit price of the item.
﻿
number
amount
The value of the amount - accurate up to three decimal places.
﻿
number
currency
Currency of the price of the item.
﻿
number
value
A number quantifying measurement.
﻿
integer
unit
Unit for measurement.
Valid values: cm, m, l, ml, nos, g, kg, mm.
string
attributes
A map to provide values for the attributes defined in Container-type configuration APIs.
﻿
﻿
isReusable
Indicates whether the Container is reusable.
default: false
boolean
isHazmat
Indicates whether this Container can contain hazardous materials.
default: false
boolean
callback
Specifies a callback URL that is used to notify the calling of the result status of the call.
pattern: https?://(www.)?[-a-zA-Z0-9@:%.\+~#=]{2,256}\.[a-z]{2,4}\b([-a-zA-Z0-9@:%\+.~#?&//=]*)
string
Request bodies are specified in JSON format. The following examples show a request body for creating a Container and a request body for updating a Container:
Create Container
Update Container
{
   "attributes":{
      "color":"red",
      "capacity.weight.max":77
   },
   "trackingDetails":[
      {
         "operator":"NationalLogistics",
         "trackingId":"PV691328537XD"
      }
   ],
   "isLeaf":false
}
{
   "attributes":{
      "color":"red",
      "capacity.weight.max":77
   },
   "trackingDetails":[
      {
         "operator":"NationalLogistics",
         "trackingId":"PV691328537XD"
      }
   ],
   "isLeaf":false
}
﻿
Creating Containers in a Batch
Batch processing helps to create and update the Containers in the batch. Batch processing supports two methods to supply the Container data:
JSON
CSV file upload
To create Containers in batch, call the Create Batch Request﻿ endpoint.
To update Containers in batch, call the Update Batch Request﻿ endpoint.
Attributes for Batch Request
Member
Description
Validation
Data Type
payload*
List of valid objects to create data in Containers.
maxItems: 1024   minItems: 1
﻿
refID*
Reference ID received for each container create request.
﻿
String
trackingDetails  (Optional)
Field to represent tracking ID (such as AWB) for a container which is usually pasted on the container and used for scanning it.   There can be multiple tracking IDs for a container, owned by different operators and hence it will be stored as a list
﻿
﻿
operator*
Field to specify the owner of the tracking ID.
minLength: 3   maxLength: 64   example: Delhivery
String
trackingId*
Tracking ID.
minLength: 1   maxLength: 128   example: 132121232423232
String
isPrimary
It defines whether it is a primary tracking ID or not. If none of the tracking details is set as primary we assume the first tracking ID as a primary tracking ID.
default: false
Boolean
attributes
(Optional)
A map to provide values for the attributes defined in Container-type configuration APIs.
﻿
﻿
items
(Optional)
List of items can be added to a container only if the container type is a leaf.
﻿
﻿
name*
Name of the item.
minLength: 3 maxLength: 128   example: Pant/shirt
String
code  
(Optional)
Code of the item.
minLength: 3 maxLength: 128
String
cost*
Cost of the item
﻿
﻿
unit
(Optional)
Represents unit price of the item.
﻿
﻿
amount
(Optional)
The value of the amount is accurate to three decimal places.
﻿
Number
currency
(Optional)
Currency of the price of the item.
﻿
String
total*
Represents the total price of the item.
﻿
﻿
amount  
(Optional)
The value of the amount is accurate to three decimal places.
﻿
Number
currency  (Optional)
Currency of the price of the item.
﻿
String
quantity  
(Optional)
﻿
﻿
﻿
quantity > value  
(Optional)
A quantifying number measurement.
﻿
Integer
quantity> unit  (Optional)
Unit for measurement.
​​Enum: [ cm, m, l, ml, nos, g, kg, mm ]
String
isHazmat  (Optional)
Represents whether this container can contain hazardous materials or not.
default: false
Boolean
isContainerizable  (Optional)
Defines whether containers can be put into other containers or not.
default: True
Boolean
callback  
(Optional)
Represents callback URL, which can be to notify status(success/failed) of API.
﻿
﻿
📘 NOTE﻿
The items marked (*) are mandatory attributes required while creating the Containers via batch processing.
The request bodies are specified in JSON format. The following examples show request bodies for creating and updating Containers in Batches.
Create Containers in Batch
Update Containers in Batch
{
    "payload": [
        {
            "containerId": "batch:3fe393b3-94d6-4fe6-b6e3-xxxxxxxxx", //Use actual ContainerID
            "data": {
                "trackingDetails": [
                    {
                        "operator": "mumbai",
                        "trackingId": "1321212324232327",
                        "isPrimary": false
                    }
                ],
                "attributes": {
                },
                "isHazmat": false,
                "isContainerizable": true
            }
        }
    ]
}
{
    "payload": [
        {
            "containerId": "batch:3fe393b3-94d6-4fe6-b6e3-xxxxxxxxx", //Use actual ContainerID
            "data": {
                "trackingDetails": [
                    {
                        "operator": "mumbai",
                        "trackingId": "1321212324232327",
                        "isPrimary": false
                    }
                ],
                "attributes": {
                },
                "isHazmat": false,
                "isContainerizable": true
            }
        }
    ]
}
﻿
👍 Container Batch Processing
A container can be created and updated in batch using Batch Processing API﻿.
Here are the sample CSV files for Batch Creation & Updation of Containers.
Creating Custom Attributes
Custom attributes can be created by specifying the following parameters:
To create Custom Attributes for a Container, call the Update Container Type Attributes and pass the following parameters in the request body:
﻿Custom Attributes﻿
Learn about Custom Attribute Entitlement Framework﻿﻿. 
Member
Description
Validation
Data type
name
Name of the attribute to add.
pattern: ^[a-zA-Z_]{1,32}$   
example: capacity
minLength: 3
maxLength: 64
string
dataType
Specifies the data type of the attribute. Valid values: string, number, boolean, object, array.
Valid values: string, number, boolean, object, array
string
description
Description of the attribute.
minLength: 1   
maxLength: 256
string
indexed
Specifies whether the attribute is indexed. Filter or search operation on the basis of a custom attribute will be only allowed if this field is set as TRUE.
﻿
boolean
isReadPublic
True: All apps can read the Custom Attributes.   
False (default): Only CAO and OTO will be able to read the Custom Attributes﻿. 
default: false
boolean
validation
Specifies the validations that are performed on the attribute when a Container of this type is created or updated.
﻿
﻿
range
Specifies the range that the attribute value must lie. In the case of the "string" data type, the range will be the length of the string value. [min: The min value, inclusive. max: The max value, inclusive.]
﻿
number
valueOneOf
Enum of accepted values.
minItems: 1
﻿
required
Specifies whether the value is required or optional.
default: false
boolean
callback
Specifies a callback URL that is used to notify the calling of the result status of the call.
pattern: https?:\/\/(www\.)?[-a-zA-Z0-9@:%.\+~#=]{2,256}\.[a-z]{2,4}\b([-a-zA-Z0-9@:%\+.~#?&//=]*)
string
Request bodies are specified in JSON format. The following examples show a request body for creating a Container and a request body for updating a Container:
JSON
{
  "attributes": [
    {
      "name": "capacity",
      "dataType": "string",
      "description": "volume-attribute",
      "tags": [
        "volume", "quantity"
      ],
      "indexed": true,
      "isReadPublic": false,
      "defaultValue": "four",
      "validation": {
        "range": {
          "min": 3,
          "max": 100
        },
        "valueOneOf": [
          "bag","box"
        ],
        "required": false
    }}
  ],
  {
    "callback": {
        "url": "https://examplecallbackurl.com",
        "meta": {
            "key1": "Post ptp type"// Optional. Meta object can not exceed 256 Bytes.
        }
    }
}
}
{
  "attributes": [
    {
      "name": "capacity",
      "dataType": "string",
      "description": "volume-attribute",
      "tags": [
        "volume", "quantity"
      ],
      "indexed": true,
      "isReadPublic": false,
      "defaultValue": "four",
      "validation": {
        "range": {
          "min": 3,
          "max": 100
        },
        "valueOneOf": [
          "bag","box"
        ],
        "required": false
    }}
  ],
  {
    "callback": {
        "url": "https://examplecallbackurl.com",
        "meta": {
            "key1": "Post ptp type"// Optional. Meta object can not exceed 256 Bytes.
        }
    }
}
}
﻿
📘 Important Note regarding Custom Attribute creation. ﻿
If the Attribute is already defined for the Container type, the validation rules are updated.
If the Attribute is not defined for the Container type, it is added as a new core attribute for the Container type.
On successful execution of the call, all updates including changes in data type take effect immediately for the Container type.
Lifecycle of a Container
The lifecycle depicts the current status of a Container. A Container typically can move between different states and substates, basis the workflows set in the application using it.
The platform will provide a default of four states for a Container:
Created: Specifies the creation of a Container. The system also generates a unique Container ID for the Container at this time.
Opened: Signifies readiness of Container to begin containerization operations (i.e. addition or removal of other Containers/packages/boxes/items). A Child Container cannot be “Opened” if the Parent Container is “Closed”.
Closed: Signifies termination of the containerization process; at this point, no further containers/packages/boxes/items may be added to the Container. A Parent Container cannot be “Closed” if a Child container is “Opened”.
Completed: End of the lifecycle of a Container. When a Container is de-containerized, the status of the Container will automatically shift to this state.
﻿
👍INFO﻿
﻿State Machine Service provides the Tenant an option to introduce sub-states under each of the States and the rules governing the corresponding state transitions.
Containerization
All physical items in a Container can be identified by their individual Tracking IDs but also share the Container’s Tracking ID. The process of grouping together boxes (or items or Containers) into a Container is called containerization; the opposite of this is de-containerization.
In the event that a Container is added to a Container, the relationship will be a parent-child relationship with the largest Container containing all other Containers (and their constituents) being the parent.
All operations performed on the parent Container are automatically inherited by the child Containers (e.g. all scan events on the parent Container are automatically propagated to the child Containers).
Conditions for Containerization
Parent Container state should be OPENED.
The child Container state should be CLOSED.
Parent Container should have isLeaf property as false.
Child Container should have isContainerizable as true.
Tenant Level Configurability and Extensibility
The Tenants have the following configurations available to them:
Attributes
Tenants have full control over defining Container types and the respective sizes for the Containers. For example, a bag can be 3x3 ft and 6x6 ft. They can also specify if a particular Container type is reusable.
Tenants can define a set of custom Indexed and Non-Indexed attributes for every Container type.
Tenants can define the duration after which they would like to move Inactive Containers to the data warehouse (default 72 hours).
The tenant can define whether the Container is a leaf Container (by using the isLeaf Base attribute). If the tenant defines a leaf Container, further, he has to define the “Items” attribute as a Custom Attribute.
Lifecycle
Tenants have the option to define a list of Event names for transition.
Tenants can define sub-states (i.e., custom lifecycle) for a particular container type.
For each State, Tenants have the option to define a set of sub-states and the corresponding rules for State transition as defined in the State Machine documentation.
Bulk Containerization/Decontainerization
Grouping together containers into a container. The container that goes inside another container is said to be containerized.
Attributes for Bulk Containerization
Bulk Containerization/Decontaizerization can be done by specifying the below-given attributes. Use the Bulk Containerization/Decontaizerization API endpoint.
Member
Description
Validation
Data type
parentId*
Field to represent container ID of the parent container. During the containerization process, this value is assigned to represent which container contains this container.
nullable: true   Example: box:9c9b1138-7cdd-11eb-9439-0242ac130002
string
childcontainerType*
Field to represent container type of the child containers.
Example: box
string
childIds*
Field to represent container IDs of the child containers.
Example: List [ "box:9c9b1138-7cdd-11eb-9439-0242ac130002", "box:9c9b1138-7cdd-11eb-9439-0242ac130003" ]
string
substate 
(Optional)
Field to represent substate of the closed to state to which the parent container has to be transitioned post containerization. Required in case of CONTAINERIZATION.
Example: closed
string
trackingDetails
(Optional)
Field to represent tracking ID (such as AWB) for a container which is usually pasted on the container and used for scanning it. There can be multiple tracking IDs for a container, owned by different operators and hence it will be stored as a list.
﻿
﻿
operator**
Field to specify the owner of the tracking ID.
minLength: 3   maxLength: 64  
example: Delhivery
string
trackingID**
﻿
minLength: 1   maxLength: 128  
example: 132121232423232
string
isPrimary
(Optional)
It defines whether it is a primary tracking id or not. If none of the tracking details are set as primary we assume the first tracking id is a primary tracking id.
default: false
boolean
attributes
A map to provide values for the attributes defined in Container-type configuration APIs.
﻿
﻿
items**
A list of items can be added to the container only if the container type is a leaf.
﻿
﻿
scannableID
(Optional)
﻿
﻿
string
isHazmat
Represents whether this container can contain hazardous materials or not.
default: false
boolean
isContainerizable
(Optional)
Defines whether a container can be put into other containers or not.
default: true
boolean
isReusable
(Optional)
Defines whether the container is re-usable or not.
default: false
boolean
action*
Field to represent an action to be performed on the container.
Enum:   CONTAINERIZE, DECONTAINERIZE   
example: CONTAINERIZE
string
callback 
(Optional)
﻿
example: https://delhivery.requestcatcher.com﻿
string (URI)
📘 Note﻿
*Mandatory fields for Bulk containerization/Decontainerization
**If ParantID is unavailable, then we create the parent instance and for the Parent instance, these attributes are required - else these are optional. 
Check how to implement Bulk Containerization/Decontainerization﻿.

Updated 08 Aug 2023

Did this page help you?

Participant

Dispatch

Docs powered by Archbee

TABLE OF CONTENTS

Introduction to Containers

What is an Item?

Types of Container

Creating a Container Type

Attributes of a Container

Creating a Container

Creating Containers in a Batch

Attributes for Batch Request

Creating Custom Attributes

Lifecycle of a Container

Containerization

Conditions for Containerization

Tenant Level Configurability and Extensibility

Attributes

Lifecycle

Bulk Containerization/Decontainerization

Attributes for Bulk Containerization

Member	Description	Validation	Data type
name	A unique name that represents a Container of this Container type	pattern: ^[a-zA-Z]{3,16}$ minLength: 3 maxLength: 64 example: bag	string
isLeaf	Defines whether this container-type will have actual physical items or not. Such types of Containers are termed leaf Containers.	default: false	boolean
allowedParent	Rules defining the allowed Container types as the parent of a Container type.	minProperties: 1
oneOf	List of Container types allowed as the parent of this Container type.	minItems: 1 maxItems: 16 pattern: ^[a-z]{1,16}$ minLength: 3 maxLength: 64	string
callback	Specifies a callback URL that is used to notify the calling of the result status of the call.	pattern: https?:\/\/(www\.)?[-a-zA-Z0-9@:%.\+~#=]{2,256}\.[a-z]{2,4}\b([-a-zA-Z0-9@:%\+.~#?&//=]*)	string
entityCode	Unique code of an entity.	pattern: ^(?!0000^$)([0-9][0-9][0-9][0-9])$	string

Attribute Name	Category	Purpose	Data Type Expected
Tenant ID	Base	The ID of the tenant to whose data domain the Container belongs.	UUID
Container ID	Base	A system-generated unique ID for the Container.	VarChar
Scannable Tracking ID	Base	This is a physically affixed tracking ID (such as a Barcode) present on the Container for tracking it during a logistical process. This is to be used by the Tenant and Operators internally. There can be multiple barcodes on a Container, generated by the Client, the Operator, and the Tenant, and hence it will be stored as a list. The Participant ID of the creator of the code also needs to be stored with the tracking ID. This Tracking ID needs to be reusable. For Containers like Trolleys and Cold Storage Boxes, their tracking IDs will be reusable. Since multiple Containers may have sequentially used this tracking ID, a search on this tracking ID should return the Container that is in either Created, Opened, or Closed states (unless the completed Containers are specifically asked). The completed state would imply that the Container is no longer in use.	List
Container Type (Optional)	Base	This is a type of Container in use by the Tenant. For example, “Bag” packed at a PC, “Box” carrying a Book purchased from Amazon.	VarChar
Parent Container ID (Optional)	Base	The ID of the parent Container inside which this Container is placed.	VarChar
Is Hazmat (Optional)	Base	Specifies whether the Container can contain hazardous materials or not. Default value: False.	Boolean
isContainerizable (Optional)	Base	Specifies whether the Container can be put into other Containers. Default value: False.	Boolean
Attributes 1 to n (Indexed)	Custom	Custom attributes for a Container with indexing. The tenant will be able to configure validations, if required, for these attributes.	Key-value
Attributes 1 to n (Non-indexed)	Custom	Custom attributes for a Container without indexing. The tenant will be able to configure validations, if required, for these attributes.	Key-value