TradeLens offers bulk document uploads and downloads using our open APIs. To use this functionality for document uploads follow the below steps.
In this article
Authentication and Token Generation
For API usage, authentication and token generation are required to be in place for systems integrating with the TradeLens platform. For example, a system user (program code) that calls the APIs.
Here is a link to the document site for TradeLens that explains the token generation: https://docs.tradelens.com/how_to/token_generation/
Setting up the Put Call
Call the PUT /api/v1/actionableDocFlows/bulk endpoint under Actionable Flows to upload the required documents. Executing this endpoint returns the bulkTransactionId
The body has the following Key/value pairs:
- documentsMetadata
- tradeObjectMetadata
- Actual file attachments:
documentsMetadata:
documentsMetaData adds the following documents for each consignment:
-
- Packing List
- Commercial Invoice
- Certificate of Origin
Document Type: To get a list of Documents types supported by the platform you can call GET/api/v1/documentTypes under Platform Constants
File Type: The supported file types are PDF, JSON, and IMAGE (JPEG, PNG)
Document References: This field is mandatory when uploading multiple documents of the same type.
Below is an example to use the bulk document upload for each documentmetadata type:
[
//First document Meta Data – Packing List
{
"filePartKeys": {
"file": "PackingList1" //This is the first packing list file an attachment
},
"metadata": {
"docType": " PACKING_LIST", //docType is PACKING_LIST
"docTypeNamespace": "platform",
"fileType": "PDF", //File uploaded as Pdf
"docReferences": {
"fileName": "PackingList123" // user supplied key-value pairs
}}},
//Second document Meta Data - Packing List
{
"filePartKeys": {
"file": " PackingList2" //This is the second packing list file as attachment
},
"metadata": {
"docType": " PACKING_LIST", //docType is PACKING_LIST
"docTypeNamespace": "platform",
"fileType": "PDF" , //File uploaded as Pdf
"docReferences": {
"fileName": " PackingList345" // user supplied key-value pairs
}}},
//Third document Meta data - Comercial Invoice
{
"filePartKeys": {
"file": "Commercial Invoice1" //This is the first Commercial Invoice file as an attachment
},
"metadata": {
"docType": "COMMERCIAL_INVOICE", //docType is Commercial Invoice
"docTypeNamespace": "platform",
"fileType": "PDF", //File uploaded as Pdf
"docReferences": {
"fileName": "Invoice 1234" // user supplied key-value pairs
}}},
//Fourth document Meta data - Certificate of Origin
{
"filePartKeys": {
"file": "Certificate of Origin" //This is the Certificate of Origin as an attachment
},
"metadata": {
"docType": "CERTIFICATE_OF_ORIGIN", //docType is Certificate of Origin
"docTypeNamespace": "platform",
"fileType": "PDF", //File uploaded as Pdf
"docReferences": {
"certificateNumber": "Cert 1234" // user supplied key-value pairs
}}}
]
tradeObjectMetadata:
Multiple actions will be triggered based on this API:
-
- Creation of Shipment object
- Add Primary reference to Shipment
- Attach Shipment to Consignment
- Add My role in the Shipment
- Add Parties to the Shipment
Shipment references: To get a list of reference types on TradeLens you can call GET/api/v1/referenceTypes under Platform Constants
Callers Party Roles: The supported roles are - SELLER, BUYER, EXPORTER, IMPORTER, ORIGIN_3PL_AGENT, DESTINATION_3PL_AGENT, CERTIFICATE_ISSUER
Parties Party Roles: The supported roles are - SELLER, BUYER, EXPORTER, IMPORTER, ORIGIN_3PL_AGENT, DESTINATION_3PL_AGENT, CERTIFICATE_ISSUER
partRef: to get a list of part references call GET/api/v1/partners and set include_reference_records as true. The response has the ids of the business partners that you can use here as partRef
Below is an example to use the bulk document upload for each tradeobjectmetadata type:
{
"consignment": {
"carrierBookingNumber": "BKA001489" //Carrier Booking Number associated with the shipment
},
"shipment": {
"references": [
{
"reference": "BKA001489", //Provide the carrier booking number or bill of lading number
"type": "proformaInvoiceNumber" // Type is billOfLadingNumber
}
],
"callersPartyRole": " ORIGIN_3PL_AGENT", //My role on Shipment (enum in swagger)
"parties": [
{
"partyRef": "12345678",
"partyRole": " EXPORTER" //company name added as exporter on Shipment
},
{
"partyRef": "23456789",
"partyRole": " DESTINATION_3PL_AGENT" //company added as destination 3PL on Shipment
}
]
}
}
Actual file attachments:
The key to the file attachments is mapped to the value specified in the document metadata : filePartKeys : file. This value will be used from the request to fetch the actual document attachment for the corresponding document.
" PackingList1": "PackingList1.pdf" //Attach Packing List 1
" PackingList2": " PackingList2.pdf " //Attach Packing List 2
" Commercial Invoice1": "CommInvoice.pdf" //Attach Commercial Invoice
" Certificate of Origin": "CertOfOrigin.pdf" //Attach Certificate of Origin
Call the Get
Call the GET/api/v1/bulkTransactions/{bulkTransactionId} endpoint under Actionable Flows using the bulkTransactionId you received as response from Step 2 to know the status of the upload.
To understand more visit the swagger link: https://platform.tradelens.com/documentation/swagger/
