Liner Shipment

Each Liner-based shipments for issuers follow a similar approach whenever a shipment needs to be imported.

1. Liner JSON & cURL

The primary step for the issuers is to prepare appropriate JSON as per the relevant data and send it across Import Bol endpoint for further review. The primary parameters required for the Tanker JSON are

  • Import Reference [importRef]
  • Shipment, Parties & Routine information [cargos]
  • Transport & Cargo documentation [cargos]
  • Parcel Details [parcels]

📘

Parcel Details PDF

The [parcels] object with JSON have a tendency to contain PDF uploadable documents that are a part of a shipment. PDF document should be in Base64 format.

Here is the cURL prepared for the Liner.

curl --location --request POST 'https://api.test.essdatabridge.com/api/v1/shipments?importRef=SIN13072030' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJraWQiOiJPUUJmaXR6KzBWOFlxWFp3N2lHc1hlWjB5T2I3RTNyekpGWGZUYm9cL0M0Yz0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZGIwNWE4YS1jZjhjLTQ5ZTItYWYzYi0xZDdjZWUwZjJlOWQiLCJldmVudF9pZCI6IjNhMjNiMDRlLWU5ZGUtNDFkYi1hYjJlLTYwMGJlY2Y1NTg3MSIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE2NTc3Nzc4NTgsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC5ldS13ZXN0LTEuYW1hem9uYXdzLmNvbVwvZXUtd2VzdC0xX1drRmF1Q2tnUSIsImV4cCI6MTY1Nzc4MTQ1OCwiaWF0IjoxNjU3Nzc3ODU4LCJqdGkiOiI3YmQwZDI0OC1iYjVlLTRkNTUtOWRjOC0zNzNhNDg1OTE3NTMiLCJjbGllbnRfaWQiOiI3bzh0dDI4OWNvNHU5NnQ5bHQ1MnFyMnZxYSIsInVzZXJuYW1lIjoielJjbFVzZXIxIn0.NSuyrVWDvXyROKLgyLroeneU1ziMnLdfHkdET5IVG0RF9RIVLTZwudEJMFfVQcTdZSUmwseupiULY7LsXwHTpFQCp_7IDrL-Yy7hn33rE4ZlMeDV9ok5RaCKHpoqzqTXLuIHUy9VQCF_e4lu9PABkr6xUfSUmWGDIMLHRs5jZwCVnFSBA7eAW3TFyxMBEChvApgb_CfL5rcXm_7j7XXPiUq_nxIHrKk8ontJCq8X-4V_OMudIdn9EOMum8uLzOYngTwelxnUw59xAYZfjIo-5r2gSMY1dmIwj4VXzf8hHvNBMoSV5HXNTQgBQDdzKaSQJ7PNAOR6DcnLBAzZB0rajQ' \
--header 'Cookie: JSESSIONID=1AC237A6C47EDD5EDBB92904840B4B2B' \
--data-raw '
{
  "shipmentReference": "C-TEST-SIN13072030",
  "shipmentType": "liner",
  "autoCollaboration": false,
  "sets": [
    {
      "setRef": "CP-SIN000466999",
      "blNumber": "SIN000466999",
      "blDocumentName": "RCL BL",
      "blDate": "2022-04-20",
      "contractNumber": "P1900212022",
      "eSetType": "electronic",
      "placeOfReceipt": "MUNDRA, INDIA",
      "placeOfDelivery": "LATKRABANG, Thailand",
      "placeOfIssue": "Hongkong, China",
      "loadingLocation": "MUNDRA, INDIA",
      "destination": "LAEM CHABANG PORT",
      "destinationCountry": {
        "unCountryCode": "TH",
        "value": "Thailand"
      },
      "billOfLadingClause": "LADEN ON BOARD THE VESSEL",
      "notifyParties": [
        {
          "name": "KONGKIAT TEXTILE CO.,LTD.",
          "address": "19/19 MOO 3, THUMBOL BUA-LOY,AMPHUR NONG-KAE,SARABURI 18230,THAILAND",
          "code": "9999"
        }
      ],
      "carrier": {
        "scac": "",
        "name": "Carrier"
      },
      "shipper": {
        "name": "zExchange 10A",
        "id": "cf331720-9f3d-4eb5-b85d-8d9279663a6e",
        "code": "12345",
        "address": "Consignor Address"
      },
      "consignee": {
        "prefix": "TO THE ORDER ",
        "name": "zExchange 10B",
        "id": "53ac84ff-e98f-4b70-ad78-6b54a34a08d6",
        "code": "67890",
        "address": "Consignor Address"
      },
      "totalContainers": "1X20GP, 1X40HC CONTAINER (S) ONLY",
      "cargos": [
        {
          "cargoName": "Generic Liner Cargo",
          "cargoDescription": "04 X 40HC FCL 600 BALES INDIA RAW COTTON (BCI COTTON) TOTAL NET WEIGHT : 97.019 MTS",
          "marksAndNumbers": ""18/S/03755"",
          "quantities": [
            {
              "quantityGross": 1941185,
              "quantityNet": 1941185,
              "crossRefId": "12",
              "label": "Liters@15C"
            }
          ],
          "packaging": [
            {
              "numberOfPackingItems": 150,
              "packingUnit": "BALES",
              "weight": {
                "quantityGross": 24334.25,
                "quantityNet": 24334.25,
                "crossRefId": "KGM",
                "format": "###,###,###",
                "label": "KGS"
              },
              "volume": {
                "quantityGross": 50,
                "quantityNet": 50,
                "crossRefId": "M3",
                "format": "###,###,###",
                "label": "CBM"
              }
            },
            {
              "numberOfPackingItems": 150,
              "packingUnit": "PLASTIC BAGS",
              "weight": {
                "quantityGross": 24334.25,
                "quantityNet": 24334.25,
                "crossRefId": "KGM",
                "format": "###,###,###",
                "label": "KGS"
              },
              "volume": {
                "quantityGross": 50,
                "quantityNet": 50,
                "crossRefId": "M3",
                "format": "###,###,###",
                "label": "CBM"
              }
            },
            {
              "numberOfPackingItems": 300,
              "packingUnit": "WOOEDN CASES",
              "weight": {
                "quantityGross": 48668.5,
                "quantityNet": 48668.5,
                "crossRefId": "KGM",
                "format": "###,###,###",
                "label": "KGS"
              },
              "volume": {
                "quantityGross": 100,
                "quantityNet": 100,
                "crossRefId": "M3",
                "format": "###,###,###",
                "label": "CBM"
              }
            }
          ]
        }
      ],
      "numberOfContainers": 4,
      "containers": [
        {
          "containerNumber": "NYKU4396732",
          "containerType": "40HQ",
          "containerTypeDescription": "SOC",
          "packingUnit": "WOODEN CASES",
          "sealNumber": "3666451",
          "totalNumberOfPackingItems": 150,
          "containerQuantity": {
            "quantityGross": 24334.25,
            "quantityNet": 24334.25,
            "crossRefId": "KGM",
            "format": "###,###,000",
            "label": "KGS"
          },
          "containerVolume": {
            "quantityGross": 50,
            "quantityNet": 50,
            "crossRefId": "M3",
            "format": "###,###,###",
            "label": "M3"
          }
        },
        {
          "containerNumber": "TLLU4610477",
          "containerType": "40HQ",
          "containerTypeDescription": "SOC",
          "packingUnit": "WOODEN CASES",
          "sealNumber": "3666454",
          "totalNumberOfPackingItems": 150,
          "containerQuantity": {
            "quantityGross": 24334.25,
            "quantityNet": 24334.25,
            "crossRefId": "KGM",
            "format": "###,###,000",
            "label": "KGS"
          },
          "containerVolume": {
            "quantityGross": 50,
            "quantityNet": 50,
            "crossRefId": "M3",
            "format": "###,###,###",
            "label": "M3"
          }
        },
        {
          "containerNumber": "TRLU7601016",
          "containerType": "40HQ",
          "packingUnit": "WOODEN CASES",
          "sealNumber": "3666454",
          "totalNumberOfPackingItems": 150,
          "containerQuantity": {
            "quantityGross": 24334.25,
            "quantityNet": 24334.25,
            "crossRefId": "KGM",
            "format": "###,###,000",
            "label": "KGS"
          },
          "containerVolume": {
            "quantityGross": 50,
            "quantityNet": 50,
            "crossRefId": "M3",
            "format": "###,###,000",
            "label": "M3"
          }
        },
        {
          "containerNumber": "TRLU7452709",
          "containerType": "40HQ",
          "packingUnit": "WOODEN CASES",
          "sealNumber": "3666454",
          "totalNumberOfPackingItems": 150,
          "containerQuantity": {
            "quantityGross": 24334.25,
            "quantityNet": 24334.25,
            "crossRefId": "KGM",
            "format": "###,###,000",
            "label": "KGS"
          },
          "containerVolume": {
            "quantityGross": 50,
            "quantityNet": 50,
            "crossRefId": "M3",
            "format": "###,###,###",
            "label": "M3"
          }
        }
      ],
      "freightCharges": {
        "paymentLocationPrepaid": "Singapore",
        "paymentLocationCollect": "London",
        "charges": [
          {
            "code": "OFT",
            "tariffItem": "FREIGHT 1",
            "freightedAs": "1/20GP",
            "rate": 550,
            "amount": {
              "currency": "USD",
              "value": 550
            },
            "prepaidType": "PREPAID",
            "exchangeRate": "SGD/1.310200"
          },
          {
            "code": "THD",
            "tariffItem": "TERMINAL",
            "freightedAs": "1",
            "rate": 2800,
            "amount": {
              "currency": "THB",
              "value": 2800
            },
            "prepaidType": "COLLECT",
            "exchangeRate": "THB/1.000000"
          },
          {
            "code": "DOC",
            "tariffItem": "DOC FEE",
            "freightedAs": "1.000",
            "rate": 1200,
            "amount": {
              "currency": "AUD",
              "value": 1200
            },
            "prepaidType": "PREPAID",
            "exchangeRate": "AUD/1.000000"
          },
          {
            "code": "DOF",
            "tariffItem": "DOC FEE",
            "freightedAs": "1.000",
            "rate": 1200,
            "amount": {
              "currency": "AUD",
              "value": 120
            },
            "prepaidType": "PREPAID",
            "exchangeRate": "AUD/1.000000"
          },
          {
            "code": "CCC",
            "tariffItem": "COLLECTION OF",
            "freightedAs": "1.000",
            "rate": 225,
            "amount": {
              "currency": "THB",
              "value": 225
            },
            "prepaidType": "COLLECT",
            "exchangeRate": "AUD/1.000000"
          }
        ],
        "chargeTotals": [
          {
            "amount": {
              "currency": "AUD",
              "value": 90
            },
            "paymentType": "PREPAID"
          },
          {
            "amount": {
              "currency": "USD",
              "value": 550
            },
            "paymentType": "PREPAID"
          },
          {
            "amount": {
              "currency": "THB",
              "value": 4225
            },
            "paymentType": "COLLECT"
          }
        ],
        "prepaidTotals": [
          {
            "amount": {
              "currency": "AUD",
              "value": 90
            },
            "location": "SYDNEY, NSW"
          },
          {
            "amount": {
              "currency": "SGD",
              "value": 720.62
            },
            "location": "SINGAPORE"
          }
        ]
      }
    }
  ],
  "externalReference": "ABCDEFGHIJKLMNOPQRSTUV",
  "locale": "ENGLISH",
  "quantityFormat": "###,##0.000",
  "vessel": {
    "imo": 1234567
  },
  "voyageReference": "Voyage Ref 110E",
  "exportReference": "ABCDEFGHIJKL",
  "shipAgent": {
    "name": "ONE",
    "crossRefId": "ONEY"
  },
  "freightForwarder": {
    "name": "freightForwarder",
    "address": "Adress for FreightForwarder"
  },
  "inspector": {
    "name": "ONE_INSPECTOR",
    "address": "Adress for Inspector",
    "crossRefId": "ONE_INSPECTOR"
  },
  "serviceTypeAtReceipt": "CY",
  "serviceTypeAtDelivery": "CY",
  "loadType": "FCL"
}
'

