With the file import via SFTP, you upload the report files of your ERP system to a dedicated storage area of your Lucanet environment, from which Lucanet VAT (Value Added Tax) imports the files. On the Lucanet CFO Solution Platform, the file import via SFTP replaces the classic network drive because the platform does not provide UNC or SMB shares.

You upload the files to the Share/ folder. During the import, VAT reads the Share/ folder, checks every file name against the configured filename pattern, imports the matching files, and then moves them to the Archive/ folder. The upload alone does not trigger an import: A file remains in Share/ until you start an import in VAT.

The following guide is intended for customer IT teams who administer the uploading machine. The guide describes the setup of the SFTP access, the rules for the files, the automation of the upload, and troubleshooting.

If your customer system can send HTTP requests, you can alternatively transmit the data without an export file via the REST import API.

The following diagram shows the infrastructure and the path of a file from the customer network to VAT:

Shows the infrastructure of the file import via SFTP for Lucanet VAT in three zones. On the left, the 'Customer network' with 'ERP export/export folder', 'SFTP client or sync tool', 'Private key (ed25519)', 'Firewall/proxy', and 'No inbound access'; in the middle, the 'Internet' with 'SFTP over SSH, port 22'; on the right, the 'Lucanet CFO Solution Platform' with 'SFTP endpoint' and 'Host key of the endpoint' as well as 'Your Lucanet environment' with the 'Share/' and 'Archive/' folders and the 'Lucanet VAT' module with the areas 'Import', 'Pre-Import', and 'Processing'. Numbered arrows 1 to 5 show the path of a file from the 'SFTP upload' to processing.
Infrastructure and data flow of the file import via SFTP in VAT

A file reaches VAT via SFTP as follows:

  1. You upload the file via SFTP to the Share/ folder.
  2. The SFTP endpoint stores the file in the encrypted storage area of your Lucanet environment.
  3. The import in VAT reads the Share/ folder and checks every file name against the filename pattern.
  4. VAT moves processed files to the Archive/ folder. As a result, the files disappear from Share/.
  5. VAT stores the data in the Pre-Import. From there, the data goes into regular processing.

The platform never opens a connection into your network. You upload the files, and VAT collects them.

The following table summarizes the characteristics of the file import via SFTP in VAT:

CharacteristicDescription
TransportYou upload the files via SFTP to the storage area of your Lucanet environment.
DirectionVAT reads the files from the storage area.
AuthenticationThe sign-in to the SFTP endpoint uses an SSH key pair of the ed25519 type.
TriggerThe import in VAT triggers the processing, not the upload.
MetadataVAT recognizes the company, report, and period from the file name.
Interface type in VATVAT uses the Network drive interface type.
Typical useThe file import suits existing file export routes and companies that previously imported via a network drive.

The file import via SFTP applies to the import of the VAT reports. The file import via SFTP is not available for VAT Audit.

Make sure that the following prerequisites are met in your company before you transfer files to VAT via SFTP:

  • Machine: A machine in your network contains the export folder and uploads the files. For the setup, you usually need administrator rights on this machine.
  • Network: Firewall and proxy allow outbound SFTP connections via TCP 22 to the regional SFTP endpoint.
  • SFTP client: An SFTP client such as WinSCP, FileZilla, Cyberduck, or OpenSSH sftp is installed. For automated operation, you additionally need a sync tool.
  • Password manager: A password manager holds the backup of the private key.

You receive the following information and files from Lucanet:

  • the onboarding kit lucanet-sftp-keygen-version.zip with generators for Linux, macOS, and Windows
  • the host of the SFTP endpoint in the region in which the data of your Lucanet environment is stored
  • your user name for the SFTP endpoint
  • the Share/ target folder and a sample file name according to which you name your export files

Lucanet and your IT team share the setup of the file import via SFTP in VAT. The following table shows the steps and the role that executes each step:

StepRoleContent
1LucanetLucanet sets up the storage area and the SFTP user for your Lucanet environment.
2LucanetLucanet creates an interface of the Network drive type in VAT, maintains the filename pattern, and executes the connection test.
3LucanetLucanet provides you with the onboarding kit, the host, the user name, and the sample file name.
4CustomerYou generate an SSH key pair.
5CustomerYou send only the public key to Lucanet.
6LucanetLucanet registers your public key, compares the fingerprint with you, and confirms the host and user name.
7CustomerYou allow the connection in the firewall, check the host key, and test the connection.
8CustomerYou upload a test file to the Share/ folder.
9CustomerYou execute the import in VAT and check the result.
10CustomerYou automate the upload and monitor it.

