ApiCalls < Cargooffice

Tags: view all tags
---+ API calls (request order and / or track & trace data)

---++ API calls to external systems

Push a message to an external API server.<br />
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:
<verbatim>
proto=api
log=1</verbatim>

*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 [[StatusActionsUrl#Write_data_to_a_file][makeFile]] status action. This is an example of such an action:

*Action example:*

<verbatim>
# 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</verbatim>

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:*

<verbatim>
# 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
</verbatim>

---++ 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.<br />
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*).<br />
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.
Topic revision: r7 - 2021-04-06 - HenkRoelofs