Blog

FTP integration using the FTP Uploader app

It is possible to upload invoices to an FTP server and have them picked up from there automatically. It provides file system upload. Tradeshift provides a free account to a server where you can upload your invoices in a variety of formats.


FTP stands for ‘File Transfer Protocol’, it is a standard network protocol used to transfer files from one host to another over a TCP-based network, such as the Internet. If you are not familiar with FTP it is recommended to find out more about it before continuing reading this page. There is plenty of information about FTP available on the web.In order to use this integration method you have to have an accounting or ERP software which is able to send documents over FTP or an FTP client (there are plenty of free FTP clients available). You have also to activate the ‘FTP Uploader‘ app from the Tradeshift apps.

To integrate your ERP, accounting system or FTP client with Tradeshift, please, follow the following steps:

1. Go to the FTP Uploader app

2. Insert a password which you will be later using to connect to the FTP server

3. Press ‘Save’ button to save the password and create an account at the FTP server

4. Copy the FTP hostname (si.tradeshift.com), port (21) and username shown in the bottom of the app

FTP Uploader app settings

5. Use FTP hostname, port, username and your password to configure your ERP, accounting software or FTP client to connect to the FTP server.

6. That’s it! You are ready to send invoices from your system or FTP client to the FTP server. Try to connect and put a document into the ‘outbox’ directory of the server. NOTE: FTP server data transfer is enabled in the PASSIVE mode only.

Latest changes

  • (S)FTP(S) usernames became Base64 encoded in order to reduce their length from 32 to 22 characters. For example, if your previous username looked like this: 877308069fd74fed822f3c8afd5e3579, it will become similar to h3MIBp/XT+2CLzyK/V41eQ. All characters like ‘/’, ‘+’ are valid. We still support 32 characters long usernames, so there is no need of changing your existing configuration.

 

Test your FTP connection in Windows

After the key was generated and successfully saved by the ‘FTP Uploader’ app, it would be a good idea to test the connection to FTP server. For the test purposes you can use FileZilla – a free and simple FTP client. You can download it from the FileZilla website http://filezilla-project.org/download.php?type=client. Install FileZilla and follow the following steps:

1. Run FileZilla, select ‘Site Manager’ from the ‘File’ menu. Click on ‘New Site’ button to create a new session

2. In the ‘General’ tab fill in ‘Host’, ‘Port’ and ‘User’ fields with the values provided in ‘FTP Uploader’ app. Select ‘FTP – File Transfer Protocol’ from the ‘Protocol’ dropdown box, ‘Use plain FTP’ from the ‘Encryption’, and ‘Normal’ from the ‘Logon Type’ dropdown boxes. Insert the password you saved in the ‘FTP Uploader’ app into the ‘Password’ field

FileZilla FTP session setup

3. In the ‘Transfer Settings’ tab set transfer mode to ‘Passive’

4. Click ‘Connect’ button

5. If login was successful you will see a commander-style window with list of FTP server’s directories on one of the sides

FTP file system

6. Double click on the ‘outbox’ directory to open it

7. Create a test invoice. Remember that all your invoices must have unique Invoice Numbers (Invoice ID). Let’s assume, you created an invoice in UBL format with the Invoice Number ‘12709’. The name of the invoice must match exactly to the Invoice Number and have ‘xml’ extension: ‘12709.xml’

8. Put the invoice into the ‘outbox’ directory of the FTP server. You can do this by just dragging the file to the ‘outbox’ and drop it there

9. The file is uploaded to the FTP server, but it’s not processed yet. To process the file put an empty file with the name which match exactly to the name of the invoice file appended by ‘.ok’: ‘12709.xml.ok’. This will trigger Tradeshift to pick up the file and process it.

Please be advised that if the files are not uploaded in the right order (1. invoice, 2. semaphore mechanism file with “.ok”) the dispatch engine will not be triggered.

10. The ‘12709.xml.ok’ file is deleted. The invoice file ‘12709.xml’ is moved to one of the following directories, depending on the validation and dispatch results:

  • sent – in case the invoice passed the validation and was dispatched successfully
  • failed – in case the invoice didn’t pass the validation and was not dispatched
  • dispatchfailed – in case the invoice passed the validation but could not be dispatched (because of the non-existing recipient’s e-mail address)

Read more about the (S)FTP server directory structure

11. Go to the ‘Documents’ tab of the Tradeshift web platform. If the invoices passed the validation it will appear under the ‘Sales’ subtab

Uploaded invoice in the 'Documents' tab

Test the FTP connection with Windows command line ( ftp.exe )

In case your company is using MS Access or other Microsoft accounting software with incorporated FTP uploader you might need to set up the FTP connection using Windows command line ( cmd/ftp.exe). If you are not familiar with FTP connection established by using command line it is recommended to find out more about it before continuing reading this page. You should also look up some documentation of your software to see how to set up an FTP connection with the FTP client incorporated in your Microsoft product. There is plenty of information about ‘FTP’ available on the web.