Between step 5 and step 7, you wait for Lucanet. As long as Lucanet has not registered your public key and confirmed the host and user name, every sign-in fails. The failed sign-in is not a misconfiguration on your side, but the handover point in the process.

For VAT to find the uploaded files, an interface of the Network drive type exists in VAT. Lucanet creates the interface at the start of the project in the Interface configuration workspace. You access the workspace via the gear icon in the top right corner.

On the Lucanet CFO Solution Platform, VAT hides the Path to netdrive and Path to archive directory fields because VAT automatically uses the Share/ and Archive/ folders of your storage area. In the interface, you maintain the Filename pattern, for example:

text
    
  

The page for creating an interface of the Network drive type is displayed in VAT as follows, for example:

Shows the 'Interface configuration: Network drive' page in VAT with the 'Connection test' and 'Save' buttons, the mandatory 'Name' field, the 'File type' drop-down list, the 'Default interface' drop-down list with the value 'No (optional)', and the 'Filename pattern' field.
The 'Interface configuration: Network drive' page

The Connection test checks reading and writing in one step: VAT reads the Share/ folder and creates an empty test file in Archive/, which VAT then deletes again. Lucanet executes the connection test before you upload for the first time. This way, Lucanet can reliably distinguish permission errors from upload problems.

Lucanet defines the specific filename pattern with you during the project. You receive a sample file name based on the pattern, according to which you name your export files, as described in the File Names for the File Import via SFTP in VAT section.

The sign-in to the SFTP endpoint for VAT uses an SSH key pair of the ed25519 type. You generate the key pair on the machine that will upload the files later. The onboarding kit from Lucanet contains generators for all platforms. Any OpenSSH installation generates the key pair just as well.

To generate the SSH key pair for the file import via SFTP in VAT:

Leave the passphrase empty if the upload is to execute unattended, because a service cannot respond to an input request. In this case, the file permissions protect the private key: mode 0600 on Linux and macOS, a restricted ACL on Windows. The generator of the onboarding kit already sets these permissions.

For the registration at the SFTP endpoint for VAT, Lucanet needs only the public key. Send the lucanet-sftp.pub file to Lucanet via the agreed secure channel.

The private key never leaves the machine. Store a backup of the private key in the password manager. If the private key is lost, generate a new key pair and send the new public key to Lucanet.

Lucanet checks the public key before the registration. A public key is a single line that starts with ssh-ed25519, ssh-rsa, or ecdsa-sha2-. If the file sent starts with -----BEGIN ... PRIVATE KEY-----, it is the private key: Lucanet then does not import the file, deletes it, and requests a new key pair.

After the registration, Lucanet compares the fingerprint of the public key with you and confirms the host and user name.

To replace the key without downtime, send the new public key to Lucanet, switch to the new private key after the confirmation, and only then ask Lucanet to delete the old public key. The deletion takes effect immediately, and you cannot undo it.

Before you upload the first file for VAT, allow the connection and check the identity of the SFTP endpoint. To do so, allow outbound connections via TCP 22 to the host of your region in the firewall and proxy.

To record the host key of the SFTP endpoint for VAT and display its fingerprint, for example for the Frankfurt region:

bash
    
  

Compare the displayed fingerprint with the fingerprint of your region. The following table shows the hosts and fingerprints of the SFTP endpoints:

RegionHostFingerprint
eu-central-1, Frankfurteu-central-1.sftp.platform.lucanet.cloudSHA256:JV+0dVOFVOMOA8Zn5gRhpSVQZALjsoY7OD+fPfJiqLM
eu-north-1, Stockholmeu-north-1.sftp.platform.lucanet.cloudSHA256:ROlNNvtVe5BCAeIYJOrBfiXKhLua6Upml3k427EG3WQ

Each region has its own endpoint and therefore its own fingerprint. Compare the line for the host that Lucanet gave you. Both host keys are 4096-bit RSA keys; ssh-keygen -lf reports them as 4096 SHA256:… (RSA).

If the fingerprint differs, stop and contact Lucanet. Do not simply read in the host key again. ssh-keyscan trusts the server that answers at that moment. If the connection were intercepted, you would store the attacker's key, and every later check would confirm it. Only the comparison with the published fingerprint closes this gap. The same rule applies later: A host key error in an active route is a reason to stop and ask, not a reason to delete known_hosts.

Then test the connection. Replace user-name with the user name that Lucanet confirmed to you:

bash
    
  

