Documentation
Documentation
API References

Find Transaction and Document

Suggest Edits

Often customers using the essDocs come across a similar use case of finding the customer based on which a transaction is to be looked at. Again each transaction, a relevant PDF document can be downloaded. Here is a complete use case with endpoint implementation.

1. Generate Token

The first step for any API endpoint call is to generate a token using Get Token endpoint. With valid user credentials, here is a cURL.

curl --location --request GET 'https://api-test.cargodocs.com/v3/common/oauth2/token' \
--header 'Authorization: Basic ekxpbmVyUGlsVXNlcjE6UHJlc2VudDIwMjAh'

A generated token JSON looks like this. The token is used as Bearer for all the other endpoints within the API.

{
    "token": "eyJraWQiOiJPUUJmaXR6KzBWOFlxWFp3N2lHc1hlWjB5T2I3RTNyekpGWGZUYm9cL0M0Yz0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJjODU2NzIxZC0wMmEyLTQ0MzItYWRhMy0xNDVjMGYxZTY4ZjIiLCJldmVudF9pZCI6ImMyNzkxMjRmLTQ1YmItNDMyMi05ZWFhLTU3OGI2ZmQzOTY1NCIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE2NTI2OTUxNjMsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC5ldS13ZXN0LTEuYW1hem9uYXdzLmNvbVwvZXUtd2VzdC0xX1drRmF1Q2tnUSIsImV4cCI6MTY1MjY5ODc2MywiaWF0IjoxNjUyNjk1MTYzLCJqdGkiOiI4YmJkMWVlZi0wNzllLTQ1NTEtOWQ2Ny1jMGUyODA2YjkyNzAiLCJjbGllbnRfaWQiOiI3bzh0dDI4OWNvNHU5NnQ5bHQ1MnFyMnZxYSIsInVzZXJuYW1lIjoiekxpbmVyUGlsVXNlcjEifQ.VJ2jXnMhX9ZOG2sRw_1w9mcA4OsaPXAWt8QEBvogStREYC7W97VJ_miaCoxF85glwTYExHIRvOOQRePRONSQETQS_7mGwCdG2KQJAJOXNjwfI6b0Q4fK7GceR3xCxcIAMF2UAD2kOvLU8ekt7J2Yp0q6q5AWanw9nLhuQ3xWQ-kyLbT6ZKPDmHCQU7y_2EUA_m7susXRdJJgRzzlmapI5zBdy7xwwk9dKO6jf8-c7Y1TCE0VaoMMhfxAgp4gDOw6L65gwaZiUSxFv8ZfAb3CTZK5Y7mNOCT3UcpMOCGEjVED4CiKNPrpMMJ3BXrcpqnS9A6lAr9KfUW5ZjDd4tY4aA"
}

2. Get Counterparties [Optional Call]

📘

Customer ID

Usually, the Customer ID is already known to the customer, however just in case the customer ID is to be retrieved, the Get Counter Parties endpoint is consumed.

Here is a usual Get Counterparties cURL.

curl --location --request GET 'https://api-test.cargodocs.com/v3/common/counterparties' \
--header 'Authorization: Bearer eyJraWQiOiJPUUJmaXR6KzBWOFlxWFp3N2lHc1hlWjB5T2I3RTNyekpGWGZUYm9cL0M0Yz0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJjODU2NzIxZC0wMmEyLTQ0MzItYWRhMy0xNDVjMGYxZTY4ZjIiLCJldmVudF9pZCI6ImMyNzkxMjRmLTQ1YmItNDMyMi05ZWFhLTU3OGI2ZmQzOTY1NCIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE2NTI2OTUxNjMsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC5ldS13ZXN0LTEuYW1hem9uYXdzLmNvbVwvZXUtd2VzdC0xX1drRmF1Q2tnUSIsImV4cCI6MTY1MjY5ODc2MywiaWF0IjoxNjUyNjk1MTYzLCJqdGkiOiI4YmJkMWVlZi0wNzllLTQ1NTEtOWQ2Ny1jMGUyODA2YjkyNzAiLCJjbGllbnRfaWQiOiI3bzh0dDI4OWNvNHU5NnQ5bHQ1MnFyMnZxYSIsInVzZXJuYW1lIjoiekxpbmVyUGlsVXNlcjEifQ.VJ2jXnMhX9ZOG2sRw_1w9mcA4OsaPXAWt8QEBvogStREYC7W97VJ_miaCoxF85glwTYExHIRvOOQRePRONSQETQS_7mGwCdG2KQJAJOXNjwfI6b0Q4fK7GceR3xCxcIAMF2UAD2kOvLU8ekt7J2Yp0q6q5AWanw9nLhuQ3xWQ-kyLbT6ZKPDmHCQU7y_2EUA_m7susXRdJJgRzzlmapI5zBdy7xwwk9dKO6jf8-c7Y1TCE0VaoMMhfxAgp4gDOw6L65gwaZiUSxFv8ZfAb3CTZK5Y7mNOCT3UcpMOCGEjVED4CiKNPrpMMJ3BXrcpqnS9A6lAr9KfUW5ZjDd4tY4aA'

