EdiDatatransfer < Cargooffice

---++!! 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 [[http://twiki.cargooffice.com/bin/view/Cargooffice/FtpUpload#FTP PUSH (automated transfer fro][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)
   * %RED%*Note*: The insertion of orders through an API calls is depreciated and might be removed in the future. This method caused many problems in the past where orders went missing due to network connection failures or temporary down servers. Also the intertion of hundreds of orders at once using API calls proved to be a relatively slow proces. It is better to use for instance email to send orders. Emails will arrive as soon as connections are restored.</red>
   * 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 apiTest2.php for an example on how to add a new order in cargooffice. 
     The advantage of this example is that the EDI configurator is used to interpret/alter the data when the new order is entered into the database.

*Post / update 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"
Attachments
Topic attachments
I	Attachment	History	Action	Size	Date	Who	Comment
txt	apiTest.php.txt	r1	manage	1.8 K	2014-06-11 - 14:42	HenkRoelofs	post a new order (example php source)
txt	apiTest2.php.txt.txt	r1	manage	3.0 K	2020-08-28 - 09:48	HenkRoelofs	post a new order via configurator (example php source)
This topic: Cargooffice > AboutFreecargo > FreightExchangeHowto > WebHome > EdiDocumentation > EdiHowto > EdiDatatransfer
Topic revision: r27 - 2021-08-25 - HenkRoelofs