(r24) EdiDatatransfer < Cargooffice

Tags: view all tags
---++!! Data transfer methods

Currently these methods are supported:
%TOC%

---+++ Email
   * Orders and [[EdiStatusUpdates][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+%RED%carrier%ENDCOLOR%[.%RED%customer%ENDCOLOR%][+%RED%ext%ENDCOLOR%]@cargooffice.com*
      * *%RED%carrier%ENDCOLOR%* : carrier number (e.g. 1122) or companycode (e.g. 'logisticplanet')
      * *%RED%customer%ENDCOLOR%* : [optional] the customer number, if the file is sent by a customer (e.g. a file containing orders)
      * *%RED%ext%ENDCOLOR%* : [optional] rename the attached file to a file having this extension (e.g. xml, csv)
      * Examples:
         * edi+logisticplanet@cargooffice.com
         * edi+1122.1234@cargooffice.com
         * edi+1122+xml@cargooffice.com
         * [[mailto:edi+logisticplanet.1234+xml@cargooffice.com][edi+logisticplanet.1234+xml@cargooffice.com]]
         * edi+1122+ttm@cargooffice.com (ttmail)
      * *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 *%RED%.customer%ENDCOLOR%* 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.<br />Clicking 'Overview of Batch Orders' in the Frontoffice will spawn an extra window displaying orders entered as a batch.<br />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.<br />Orders can than be edited and set to 'sent' for further processing.

---+++ FTP / SFTP / FTPS up- and downloads
   * You can use either [[FtpUploads][FTP, SFTP or FTPS]] (the latter is SSL/TLS encryted)
   * For every new user you must enter a user and a password (backoffice -&gt; Settings -&gt; 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
      1 download the file
      1 logout
      1 process the file
      1 login
      1 move the file to /done or /error depending on the result of your process
      1 logout
   * See also: FtpUploads
   * If you want us to assist, please send us a request by using your [[ReportAdd][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 [[ReportAdd][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:
<pre>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 
</pre>

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

*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 [[ReportAdd][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:
<verbatim> $secretkey= "abcdefabcdef"; 
 $timestamp = mktime(date());
 $signature = md5( $timestamp . $secretkey);</verbatim>
   * The *signature* is passed in the url along with the timestamp in its original form:
<verbatim>/somescript.php?sig=93abd8578e9a4d8af3&ts=123333456</verbatim>
   * 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"