--- agentTools: projectIndex: https://cargodocs-customer.readme.io/llms.txt --- # Search This API allows partners to find specific transactions or all transactions for a customer that they are authorised to download / manage. It always returns a list of set DTOs, which includes set_id & transaction_id; and set meta data If search result is unique, then will return document XML data and document_ids along with DTO. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "version": "3.0.0", "title": "CargoDocs Customer API", "description": "This API have endpoints For Tankers, Liner Cos, NVOCCs & future Warehouses wishing to create/issue original electronic bills of lading.", "termsOfService": "https://www.essdocs.com/policies/", "contact": { "name": "CargoDocs API Team", "email": "api@essdocs.com", "url": "https://www.essdocs.com" } }, "servers": [ { "description": "Sandbox API", "url": "https://api-test.cargodocs.com/v3/" }, { "description": "UAT API", "url": "https://api-uat.cargodocs.com/api/v3/" }, { "description": "Production API", "url": "https://api.cargodocs.com/api/v3/" } ], "externalDocs": { "description": "Find out more about essCargoDocs", "url": "https://cargodocs-issuer.readme.io" }, "tags": [ { "name": "Export Data from CargoDocs", "description": "This category of endpoints is used to export your data and PDFs from CargoDocs." } ], "paths": { "/common/sets/search": { "post": { "description": "This API allows partners to find specific transactions or all transactions for a customer that they are authorised to download / manage. It always returns a list of set DTOs, which includes set_id & transaction_id; and set meta data If search result is unique, then will return document XML data and document_ids along with DTO.", "summary": "Search", "operationId": "search", "tags": [ "Export Data from CargoDocs" ], "security": [ { "Authorization": [] } ], "parameters": [ { "name": "offset", "in": "query", "description": "Pagination offset of search results", "schema": { "type": "number" } }, { "name": "size", "in": "query", "description": "The max number of search results.", "schema": { "type": "number" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetSearchQuery" } } } }, "responses": { "200": { "description": "Parcel success response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetSearchResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden access denied config issue" }, "500": { "description": "Internal Server Error" }, "503": { "description": "Service Unavailable" }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "Authorization": { "type": "http", "scheme": "bearer" } }, "schemas": { "SetSearchResponse": { "properties": { "code": { "type": "number", "example": 200, "description": "Search response code" }, "status": { "type": "string", "example": "OK", "description": "Search returned status" }, "data": { "type": "object", "properties": { "offset": { "type": "number", "example": 5, "description": "Pagination offset number" }, "limit": { "type": "number", "example": 100, "description": "" }, "total": { "type": "number", "example": 1, "description": "" }, "count": { "type": "number", "example": 1, "description": "" }, "results": { "type": "array", "description": "Returned search set results array", "items": { "type": "object", "properties": { "setId": { "type": "string", "example": "52792116-dd88-4a85-bd53-74b60900385a", "description": "Returned set unique id" }, "transactionId": { "type": "string", "example": "40359336-c509-4085-baaa-59527bcd5a23", "description": "Transaction id generated against the search" }, "parcelRef": { "type": "string", "example": "VALEPM201123605", "description": "Parcel reference for additional details" }, "shipmentRef": { "type": "string", "example": "VALE TEST 1", "description": "" }, "type": { "type": "string", "example": "mSet", "description": "This indicates type of document set for the current shipment. Possible values could be mSet, eSet or Paper." }, "billOfLadingNumber": { "type": "string", "example": "BL 040220A", "description": "BL Number saved against the shipment." }, "status": { "type": "string", "example": "eUCP Present Sent", "description": "Parcel current status. This status would be as per the DOCEX/DOCHUB GUI." }, "destinationName": { "type": "string", "example": "China Mainland", "description": "Destination of the parcel" }, "destinationCountry": { "type": "string", "example": "MAIN CHINESE PORTS", "description": "Parcel destination country" }, "cargoName": { "type": "string", "example": "CARAJAS IRON ORE" }, "modifiedDate": { "type": "string", "example": "11 Mar 2022 15:11" }, "fromParty": { "type": "string", "example": "zExchange 10A" }, "fromPartyId": { "type": "string", "example": "0a2ac7f2-44e4-11e9-9ed6-0a24491b68de" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Congenbill 1994" }, "documentId": { "type": "string", "example": "53c7b28a-5a1e-4553-8c17-0e02fe70599f" }, "docType": { "type": "string", "example": "Bill of Lading" }, "xmlContent": { "type": "string", "example": "VALE TEST 1VALEPM201123605VALEPM2011236012020-08-19 00:00:00PORT OF PONTA DA MADEIRA BRAZIL2020-08-19 00:00:001000004M/V draftLog/>" } } } }, "actions": { "type": "string", "format": "nullable" }, "agentCompanyName": { "type": "string", "example": "zShip Agent 1" }, "billOfLadingDate": { "type": "string", "format": "date", "example": "2020-08-19T00:00:00.000Z" }, "consignorCompanyName": { "type": "string", "example": "VALE S.A." }, "consigneeCompanyName": { "type": "string", "example": "To Order" }, "consigneeCompanyPrefix": { "type": "string", "example": "To Order" }, "loadTerminalName": { "type": "string", "example": "PORT OF PONTA DA MADEIRA BRAZIL" }, "vesselImo": { "type": "string", "example": 1000004 }, "vesselName": { "type": "string", "example": "M/V zCarrier4Vessel1" }, "documentNumber": { "type": "string", "format": "nullable" }, "toParty": { "type": "string", "example": "zExchange 10B" }, "toPartyId": { "type": "string", "example": "0a2ac97f-44e4-11e9-9ed6-0a24491b68de" }, "recipient": { "type": "string", "format": "nullable" }, "recipientId": { "type": "string", "format": "nullable" }, "returnReason": { "type": "string", "format": "nullable" }, "links": { "type": "array", "items": { "type": "string", "description": "" } } } } } } }, "links": { "type": "array" } } }, "Status": { "type": "string", "default": "ACTIVE", "enum": [ "ALL", "ACTIVE", "FILED", "AMENDMENT_CANCELLED", "AMENDMENT_ISSUED", "AMENDMENT_REJECTED", "AMENDMENT_REQUESTED", "CONVERT_SENT", "CONVERTED", "CORRECTING_DOCUMENT", "DOCUMENTS_REJECTED", "DOCUMENTS_RETURNED", "ENDORSEMENT_DRAFTED", "ENDORSEMENT_SIGNED", "ENDORSEMENT_SENT", "ENDORSEMENT_RETURNED", "PRODUCED", "TITLE_HELD", "VOIDED", "VOID_REQUESTED" ] }, "SetSearchQuery": { "required": [ "status", "instance" ], "properties": { "status": { "$ref": "#/components/schemas/Status" }, "instance": { "type": "string", "description": "essDocs Query instance. This indicates the system from which the relevant result is to be fetched. ", "example": "DOCHUB", "default": "DOCHUB", "enum": [ "DOCEX", "DOCHUB" ] }, "transactionId": { "type": "string", "description": "A unique transaction id associated with the setId", "example": "c092db67-933d-4d94-9c44-71ea6c58d3e7" }, "parcelRef": { "type": "string", "description": "External parcel reference number set by the Exporter", "example": "24000 - A-1" }, "shipmentRef": { "type": "string", "description": "Shipment reference set by the exporter during creation of a shipment", "example": "TEST-A-1" }, "destinationName": { "type": "string", "description": "Filter to extract shipment based on the provided destination name", "example": "Vizag" }, "cargoName": { "type": "string", "description": "Implied cargo name against the shipment", "example": "Generic Bulker Cargo" }, "billOfLadingNumber": { "type": "string", "description": "Bill of Lading number associated with the shipment", "example": "Test BL Number" }, "billOfLadingDate": { "type": "string", "description": "BoL generation date in YYYY-MM-DD format", "example": "2021-03-16" }, "billOfLadingDateRange": { "type": "array", "description": "To filter the results based on the BoL date. Required format is YYYY-MM-DD", "items": { "type": "string", "example": "2021-03-16" } }, "consignorCompanyName": { "type": "string", "description": "Shipment consignor company name", "example": "HSBC Exporter" }, "consigneeCompanyName": { "type": "string", "description": "Shipment current consignee company name", "example": null }, "toOrder": { "type": "boolean", "description": "Indicates a flag to order the result in ascending order. Set to true if the result is to be ordered", "example": null }, "loadPort": { "type": "string", "description": "Shipment loading port", "example": null }, "vesselName": { "type": "string", "description": "Shipping vessel name", "example": null } } }, "Error": { "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32", "example": 404 }, "message": { "type": "string", "example": "Invalid object found in parameters" } } } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true }, "_id": { "buffer": { "0": 102, "1": 38, "2": 75, "3": 226, "4": 141, "5": 159, "6": 237, "7": 0, "8": 16, "9": 195, "10": 21, "11": 25 } } } ```