How can we help you?

Help articles

In this section of the Billit website, you will find manuals and explanations about all the features in Billit. You can find help articles using the search function or through the menu structure on the left which follows the menu-structure in Billit.
search

SFTP

  • Activate the SFTP connection
    Down

    (S)FTP stands for (Secure) File Transfer Protocol: a standard way to exchange files between servers. SFTP sends those files over an encrypted SSH connection, so it is more secure than FTP.

    Does your company already run an SFTP server? Then you can connect it to Billit. Billit logs in to your server every 20 minutes (at :00, :20 and :40 past the hour) and:

    • imports the invoices you place in a folder (incoming flow), and/or
    • exports your approved invoices and credit notes to another folder (outgoing flow).

    You can turn on one flow or both. You host and manage the server yourself: Billit does not provide an SFTP server for this integration.

    Two different integrations

    Under Settings > Integrations you will find two integrations with a similar name:

    Integration Direction Use it to
    SFTP Two-way (import and/or export) Sync invoices automatically between your own SFTP server and a company in Billit.
    FTP Export only Send a client file from the accountant portal to an FTP(S) or SFTP address: sales and purchase invoices, documents and CODA files.

    This article covers the SFTP integration, which handles the incoming and outgoing flows.

    Activating the SFTP integration

    1. Log in to Billit and open the company you want to connect.
    2. Go to Settings > Integrations.
    3. Choose SFTP and click Available.
    4. Fill in the connection details (see Connection settings below).
    5. Turn on Enable export of documents and/or Enable import of documents, and fill in the settings for each flow.
    6. Click Save.

    When you save, Billit tests the connection:

    • It places a small test file (test<number>.txt) in each folder you enabled.
    • In the import folder, it then moves the test file to the success folder or deletes it, depending on your settings.
    • If a folder does not exist yet, Billit creates it.

    If the test fails, you see the error message from your server and nothing is saved. Check your host, port, credentials and folder permissions.

    Go to the settings

    Use the link below to open the settings in Billit, then choose Integrations.

    Connection settings

    Field Description
    Type Select SFTP.
    Host Your server's host name or public IP address, for example sftp.mycompany.com. Internal or private addresses (such as 192.168.x.x or 10.x.x.x) are not accepted.
    Port Default: 22.
    Username The user Billit logs in with.
    Password The user's password. When you edit the integration later, leave this field empty to keep the saved password.
    Private key file Optional. Upload a private key to log in with a key instead of a password. When a private key is present, it is always used instead of the password.
    Password for the private key The passphrase of the private key, if it has one.

    Tips

    • Give the SFTP user permission to read, write, create folders, rename or move, and delete in the folders you configure.
    • Does your server only accept known IP addresses? Then allow Billit's IP addresses (see below).
    • Don't know your credentials? Contact the IT partner who set up your server.

    IP addresses to allow

    Billit connects to your server from the IP addresses below. Allow all addresses for the environment you use.

    Environment IP addresses
    Production (my.billit.eu) 37.97.167.112, 37.97.163.23, 85.10.128.134, 93.119.11.128, 93.119.11.121, 85.10.143.148, 85.10.143.154, 87.253.157.124
    Sandbox (test environment) 141.138.138.64, 85.10.131.55, 93.119.12.17, 93.119.11.121

    Outgoing flow: exporting invoices from Billit to your server

    Turn on Enable export of documents to have Billit place your invoices on your SFTP server.

    Setting Default Description
    Folder where we may place the invoices /Input The folder on your server where Billit uploads files. Every file goes straight into this folder: Billit makes no subfolders.
    Type of invoice that we may place in the folder Empty (both) Income exports sales documents only. Cost exports purchase documents only. Leave it empty to export both.
    Place PDF in folder Off When on, Billit also uploads the invoice PDF and all its attachments next to the XML file.
    Export source UBL if present Off When on and the invoice came in as a UBL (for example via Peppol), Billit exports that original UBL file unchanged.
    Export as type Default UBL The XML format used when no source UBL is exported, such as Peppol BIS 3.0, XRechnung or a country-specific CIUS. The source UBL takes priority if that option is on.
    Encrypt the file with a public key None Optional. Upload an RSA public key (.pem). Billit then encrypts the files of each invoice into a single .zip file before uploading. Only the holder of the matching private key can open them.

    What is exported, and when?

    Billit checks for new documents every 20 minutes (at :00, :20 and :40). A document you approve now reaches your server within about 20 minutes. A document is exported when all of these conditions are met:

    • It is an invoice or a credit note.
    • It has been approved, and the approval happened after the export was activated. Older documents are not exported retroactively.
    • It was created in the last 4 months.
    • It matches the invoice type you chose (Income, Cost or both).
    • It was not imported through this same SFTP integration. This prevents documents from bouncing back and forth. To export it anyway, use Filter – Export invoices in the incoming flow.

    Each document is exported once. After the upload, the document's history shows that it was exported to SFTP.

    Files placed on your server

    For each document, Billit places:

    • <name>.xml: the UBL file. The PDF is embedded in the UBL when Place PDF in folder is on.
    • <name>.pdf: the invoice PDF (only with Place PDF in folder).
    • Any extra attachments of the document (only with Place PDF in folder).

    With Encrypt the file with a public key, these files are bundled per document into one .zip file containing:

    • payload.key.enc: a random AES key, encrypted with your public key.
    • payload.tar.enc: the files, encrypted with AES-256-CBC.

    If an upload fails

    Billit stops the export run for your company and tries again at the next run, 20 minutes later. Documents already uploaded in the failed run are remembered and not uploaded twice.

    Incoming flow: importing invoices from your server into Billit

    Turn on Enable import of documents to have Billit pick up files from your SFTP server every 20 minutes (at :00, :20 and :40). The files go to Fast input and are processed like any other uploaded document: they are recognised, categorised as sales or purchase, and become invoices.

    Setting Default Description
    Folder from which we may retrieve the invoices /Output The folder on your server where Billit looks for new files. Subfolders are not read.
    Synchronise the invoices in Billit from Empty Only files added or changed after this date are imported. Useful to skip an existing backlog.
    Handling of successfully read files – Move to success folder moves processed files to <folder>/Succes/. Delete from folder removes them from your server.
    Create new success folder for each day On With Move to success folder, files go into a subfolder per day: <folder>/Succes/yyyyMMdd/.
    Filter – Prefix file name Empty Only download files whose name starts with this text.
    Filter – Suffix file name Empty Only download files whose name (without the extension) ends with this text.
    Filter – Extension file name All checked Only download files with the checked extensions: .pdf, .xml, .jpg, .jpeg, .png and .zip.
    Filter – Sent status Empty Invoices whose file name contains this word are marked as sent in Billit. Useful for sales invoices you already sent outside Billit.
    Filter – Export invoices Empty Invoices whose file name contains this word are exported back to your export folder after they are created, for example to receive the processed UBL.
    PDF files as attachments Off Use .zip files to add PDFs as attachments to an existing invoice. The name of the .zip file must exactly match the invoice number in Billit, for example INV-2026-0042.zip.

    Note: If you choose neither Move to success folder nor Delete from folder, processed files are deleted from your server.

    Note: Filters are case-sensitive: invoice does not match Invoice_001.pdf. If you fill in both a prefix and a suffix, a file only needs to match one of the two.

    Supported files

    File What happens
    PDF, JPG or PNG Imported as a document and read by Billit's recognition.
    XML (UBL) Imported as a structured invoice.
    XML and PDF with the same name Handled as one invoice, for example INV001.xml and INV001.pdf. If the UBL contains no PDF, Billit embeds the PDF.
    ZIP Unpacked: every file inside is imported separately. With PDF files as attachments on, the PDFs are added to the matching existing invoice instead.

    Good to know

    Topic What to know
    Volume At most 5,000 files are read per run. Larger batches are picked up in the following runs.
    File names File names longer than 40 characters are shortened in Billit. The extension is kept.
    Duplicates Billit relies on processed files being moved or deleted. Don't put a file back in the import folder unless you want it imported again.
    Income or cost Billit decides this per document during processing. One SFTP connection always belongs to one company in Billit. To import for several companies, set up a separate integration (and folder) for each company.
    Failed files Failed files stay in the import folder and are retried at the next run. There is no separate error folder.

    Monitoring and error messages

    • You can follow the integration's activity under Settings > Integrations > Log.
    • If Billit cannot connect to your server for more than 1 day, a "Connection failed" notification appears in Billit, with the message "SFTP failed to upload/download with message: …". If Send e-mail on notification is turned on in your company settings, you also receive this notification by e-mail at your notification address.

    Note: If the connection keeps failing for 10 days, Billit deactivates the integration automatically. Fix the problem and activate the integration again.

    Common causes:

    Message from your server Likely cause
    No connection could be made because the target machine actively refused it / A connection attempt failed… Wrong host or port, the server is down, or a firewall is blocking Billit's IP addresses.
    Unable to resolve host The host name does not exist or is misspelled.
    Permission denied / Reached authentication attempt limit Wrong username, password or private key.
    Path not found / The file path does not exist or is invalid The folder was removed or renamed, or the user has no access to it.
    Quota exceeded Your SFTP storage is full. Remove or archive old files, for example in the Succes folder.
    SSH/SFTP are not enabled for this account The account only allows FTP. Ask your hosting provider to enable SFTP.
    Session operation has timed out / Channel was closed Unstable connection or a server timeout. This usually resolves itself at the next run.