A successful 200 response looks like this.

2. Review Shipment

Once the shipment is imported successfully, the parcel needs to be viewed in DocHub however for Liner, it needs to be signed and issued from DocEx for further processing. Here are step-by-step guidelines.

  1. The imported shipment will be visible in DocHub & DocEx, however further processing is done within DocEx.

  1. Shipment details can be seen below.

  1. Documents within the shipment can be seen below and are actionable in DocEx as depicted in further screenshots.

  1. The eBoL can be reviewed or edited here if required. Once changes are done, the updates can be saved.

  1. Here is how an eBoL looks in its preview state or printable format.

  1. Documents log in to be finalized under a shipment before the shipment can be further processed.

  1. To Sign & Issue the shipment, the user needs to log in to DocEx. The imported shipment would be visible in the list of available shipments under INBOX. Each shipment will have the eSet available within the preview panel. The eBoL will have Sign and Reject options to proceed further.

  1. A shipment needs to be Sign & Issue to get processed. Users can initiate the process by clicking on Sign button as depicted in the below screenshot. The existing status of the shipment will be set to Signing.

  1. Once user proceeds with signing, the authorization is required which is performed providing authentication username and password.

  1. Once the process is completed, the user will be prompted with a success message and the status of the shipment would be changed to Signed.

  1. Once a shipment is Signed, the next step is to Issue the shipment. The Issue action would be visible to the user against the selected shipment.

  1. The User gets an option to select the recipients against whom the shipments are to be issued.

  1. Authorization is a mandatory step in issuing the shipment. The authorized user needs to enter his credentials to process the shipment further.

  1. Upon successful issuance, a pop-up is displayed as a confirmation.

  1. An issued shipment will be visible under Filed tab with Issued status.

3. Retrieve MQ Details for PDF Download

Once the shipment is issued, the associated Customer queue gets a notification from DocEx instance. Please refer Queue Messages for more details on each parameter available within the queue. Subscribe to RabbitMQ - Sample Code provides a JAVA-based sample code to show how these kinds of RabbitMQ can be subscribed to receive instant notifications.

{
   "actor":"zCarrier5User1",
   "actorCompany":"zCarrier 5",
   "instance":"DocEx",
   "newStatus":"ISSUED",
   "parcelReference":"P-1",
   "customerId":"0a2c03a9-44e4-11e9-9ed6-0a24491b68de",
   "action":"Sign",
   "setId":"b9f77363-4fd8-42c8-b248-36a4628ca118",
   "updatedDate":"Mon May 16 15:05:02 UTC 2022",
   "message":"The set status has been updated",
   "transactionId":"18f3f989-8f2c-49ec-a2b6-efab51868998"
}