Developers can filter out the customerId as per the customerName within the code and utilize the customerId for the next queries. 

[
    {
        "customerId": "0a2ab3cb-44e4-11e9-9ed6-0a24491b68de",
        "customerName": "CUSTOMER NAME 187"
    }
]

3. Get Parcel Transaction Details

Each customer parcels related transaction can be searched using Search endpoint which is common across all essDocs API Documentations. The Search method supports multiple parameters-based filters to retrieve tailored output as per the requirement. Here is an example of a Search based on a customer id and a specific shipment reference number.

curl --location --request POST 'https://api-test.cargodocs.com/v3/common/sets/search' \
--header 'Authorization: Bearer eyJraWQiOiJPUUJmaXR6KzBWOFlxWFp3N2lHc1hlWjB5T2I3RTNyekpGWGZUYm9cL0M0Yz0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJjODU2NzIxZC0wMmEyLTQ0MzItYWRhMy0xNDVjMGYxZTY4ZjIiLCJldmVudF9pZCI6Ijg0M2ExNWVhLTdjY2UtNDliZC1iYWI5LTY5ZDE5ZThlM2VjZiIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE2NTI4NjgyMDEsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC5ldS13ZXN0LTEuYW1hem9uYXdzLmNvbVwvZXUtd2VzdC0xX1drRmF1Q2tnUSIsImV4cCI6MTY1Mjg3MTgwMSwiaWF0IjoxNjUyODY4MjAxLCJqdGkiOiJlZDBhZTQ2OC1kNWJjLTQ3ZTMtYTQzZC1mYzkwZWI1MGE5ZDkiLCJjbGllbnRfaWQiOiI3bzh0dDI4OWNvNHU5NnQ5bHQ1MnFyMnZxYSIsInVzZXJuYW1lIjoiekxpbmVyUGlsVXNlcjEifQ.FwVgGDwchBiP-kTGO1Fj8PHv0NFuG4yqdXCKyDS7O9Vfnyge-X736x17VQdVJHtGwgcRAmawQhI9lXmT3tdhb1rIrf_NGSqsjIGUZaXD-ECiPKmvr5mzdGQWxNkTLzjNA8pLVBF6CqqP5MnQ8uvGWvxrIJHidLafGVARq6toyJSUEWy1RXS488buMAQlyl898wcxUTKQJvbu7Wv2LYfF2yqKrR07G8zYzrcPSamtDyPGrTz94UfRDZPF30kZlqeJOgVUgda780qmQs8UIIBe79UPDjky2qyReIi8HmG6jd7WlTpr7NIjo1tuPrSCASWXmHPC_4PyCop0xr4Ao8_pPA' \
--header 'Content-Type: application/json' \
--data-raw '{
"status": "ACTIVE",
"instance": "DOCEX",
 "customerIds": ["df192c5e-701e-4e58-9b8d-d0daf7404109"],
 "shipmentRef": "SRIDINO200420227"
}'

Once executed, the filtered output looks like this.

{
    "code": 200,
    "status": "OK",
    "data": {
        "offset": 0,
        "limit": 100,
        "total": 1,
        "count": 1,
        "results": [
            {
                "setId": "627fc311-515f-4b76-811b-0c02d845a966",
                "transactionId": "f41acec7-63e6-48a4-a086-43ba641a58db",
                "parcelRef": "P-SRIDINO220320221",
                "shipmentRef": "SRIDINO200420227",
                "status": "signed",
                "destinationName": "LAEM CHABANG PORT",
                "destinationCountry": "Thailand",
                "cargoName": "Generic Liner Cargo",
                "modifiedDate": "9 May 2022 10:50",
                "fromParty": null,
                "fromPartyId": null,
                "documents": [
                    {
                        "name": "PIL Singapore",
                        "documentId": "36e6953f-41f4-42b3-8540-19fd99d60b91",
                        "docType": "Bill of Lading",
                        "xmlContent": null
                    },
                    {
                        "name": "Cargo Manifest",
                        "documentId": "58487c7b-3471-4718-ac70-e789794617df",
                        "docType": "Uploadable Document",
                        "xmlContent": null
                    }
                ],
                "actions": null,
                "billOfLadingDate": "2022-03-14",
                "signature": "1 of 1",
                "quantity": "null null",
                "consignorCompanyName": "zExchange 10A",
                "consigneeCompanyName": "zExchange 2",
                "loadPort": "MUNDRA, INDIA",
                "vesselName": null,
                "links": []
            }
        ]
    },
    "links": []
}

4. Get PDF

A single document can be extracted by providing the relevant setId and documentId to Single PDF endpoint if required.