The ftp.exe does not support data transfers in passive mode, so the active mode is used as a default. To establish an Active FTP connection and data transfer mode by you should follow the following steps:

After the FTP account was created by the ‘FTP Uploader’ app, it would be a good idea to test the connection to our FTP server.

Preliminary steps:

In order to allow Active FTP connections you might need to add a firewall rule. Active FTP sessions will need to establish connections from our FTP server to your host. Because of this you should allow incoming traffic on your firewall to your host.

1. Add firewall rule that allows incoming tcp from the domain si.tradeshift.com from the source port 2105. Destination IP will be your ftp client (host) and destination port will be random.

Without adding this rule, you will not be able to receive data communication from our server. This is an essential measure if you connect by using ftp.exe to our FTP server. You do not necessarily need to make this step in case you are using an FTP client like FileZilla or wput that supports passive mode.

2. Go to Start -> Run -> type in ‘cmd’ and press enter in the command line type:

3. ftp si.tradeshift.com -> start FTP session and connect to the host provided by the FTP Uploader app (e.g. si.tradeshift.com)

4. Enter your username provided by the FTP Uploader app

5. Enter the password you set in the FTP Uploader app end press Enter key

Now you should see a line similar to ‘ 230 User logged in, proceed ’. This means you are successfully logged in.

6. ls ->this going to display a list of documents in the root directory. By issuing this command you can test if you can receive data from the FTP server

7. Now change directory by typing: cd outbox -> this is the directory where you have to upload your documents.

8. Now you can upload your documents by using ‘put’ command, e.g. ‘put c:/test_invoice_001.xml test_invoice_001.xml’.

9. For this step please follow the example above from step 7. until step 11.

Tradeshift’s (S)FTP server directory structure

Dir name Description
outbox Directory used to put files to be processed by Tradeshift. Read more about supported document formats.
NOTE: Tradeshift’s SFTP server is following ‘.ok file’ strategy. It means, that in order to signal that the document file has been uploaded and Tradeshift can pick it up, an empty file with the same name but appended with ‘.ok’ has to be uploaded. For example, if you want Tradeshift to send an invoice by uploading file ‘invoice_001.xml’, it has to be followed by ‘invoice_001.xml.ok’ file. If the .ok file is not uploaded Tradeshift will keep waiting for it. The original document file will be stored in the outbox dir until it’s deleted or .ok file is uploaded.
sent Stores successfully dispatched files. Besides, there will be dispatch results file available for each sent document. The dispatch results file has the same name as the original file, but has ‘.dispatch.xml’ appended.
failed Stores files which didn’t pass the validation. Besides, there will be validation results file available for each failed validation file. It has the same name as the original file but ‘.failed.xml’ appended.
dispatchfailed Stores files which pass the validation, but couldn’t be dispatched. Besides, there will be dispatch results file available for each failed validation file. It has the same name as the original file but ‘.dispatchfailed.xml’ appended. Dispatch might fail because of invalid e-mail address in the document.
dynamicvalidations Optional directory. You have to activate Dynamic Validations Appto have it enabled.Stores definitions of dynamic validation. The dynamic validation definitions are XML files defining fields of documents which should be validated against list of possible values that are dynamically uploaded to the dynamicvalidationchanges directory. The validations may define the sender and the receiver of the document for which the field must be validated. It is particularly valuable for an enterprise which has branches (see Branch Management App): the different validations can be be defined for each branch by setting the branch as the receiver.

All files must have the following mandatory fields:

  • Id – the unique ID of the validation definition
  • ReceiverId – the receiver of the document for which the validation must apply. It is defined by the scheme (for example “GB:VAT”, “DK:CVR”) and the actual value this scheme represents
  • Field – the XPath expression unambiguously defining the field of the document to apply validation to
  • DocumentType – the type of the document which is to be validated. For example: invoice, quote, etc.

Optionally, the SenderId could be defined. In this case the validation is applied only to documents sent by this particular sender.

NOTE: the file name must exactly match to the Id of the validation definition appended by “.xml” string.

Only one validation definition per file is allowed.

Following the SFTP’s server “.ok file” strategy, the file will be uploaded only after an empty file with the same name appended with “.ok” is uploaded to the directory.

dynamicvalidationchanges Optional directory. You have to activate Dynamic Validations Appto have it enabled.Directory to upload list of valid values of fields defined by the dynamic validation definitions (see dynamicvalidation directory description). They are uploaded as XML files containing reference (dynamicValidationId) to the correspondent dynamic validation definition uploaded earlier. If the referenced dynamic validation definition does not exist, the uploaded file will be skipped.

NOTE: the file name must exactly match to the dynamicValidationId of the validation definition appended by “.xml” string.

File will be uploaded only after an empty file with the same name appended with “.ok” string is uploaded. The uploaded files are not viewable and the directory is always empty.