Sign in

nShift Help Center

Container API

Avatar
Malene Tidemann
Updated

 

 

Environments | {{URL}}

https://customer-api.consignorportal.com/ApiGateway/Containers

This is a REST API and can only be used for sending/receiving requests so is not meant to be opened in a browser.

 

 

Authentication

The API support Bearer Authentication
See this article on how to generate the ClientId and ClientSecret

 

Example on how to request a token

curl -X POST "https://www.consignorportal.com/idsrv/connect/token" 
--header "Content-Type: application/x-www-form-urlencoded" 
--data-urlencode "grant_type=client_credentials" 
--data-urlencode "client_id={{CLIENT_ID}}" 
--data-urlencode "client_secret={{CLIENT_SECRET}}"

Response

{
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjI3QjA1ODk4Nzc1OEUwMkMI1NiIsInR2...",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "public_api_shipmentserver"
}

The Token is valid for 60 minutes before it expires and you have to re-authenticate

 

All request has to have the token in the Authorization header

curl -X POST "{{URL}}/ShipServer/ApiGateway/ShipmentData/" 
-H "Authorization: bearer {{TOKEN}}"
-H "Content-Type: application/json"
--data-raw "{}"

 

 

Postman Collection

This collection contains request & response examples for all requests:
https://documenter.getpostman.com/view/22736309/2s8YmHxQWK

In order to use these requests against your own configuration/actor you need to:

 

Bearer Token

  • Generate a CLIENT_ID & CLIENT_SECRET using this article:
    https://helpcenter.nshift.com/hc/en-us/articles/360026218413
  • Select the Environment DeliveryHUB API from the top right corner in Postman
  • Update the Initial & Current value on the variables in the selected environment:
    CLIENT_ID, CLIENT_SECRET
  • Remember to Save the Environment
  • Open the Authorization folder
  • Run the Authenticate request
  • Update any of the request and click Send

 

 

Note:
Check the pre-request section on each request to see the {{DATA}} and {{OPTIONS}} variables

 

 

 

API Index

 

 

GET Manage Get All Containers  ../Containers/Active
GET Manage Get Container By Identity ../Containers/Container
POST Manage Get Container Count ../Containers/Active/Count
POST Parent Create Parent ../Containers
POST Parent Close Parent ../Containers/:Uuid/Close
POST Parent Lock Parent ../Containers/:Uuid/Lock
POST Parent Unlock Parent ../Containers/:Uuid/Unlock
GET Parent Add Event To Parent ../Containers/:Uuid/Events
GET Parent Get Children From Parent ../Containers/:Uuid/Children
GET Parent Get Children Count From Parent ../Containers/:Uuid/Children/Count
PUT Child Add To Parent ../Containers/:Uuid
GET Child Get Parent From Child ../Containers/Children/:Identifier
GET Settings Get Owner Settings ../Containers/Settings
PUT Settings Update Owner Settings ../Containers/Settings

 

-

 

Manage | Get All Containers

Use this method to return all active first-level containers associated with the user context. In case of no active container, an empty response will be returned.

Container identifier is optional and can be provided in the URI { identifier }. If provided, the "starting with" filter will be applied to the string input.

 

Request

GET {{URL}}/Containers/Active
GET {{URL}}/Containers/Active?pageIndex=0
GET {{URL}}/Containers/Active?pageIndex=0&pageSize=15
GET {{URL}}/Containers/Active?identifier=40154685321354
GET {{URL}}/Containers/Active?pageIndex=0&identifier=40154685321354
GET {{URL}}/Containers/Active?pageIndex=0&pageSize=15&identifier=40154685321354
  • pageSize: int - optional field. ( default value 50. Maximum value 50 )
  • pageIndex: int - optional field
  • identifier: string - optional field

 

-

 

Manage | Get Container By Identity

Use this method to retrieve containers by identifier or UUID and active status. By default, the search will be done only based on active containers. In case you also want to get the inactive containers, you should use the "active" parameter with a false value.

In case no container was found based on the searching criteria provided, HttpStatus code 200 OK will be received with an empty body.

 

Request

GET {{URL}}/Containers/Container?identifier&active
GET {{URL}}/Containers/Container?uuid&active
  • identifier: string - optional parameter
  • uuid: string - optional parameter
  • active: bool - optional parameter; default value true

 

-

 

Manage | Get Container Count

Get the total number of first-level active containers associated with the user context within the specified date range. The date filter will be applied considering the UTC date value greater or equal to startdate and less than enddate.

 

Request

GET {{URL}}/Containers/Active/Count

Body

{
   "startDate": "2022-03-01T00:33:02.991",
   "endDate": "2022-06-16T13:33:02.991"
}
  • startData: Iso8601datetime
  • endDate: Iso8601datetime

 

-

 

Parent | Create Container

Will create the container and return the unique identifiers.

 

Request

POST {{URL}}/Containers

Body