curl --location --request GET 'https://api-test.cargodocs.com/v3/common/sets/627fc311-515f-4b76-811b-0c02d845a966/get-single-pdf/36e6953f-41f4-42b3-8540-19fd99d60b91' \
--header 'Authorization: Bearer eyJraWQiOiJPUUJmaXR6KzBWOFlxWFp3N2lHc1hlWjB5T2I3RTNyekpGWGZUYm9cL0M0Yz0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJjODU2NzIxZC0wMmEyLTQ0MzItYWRhMy0xNDVjMGYxZTY4ZjIiLCJldmVudF9pZCI6IjIzNjRmY2M0LTBiNzEtNDNjOC1iNDk2LTIyOGY2MTcwZTUyNiIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE2NTI5Nzc3MDIsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC5ldS13ZXN0LTEuYW1hem9uYXdzLmNvbVwvZXUtd2VzdC0xX1drRmF1Q2tnUSIsImV4cCI6MTY1Mjk4MTMwMiwiaWF0IjoxNjUyOTc3NzAyLCJqdGkiOiJjYThkZTczNS0wMmY2LTQwOTItYjFiZi01ODA3ZTljYzJjOWUiLCJjbGllbnRfaWQiOiI3bzh0dDI4OWNvNHU5NnQ5bHQ1MnFyMnZxYSIsInVzZXJuYW1lIjoiekxpbmVyUGlsVXNlcjEifQ.en8y29lQu24sfzHg7Mx6H0oNYWTA3jWci--X43fx32CDs0tAq17KLW4a23x25a6NUKzwq4YkVqi6fZ8t8XwPBhR_CGsYBD4MirZufK16HDqSbRa32T417Qw0YLl_4Fvfnla2JzQPwazsZE74phkaiIZ-TjF4XwlGq1WHE1DvuS7Pn32cOL-pcjSCwBnVzpNk6Wc_-dyxtoqaw7LzPnqAZIhHCqrZe9zB7uD6S7pf2G8_T-uzSrZrrEzo2oon9urQD-1vRorP-xqHPi3W6tWMVOIQdzfGVa58dYEBJjRaHwKjLevzcFaWz23CreCcPVrDxTNlaH1PiNb8qYexWrzzig' \
--data-raw ''

The validated arguments within the Get PDF endpoint retrieve the complete PDF file that can be saved and viewed. 

%PDF-1.5
%����
1 0 obj
<</ColorSpace/DeviceGray/Subtype/Image/Height 842/Filter/FlateDecode/Type/XObject/Width 595/Length 4879/BitsPerComponent 8>>stream
x���=k���4v��IܨR�4qaL
�"�\����cI�5��N�}�H�Uvc�=k��?zf��

❗️

PDF vs Base64

Please note that the current API supports output as a plain PDF. The Base64 implementation is in progress and will be available by the end of Q2 2022.

Messaging Queue Information

For each parcel update, the customer parcel queue gets a notification that can be used by the developer for their internal application notifications. Here is the major parcel status that a developer can keep a tap on.

  • Drafted
  • Signed
  • Issued
  • Title Held
  • Transfer Drafted

Here are the message bodies from the RabbitMQ, that can be used by the customers to retrieve relevant information as per the need.

Drafted

{
  "instance": "DocHub",
  "newStatus": "DRAFTED",
  "parcelReference": "P-1",
  "customerId": "0a2ae359-44e4-11e9-9ed6-0a24491b68de",
  "action": "APPROVE_COLLAB",
  "setId": "b9f77363-4fd8-42c8-b248-36a4628ca118",
  "updatedDate": "Mon May 16 15:02:01 UTC 2022",
  "message": "The set status has been updated",
  "user": "zCarrier5User1",
  "transactionId": "18f3f989-8f2c-49ec-a2b6-efab51868998"
}

Signed

{
  "actor": "zCarrier5User1",
  "actorCompany": "zCarrier 5",
  "instance": "DocEx",
  "newStatus": "Signed",
  "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"
}

Issued

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

Title Held

{
  "actor": "zCarrier5User1",
  "actorCompany": "zCarrier 5",
  "instance": "DocEx",
  "newStatus": "TITLE_HELD",
  "parcelReference": "P-1",
  "customerId": "0a2c03a9-44e4-11e9-9ed6-0a24491b68de",
  "action": "ISSUE",
  "setId": "b9f77363-4fd8-42c8-b248-36a4628ca118",
  "updatedDate": "Mon May 16 15:05:12 UTC 2022",
  "message": "The set status has been updated",
  "transactionId": "a49c6862-d598-4229-bd54-bbbefce0103b"
}

Transfer Drafted

{
  "instance": "DocEx",
  "newStatus": "TRANSFER_DRAFTED",
  "parcelReference": "P-1",
  "customerId": "0a2c03a9-44e4-11e9-9ed6-0a24491b68de",
  "action": "DRAFT_TRANSFER",
  "setId": "b9f77363-4fd8-42c8-b248-36a4628ca118",
  "updatedDate": "Mon May 16 15:23:27 UTC 2022",
  "message": "The set status has been updated",
  "user": "zValeUser1",
  "transactionId": "a49c6862-d598-4229-bd54-bbbefce0103b"
}

Updated over 2 years ago