For the first upload to the storage area for VAT, use a test file without real data.

To upload the test file for VAT with OpenSSH sftp:

bash
    
  

In a graphical SFTP client, enter the host, port 22, and the user name, select the lucanet-sftp file as the identity file, and drag the file to the Share/ folder.

Always upload the files to the Share/ folder. The import in VAT does not find a file in the root directory of the storage area.

After the upload, start the import in VAT. For a single company, click Import from network drive in the Import workspace. For several companies, click Update import data in the Mass Data Import workspace.

The import reads the Share/ folder including all subfolders and checks every file name against the filename pattern. VAT stores processed files under Archive/<unitId>/<date>#<time>/ and removes them from Share/. To do so, VAT first copies every file to Archive/ and then deletes it in Share/.

After the import, check whether the company and the period are correct, and compare the totals with the source report. If the test file is not to remain in the archive, ask Lucanet to remove the test file.

For VAT to accept and recognize an uploaded file, follow the rules below for file extensions, file names, and storage locations.

The SFTP endpoint accepts only certain file extensions during the upload. The check takes place on the server, and no client can bypass it. Downloads are not restricted.

The following rules apply to the file extensions:

  • Allowed extensions: The SFTP endpoint accepts the .csv and .txt extensions. The .txt extension covers the SAP standard reports RFUMSV00, RFUMSV10, RFBILA, and RFASLM, which all export as TXT.
  • Spelling: The extension is written entirely in lowercase or entirely in uppercase: .csv, .CSV, .txt, or .TXT. The SFTP endpoint rejects mixed spellings such as .Csv. If a tool creates the extension in a mixed spelling, correct the extension in the export.
  • Content: The SFTP endpoint checks only the extension and not the content. VAT checks the format only during the import.

VAT recognizes the company, report, and period from the file name. VAT compares only the file name and not the path. VAT also finds a file in a subfolder of Share/, but the name of the subfolder plays no role in the recognition.

Lucanet configures the filename pattern per interface and gives you a specific sample file name for your export route. Such a file name looks like this, for example:

text
    
  

If the file name does not match the filename pattern, the file remains unnoticed in Share/. VAT neither imports nor archives the file and displays no error message. An unmatched file name is the most frequent error in a new export route.

The storage area for the file import via SFTP in VAT contains the following folders:

FolderWritten byContent
Share/CustomerThe folder contains the files to be imported. You have full SFTP access to this folder.
Archive/VATThe folder contains the processed files, stored under Archive/<unitId>/<date>#<time>/.

The Share/ folder is your customer area. Therefore, VAT never writes to this folder. Everything that VAT stores itself is in the Archive/ folder.

If you do not want to execute the upload for VAT manually, automate it with a sync tool. For occasional transfers, an SFTP client is the recommended approach supported by Lucanet.

Lucanet guarantees the SFTP endpoint, that is, the availability of the host and the acceptance of your key. Setup, operation, and troubleshooting of a sync tool including scheduling and logs are your responsibility and are not part of Lucanet Support.

You can choose any sync tool. rclone is well suited: The tool consists of a single executable file, supports SFTP natively, offers filter rules, and needs no background service. The following sections use rclone as an example to describe the points that decide whether a route operates stably.

Use rclone copy. The command adds and updates files, but deletes nothing on either side.

Do not use rclone sync. The command turns the storage area into a mirror image of the local folder and therefore deletes files that VAT has not processed yet.

The SFTP endpoint does not store a modification time. Therefore, the default comparison of time and size considers every file changed and uploads it again endlessly. Use --size-only instead. The --checksum option does not help because the SFTP endpoint does not provide checksums.

The size comparison does not detect a change if the file size remains the same. Therefore, always write exports under a new file name instead of overwriting an existing file.

The following configuration connects rclone to the SFTP endpoint in Frankfurt. Replace the host, user name, and paths with your values:

ini
    
  

The following settings are required for the SFTP endpoint:

  • shell_type = none: The SFTP endpoint is a managed SFTP service without a shell. Without this setting, rclone searches for a shell and logs failures.
  • md5sum_command = none and sha1sum_command = none: Checksums require a shell, which does not exist here.
  • set_modtime = false: The SFTP endpoint does not accept modification times.

Save the configuration file as UTF-8 without BOM. A leading BOM causes rclone to skip the [lucanet] section.

Store the private key in a directory that only administrators or the executing service account can read. The key file contains the complete block from -----BEGIN OPENSSH PRIVATE KEY----- to -----END OPENSSH PRIVATE KEY----- with LF line endings. A truncated key or a key converted to CRLF fails in the SSH handshake with the uninformative message EOF.