{
    "ParentIdentifier": "{{$randomUUID}}",
    "ChildrenIdentifier": [
        "{{CHILD_SHIPMENTNUMBER_1}}",
        "{{CHILD_SHIPMENTNUMBER_2}}"
    ],
    "DateCreated": "2022-06-16T13:33:02.991",
    "IsVirtualParent": true,
    "MaxDaysOld": 10,
    "EventCode": "111"

}
  • ParentIdentifier: string - the id of the container.
    if IsVirtualParent is false then a shipment number or package number is used.
    If isVirtualParent is true then a Uuid or other unique string is used. 
  • ChildrenIdentifier: [string] - the id's of the children
  • DateCreated: datetime
  • IsVirtualParent: bool
  • MaxDaysOld: int
  • EventCode: string

 

-

 

Parent | Close Container

Use this method in order to close and update the relationship for all the connected children. Once the tree is closed, no more children can be added to the container.

 

Request

POST {{URL}}/Containers/:Uuid/Close
  • Uuid: string

 

-

 

Parent | Lock Container

Use this method to lock a virtual container. Once the container is locked, no children can be added to the container with the “Add Children to Container” method. A new container should be created using the “Create Container” method. The "Create container" method will not be allowed if there is another not locked container for the same template. Only one virtual container per template at a time can be locked.

Only virtual active containers created by the owner that is initiating the request can be locked. In case of at least one criteria not being met BadRequest will be returned.

If the operation succeeded HttpStatus code 200 OK will be received with an empty body.

 

Request

POST {{URL}}/Containers/:Uuid/Lock
  • Uuid: string

 

-

 

Parent | Unlock Container

Use the method to unlock a virtual active container.

Once the container is unlocked, children can be added to the container with “Add Children to Container” method.

A virtual container can be unlocked only if there is no other virtual container with the same template not locked. Only virtual active containers created by the owner that is initiating the request can be unlocked. In case of at least one criteria not being met BadRequest will be returned.

If the operation succeeded HttpStatus code 200 OK will be received with an empty body.

 

Request

POST {{URL}}/Containers/:Uuid/Unlock
  • Uuid: string

 

-

 

Parent | Add Event

Use this method to send an event to a container and its linked children. The event will be propagated to all-level children. In case of a closing event (defined on the event), the status of the container will be set to "Closed" (since all children would be considered closed, the container will also be automatically closed). ParentUuid will be provided in the URL. EventCode is mandatory.

 

Request

GET {{URL}}/Containers/:Uuid/Events

Body

{
  "EventCode": "111",
  "DateCreated": "2022-06-16T13:33:02.991"
}
  • EventCode: String
  • DateCreated: Iso8601datetime

 

-

 

Parent | Get Children

Use this method to get the list of level 1 children.
HasChildren will be set to true in case they have children, otherwise, it will be set to false.

 

Request

GET {{URL}}/Containers/:Uuid/Children
  • Uuid: string

 

-

 

Parent | Get Children Count

Use this method to get the list of level 1 children.
HasChildren will be set to true in case they have children, otherwise, it will be set to false.

 

Request

GET {{URL}}/Containers/:Uuid/Children/Count
  • Uuid: string

 

-

 

Child | Add

Use this method to add one or more children to an existing container.

If EventCode is provided, this will propagate the event to any children attached to the container.

 

Request

PUT {{URL}}/Containers/:Uuid

Body

{
    "ChildrenIdentifier": [
        "{{CHILD_SHIPMENTNUMBER_3}}"
    ],
    "DateCreated": "2022-06-16T13:33:02.991",
    "MaxDaysOld": 15,
    "EventCode": "111"
}
  • ChildrenIdentifier: [string]
  • DateCreated: datetime
  • MaxDaysOld: int
  • EventCode: string

 

-

 

Child | Get Parent

Use this method to get the active parent of an active child based on the child identifier. In case of no active container, an empty response will be returned.

 

Request

GET {{URL}}/Containers/Children/:Identifier
  • Identifier: string

 

-

 

Settings | Get Owner Settings

Use this method to get the configured container settings for the owner.
In case the user is not ADMIN (carrier, customer) or OWNER (carrier, customer) Forbidden will be returned. If the user or owner is not correctly configured in User Management, Bad Request will be returned. If the operation succeeded, HttpStatus code 200 OK will be received containing the settings for the user's owner.

 

Request

GET {{URL}}/Containers/Settings

 

-

 

Settings | Update Owner Settings

Use the Add or update owner settings method to save or update settings for a user's owner.
In case the user is not ADMIN (carrier, customer) or OWNER (carrier, customer), Forbidden will be returned.
In case the user or owner is not correctly configured in User Management, Bad Request will be returned.
In case the operation succeeded HttpStatus code 200 OK will be received containing an empty response.

 

Request

PUT {{URL}}/Containers/Settings

Body

{
    "ClosingOption": false
}
  • ClosingOption: bool

 

If set ClosingOption = false no events will be propagated.

Will break the relation with his parent (if it’s middle level and trigger the closing up in the tree)

  • If there is one level down => the relation will be broken (considered delivered) and no events will be propagated
  • If there are more than one level down => the relation will not be broken and no events will be propagated and the tree will travel independently

If set ClosingOption = true will break the relation down (and trigger the closing up in the tree) and propagate the events to children

 

Related articles