(r23) EdiDatatransfer < Cargooffice

Tags: view all tags

Data transfer methods

Currently these methods are supported:

Email

Orders and status updates sent to Cargooffice are processed automatically.
Data files must be added as MIME encoded attachments.
The extension of the attached data files must indicate their format (.csv , .xml , .xls , ttm).
The contents of the email and the "subject" info are not used.
The exact email address will be given to you by the system administrator, the general format of the email address is:
- edi+carrier[.customer][+ext]@cargooffice.com
- carrier : carrier number (e.g. 1122) or companycode (e.g. 'logisticplanet')
- customer : [optional] the customer number, if the file is sent by a customer (e.g. a file containing orders)
- ext : [optional] rename the attached file to a file having this extension (e.g. xml, csv)
- Examples:
- NOTE: this email address must be the only email address in the To: header. Put other email addresses in the cc: or bcc: header.
If customers are sending EDI files then the .customer part always needs to be added.
The optional +ext part allows for the processing of files with a 'wrong' extension by the correct parser.
Processed orders will be visible through the track & trace website.
In case a parse error occurs, an error message will be mailed back to the originating mail address along with the file sent.
Note that it can take a few minutes before orders are processed and appear on the webpage.

Http uploads

Files as mentioned above can be uploaded via the Cargo Office website.
Clicking 'Overview of Batch Orders' in the Frontoffice will spawn an extra window displaying orders entered as a batch.
On top of the page there is a form element, allowing to upload files to Cargo Office.
Orders from the uploaded files will per default be stored as batch orders (status 'batchentry') and appear in the list below the upload form directly after.
Orders can than be edited and set to 'sent' for further processing.

FTP / SFTP / FTPS up- and downloads

You can use either FTP, SFTP or FTPS (the latter is SSL/TLS encryted)
For every new user you must enter a user and a password (backoffice -> Settings -> FTP user management)
To login connect to ftp.cargooffice.com (port 21 for FTP and port 2222 for SFTP)
If you are downloading files then please note that there is a timeout of 1 minute, use the following procedure for your script:
1. login
2. download the file
3. logout
4. process the file
5. login
6. move the file to /done or /error depending on the result of your process
7. logout
See also: FtpUploads
If you want us to assist, please send us a request by using your bug tracking system.

Track & Trace API

There are several API's available to receive order and track & trace data
Read all about it here: ApiCalls

SOAP calls

XML formatted messages can be send to an external SOAP server
The XML message must be in a file with the extension .soap
And you need to tweak param orderoutputFTP
Read all about it here: SoapCalls
If you want us to assist, please send us a request by using your bug tracking system.

Web service API (Application Programming Interface)

Cargooffice offers serveral different methods for on-line querying and updating of data. The preferred method is REST. REST is a lightweight alternative to Web Services like SOAP and XML-RPC. The idea is that, rather than using complex mechanisms such as CORBA, (XML)RPC or SOAP to connect between machines, simple HTTP is used to make calls between machines.
RESTful applications use HTTP requests (GET,POST,DELETE,UPDATE).
Use POST to create data, GET for reading data from the database, PUT to create/update data, and DELETE to delete data. (In practice only GET and POST are usually enough).

REST examples

Below are examples of a request to query XML order data:

http://maersk.cargooffice.com/api/order/?sig=59400d0d0279d7bef8c66df1f269ae5b&ts=1295352899&ShipmentID=100272
http://maersk.cargooffice.com/api/orderpc/?sig=95ba0d61dc72698d7bd66446c7447950&ts=1295352899&ShipmentID=496295&Postcode=4891PR

Format:
Url http://hostname.cargooffice.com (in the example the Maersk host is queried).
Method (in this case 'api')
Function (in this case 'order')
Parameters:
- sig signature (see authentication below)
- ts time stamp (see authentication below)
- ShipmentID the ID of the order to query
- Postcode the delivery postcode of the order to query
The reply would look something like this:

<Order>
 <shipmentID>100272</shipmentID>
 <customerID>1234</customerID>
 <orderReference>ref121212</orderReference>
 <deliveryType>Normal delivery</deliveryType>
 <CODcurrency>EUR</CODcurrency>
 <pickupName>Loginet B.V.</pickupName>
 <pickupAddress>Science Park 402</pickupAddress>
 <pickupPostcode>1098 XH</pickupPostcode>
 <pickupCity>Amsterdam</pickupCity>
 <pickupCountry>NL</pickupCountry>
 <pickupDate>20-08-13</pickupDate>
 <pickupTime>11:00</pickupTime>
 <deliveryName>Philips</deliveryName>
 <deliveryAddress>Boven Heining 2</deliveryAddress>
 <deliveryPostcode>4891PR</deliveryPostcode>
 <deliveryCity>...
 ...
</Order>

Post new order example

See the attached file apiTest.php for an example on how to add a new order in cargooffice.

Authentication

Each api user must have a unique api-key. If you want one then please contact us by sending us a request through our bug tracking system.
The key should be kept Secret and can only be used on the clients' server.
The key will never be passed in a request, but mixed with a 'unique number' (unix-timestamp) in md5 format. Like this:

 $secretkey= "abcdefabcdef"; 
 $timestamp = mktime(date());
 $signature = md5( $timestamp . $secretkey);

The signature is passed in the url along with the timestamp in its original form:

/somescript.php?sig=93abd8578e9a4d8af3&ts=123333456

The RESTserver reads the users secret key from the database, and re-creates the signature (with the given timestamp).
The request is valid/authenticated if the signatures are equal.
If it is not valid, then REST will return a html status-code: "401 Unauthorized"