Skip to main content

/reports (POST)

The API will allow you to generate a new report and retrieve the download link for that report. Call the Reports with the /reports route.

Parameters​

files required

files: array of files to be included in the new report This represents the unique file reference as used on the platform. This value can be obtained from the platform, but more typically from the Cargosnap “Files-API”. Note: maximum 100 unique files may be added into 1 report (using more will generate an error response).

template optional (default = 2)

Template id, may be obtained from the Cargosnap platform. Example value: template: “12392”,

filename optional

(by default, Cargosnap will generate a timestamp filename)

##Example value: MyDocumentFromCargosnap.pdf

settings optional

Settings object has the following optional settings:

  • locale: possible values: (please ask Cargosnap support). Default en-US.
  • format: possible values pdf.
  • dateTime.zone: possible values see: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones (column “TZ database name”). Default UTC
  • dateTime.format: for example “Y-m-d H:i:s”. Default Y-m-d H:i:s

** asynchronous ** optional (default: false)

The 'asynchronous' option allows you to set an asynchronous pattern. This pattern allows the API to immediately return an URL of the report, even before the reports has actually been generated. Upon the return of this call, you may either trust it 'will be there soon enough', or poll for its presence. The key advantages of using this pattern are:

  • response time: your code may continue almost immediately upon completing the API call, whereas in a synchronous pattern it may take up to minutes for the call to be completed.
  • stability and retry logic: in the asynchronous pattern, you delegate retry logic to the API, but also because it is not subject to any timeouts, it will lead (esp on the larger reports with many photo's) to improved success rates of the report being generated without failure.

Example value:​

{ 
	"asynchronous": true,
    "files": [  
        12345, 
        134543, 
        65433
    ],
    "settings": { 	
        "locale": "en-US",	
        "format": "pdf",
        "dateTime": { 
            "zone": "Europe/Amsterdam", 
            "format": "Y-m-d H:i:s"
        }
    }
}

Response values​

The content of the response will depend on the query parameters, the implemented features on Cargosnap as well as the actual available data. The typical response will be:

url: https://cargosnapstorage.blob.windows.net/123/2345/gfbd24scdn5465hgre76fwscgfgrfedscbggrf/MyDocumentFromCargosnap.pdf

Example Request​

POST https://api.cargosnap.com/api/v2/reports?token=[MY-API-TOKEN]

POST DATA:

{
	"files": [  
		12345, 
		134543, 
		65433
	],
	"template": 12392,
	"filename": "HASU1234576-20190219",
	"settings": { 	
			"locale": "en-US",	
			"format": "pdf",
			"dateTime": { 
				"zone": "Europe/Amsterdam", 
				"format": "Y-m-d H:i:s T"
		}
	}
}

This query would:

  • Return a 201 response code, with the URL to the report in the content body:
{ url:"https://cargosnapstorage.blob.windows.net/123/2345/
gfbd24scdn5465hgre76fwscgfgrfedscbggrf/MyDocumentFromCargosnap.pdf" }