Blog

FTPS integration using FTPS Uploader app

It is possible to upload invoices to an FTPS 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.


FTPS stands for ‘File Transfer Protocol Secure’, it is a standard network protocols used to transfer files from one host to another over a TCP-based network, such as the Internet. If you are not familiar with FTPS it is recommended to find out more about it before continuing reading this page. There is plenty of information about FTPS 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 FTPS or an FTPS client (there are plenty of free FTPS clients available). You have also to activate the ‘
FTPS Uploader‘ app from the Tradeshift apps.

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

1. Go to the FTPS Uploader app

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

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

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

FTP Uploader app settings

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

6. Open Ports: For FTPS traffic on top of 990 please open ports 2300->2800 for the live environment (si.tradeshift.com) – that is a requirement for passive connections.
The test environment (si-sandbox.tradeshift.com) is using port 9901-> 9905 besides 990.

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

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 FTPS connection in Windows

After the FTPS account was created by the ‘FTPS Uploader’ app, it would be a good idea to test the connection to FTPS server. For the test purposes you can use FileZilla – a free and simple FTPS 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 ‘FTPS Uploader’ app. Select ‘FTP – File Transfer Protocol’ from the ‘Protocol’ dropdown box, for FTPS connection select ‘Require implicit FTP over TLS’ from the ‘Encryption’, and ‘Normal’ from the ‘Logon Type’ dropdown boxes. Insert the password you saved in the
‘FTPS Uploader’ for FTPS connection into the ‘Password’ field

FileZilla FTPS session setup

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

4. Click ‘Connect’ button

4a. Confirm the Server Certificate

FTPS Certificate

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

FTPS 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’ and file name 12709.xml.

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

9. The file is uploaded to the FTPS server, but it’s not processed yet. To initiate file processing you must use one of the semaphore mechanisms described in Tradeshift’s (S)FTP(S) server directory structure (see ‘outbox’ dir). In this example I will use .ok 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(S) 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

Tradeshift’s (S)FTP(S) server directory structure

Dir name Description
outbox Directory used to put files to be processed by Tradeshift. Read more about supported document formats. Files MUST have unique file names.
NOTE: This server implements different semaphore mechanism to allow you to signal that an upload is completed. You MUST employ one of these methods – if you do not, the server will wait indefinitely for the upload to complete.First semaphore mechanism: Using .ok notation
After successfully uploading a file <filename> (e.g. invoice-1.xml), either: Upload a second possibly empty file named <filename>.ok (e.g. invoice-1.xml.ok), or: Rename from <filename> to <filename>.okSecond semaphore mechanism: Using .tmp notation
Upload the file as <filename>.tmp (e.g. invoice-1.xml.tmp), and after successfull completion, rename the file to <filename> (e.g. invoice-1.xml).

Third semaphore mechanism: Using .filename notation
Upload the file as .<filename> (e.g. .invoice.xml), and after successfull completion, rename the file to <filename> (e.g. invoice-1.xml).

Only one document (e.g. invoice, credit note) per one file is supported.

This server supports attachments to documents. Attachments are files which are attached to the target document. Attachments can be send only together with the original document. It is not possible to add attachments to already uploaded document.

Attachments file names MUST be unique for the target document.
If sending a document with attachments they MUST be uploaded to the server BEFORE the signal about completed upload of the target document (read about semaphore semantics above). Only ONE signal about completed upload should be made: the signal about the target document upload. Do NOT signal completion of attachment files upload.
If there are no attachments to the target document or they do not confirm to the document attachments naming convention, the target document is send without attachments.
The attachment file names to the target document MUST confirm to ONE of the following rules:

attachment[documentfilename]attachmentfilename
Name starts with the word ‘attachment’ and the file name of the target document inside the square brackets and followed by the file name of the attachment itself.
E.g. the attachment which original name is receipt.pdf and has to be attached to invoice which file name is invoice-01.xml must be put to the server with file name attachment[invoice-01.xml]receipt.pdf

attachmentfilename.attachment.documentfilename
Name starts with original attachment’s file name followed by ‘.attachment.’ and ends with the file name of the target document.
E.g. the attachment which original name is receipt.pdf and has to be attached to invoice which file name is invoice-01.xml must be put to the server with file name receipt.pdf.attachment.invoice-01.xml

Attachments are attached to the target document with their original file names (e.g. receipt.pdf). Attachments are REMOVED from the server after the document is processed, no matter successfully or not.

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 App to have it enabled. The directory 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.

The directory follows the same (S)FTP(S)’s server semaphore mechanics described for ‘outbox’ directory.

dynamicvalidationchanges Optional directory. You have to activate Dynamic Validations App to 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 one of the semaphore strategies was fulfilled (see description of the ‘outbox’ directory for details). The uploaded files are not viewable and the directory is always empty.