API calls (request order and / or track & trace data)

API calls to external systems

Push a message to an external API server.
This is handled by the pushspooler which runs every few seconds and also handles / pushes FTP files to remote servers. To configure API calls, you need to tweak param 'orderOutputFTP' a little bit so that it also pushes API messages.

If param 'orderOutputFTP' doesn't exist it needs to be created. The param needs to have a customerID (don't create a general param with a blank customerID).

Example of an orderOutputFTP param to push API messages:

proto=api
log=1

Explanation:

• proto: must be 'api'
• log: whether the actions should be made visible under 'EDI log' in your Cargooffice, set to 0 for no logging, set to 1 for logging.

A special folder is created automatically for this customerID. This folder will be created in your /in folder with the name /in/ftpoutspool{customerID}. This is the folder where you will later place files containing the messages that must me communicated to your external party.

The messages are generally created by a makeFile status action. This is an example of such an action:

Action example:

# CN and shipmentID are mandatory:
CN={CN}
shipmentID={shipmentID}
#
# the name of the function to call:
action=makeFile
#
# path and name of the file to create:
file=/in/ftpoutspool1234/status_{orderID}_{statusDate}_{statusTime}.api
#
# file data after this line:
fileData=
curl -H "x-api-key: 1234" -H "Content-Type: application/json" --data-raw '{
    "actualDatetime": "{deliveryDate}T{deliveryTime}:00Z"
}' -X POST https://api.example.com/PROD/statusReport/?divisionCode=TEST

The extension of the file must be .api and the content of the created file must be a curl command.

Example of a more complex call:

# CN and shipmentID are mandatory:
CN={CN}
shipmentID={shipmentID}
#
# the name of the function to call:
action=makeFile
#
# path and name of the file to create:
file=/in/ftpoutspool1234/status_DE_{orderID}_{statusDate:preg_replace/-//}{statusTime:preg_replace/://}.api
#
# file data after this line:
fileData=
curl -H "x-api-key: 1234" -H "Content-Type: application/json" --data-raw '{
   "estimatedDeliveryDate": "{deliveryDateEstFrom}T{deliveryTimeEstFrom}:00Z",
   "estimatedDeliveryTimezone": "Europe/Brussels",
   "transportOrderCode": "{orderReference}",
   "divisionCode": "VXF"
}' -X PATCH https://api.example.com/PRO/v1/transportOrders/{orderReference}?divisionCode=VXF

Request order of track & trace data

An API ( Application Program Interface) sends you data in a format that is readable by your applications. The format might be for example JSON, XML or CSV.
To request the data you have to call a special URL together with some parameters.

The URL (example)

https://yourcompanycode.cargooffice.com/ttbox/trackapi.php?r=123456789&t=1234AB

The parameters

• r = order reference number or ID
• t = postcode
• s = shipment number or ID

You can choose to provide either the order reference number (parameter r) or the shipment number (parameter s).
The shipment number may also be the tracking number of the shipment, if you have it available.

If you are not logged in (which is mostly the case) you must provide the postcode (parameter t) as well (the delivery or receiver postcode). This is to prevent external users repeatedly trying random numbers.