Set up the upload as a scheduled task that executes one run and then ends, and not as a service. A scheduled task has no state that can become corrupted. Note the following points:

  • Preventing overlaps: Two simultaneous runs of the same route transfer the same files twice if there is a backlog.
  • Identity: The executing account must be able to read the private key and the source folder. The SYSTEM account reads local paths, but no UNC or network shares. If the export folder is on a share, the scheduled task needs a service account with access to the share and the key.
  • Rotating the log: The file that you specify with --log-file grows without limit.
  • Alerting on errors: A scheduled task that starts to fail is silent by default. Set up alerting on the return code or on the age of the most recent file in Share/.
  • Interval: Five minutes is a good starting value. Below one minute, mostly additional traffic arises without making the data noticeably more current.

Set the same extension filter locally that the SFTP endpoint allows. Otherwise, every run tries to upload all temporary and system files, and the SFTP endpoint rejects them. The filter is case-sensitive, like the rule in the Allowed File Extensions for the File Import via SFTP in VAT section. A suitable filter file looks like this, for example:

text
    
  

Use the Share/ folder, from which VAT reads, as the target path. Define the target path once and do not change it afterward.

Go through every route manually once before you automate it, including a test run with --dry-run:

powershell
    
  

The following table shows the most frequent errors in the file import via SFTP in VAT, their causes, and the solutions:

ErrorCauseSolution
The sign-in to the SFTP endpoint fails.Lucanet has not registered the public key yet, or the host or user name is wrong.Wait for the confirmation from Lucanet. Check the host, port 22, the user name, and the private key used.
The SFTP endpoint rejects an upload.The file extension is not allowed or is written in a mixed spelling, for example .Csv.Use .csv or .txt entirely in lowercase or entirely in uppercase.
A route that has been working reports a host key error.Lucanet has replaced the endpoint, or someone is intercepting the connection.Stop the route and clarify the error with Lucanet. Do not simply delete known_hosts.
The SSH handshake aborts with EOF.The private key is incomplete or stored with CRLF line endings.Store the complete BEGIN/END OPENSSH PRIVATE KEY block with LF line endings.
An automated run cannot read the key or the source folder.The scheduled task executes as SYSTEM, and the export folder is on a network share.Use a service account with access to the share and the key.
Every run transfers the same files again.The sync tool compares by modification time, which the SFTP endpoint does not store.Switch to the size comparison with --size-only.
The files are in Share/, but the import in VAT finds nothing.The file name does not match the filename pattern.Check the file name against the sample file name from Lucanet. VAT compares only the file name and not the path.
The files are in the root directory, and the import in VAT finds nothing.The upload does not target the Share/ folder.Upload the files to the Share/ folder.
The import is successful, but the files remain in Share/.After copying the files to Archive/, VAT could not delete them from Share/.Contact Lucanet. As long as the files remain in Share/, VAT can read them again during the next import.

Before you start, clarify whether the following limits of the file import via SFTP in VAT fit your requirements:

  • Local deletions: A sync tool uploads and updates files. If you remove a file locally, the file remains in the storage area. Only Lucanet can remove the file there.
  • No import through the upload: VAT reads a file only during the next import. If you need a time relationship, align the upload window and the import with each other.
  • Support boundary: Lucanet guarantees the SFTP endpoint, that is, the availability of the host and the acceptance of your key. A self-operated sync tool including scheduling, logs, and behavior is your responsibility.
  • User name: Lucanet derives the user name from your Lucanet environment. You cannot choose the user name freely. The user name is entirely in lowercase.
  • VAT Audit: The file import via SFTP applies to the import of the VAT reports and not to VAT Audit.

The following checklist summarizes what your IT team has completed before the file import via SFTP in VAT goes live:

  • [ ] Key pair generated, only the file with the .pub extension sent, private key backed up
  • [ ] Outbound connections via TCP 22 to the SFTP endpoint allowed
  • [ ] Host key checked against the fingerprint of your own region
  • [ ] Export files available as .csv or .txt, extension not in a mixed spelling
  • [ ] File names follow the agreed filename pattern
  • [ ] Upload targets the Share/ folder and not the root directory
  • [ ] One test file successfully uploaded and imported into VAT
  • [ ] For automation: copy instead of mirror command, size comparison, overlap protection, log rotation, and alerting set up

This content was generated using AI and reviewed by Lucanet subject matter experts before publication.