Send and receive via SFTP

This guide describes how to exchange invoices and credit notes with xTool via SFTP: set up access, name and upload files, read response XML, and receive inbound documents.

For CSV import via SFTP, see CSV import via SFTP and Import documents.

What SFTP is

xTool provides an SFTP server for your organisation. After you enable access in the web app, xTool shows Host, Port, and Username — you choose a password (or use a private key). Your ERP or integration client connects to this server and places files in the upload folder; xTool processes them and writes status XML to response folders.

Supported file types are the same as for web upload: XML and PDF invoices and credit notes in supported formats, and xTool CSV for import.

Set up access

1. Sign in to the xTool web app and select your organisation.
2. Open Interfaces → SFTP Configuration (requires permission to manage integrations).
3. Enter and confirm a password, then click Set Up SFTP.
4. Wait until access is ready (this can take up to 2 minutes). When active, the status turns green and connection details (Host, Port, Username) are shown.

Alternative: connecting with a private key is also supported instead of password authentication.

Actions on the SFTP page:

See Organisation and users for permissions.

File name rules

File names must not contain spaces, umlauts, or other special characters.

Allowed characters: a-z, A-Z, 0-9, ., _, -

Allowed extensions for invoice files: .xml, .pdf

Examples — correct:

• INV2020_158.xml
• INV2020_212.pdf

Examples — incorrect:

Use the + character as a separator when you need routing or conversion instructions in the file name (see below).

Complete invoice files

Send via Peppol — IDs in the XML

If sender and receiver Peppol Participant IDs are included in the invoice XML:

1
2

<unique-file-name>.xml
<unique-file-name>.pdf

Send via Peppol — IDs in the file name

If you cannot set Peppol IDs in the file content, pass them in the file name:

1

<unique-file-name>+<sender PEPPOL ID>+<receiver PEPPOL ID>.xml

Each Peppol ID consists of Electronic Address Scheme (EAS) and ID, separated by a dot.

Full EAS list: PEPPOL EAS codelist

Examples:

• 9930.DE279247134 — German VAT ID
• 0204.16067088 — German Leitweg ID
• 0088.5790000123456 — GLN

Example file name:

1

invoice-20200821-1+9930.DE279247134+9930.DE123456789.xml

Send via email

To send by email instead of Peppol, use:

1

<unique-file-name>+<email-receiver>.xml

Example:

1

invoice-20200821-1+receiver@webware24.de.xml

Convert before sending

Add a format code to request conversion before validation and sending:

1

<unique-file-name>+<format-code>.xml

Examples: 68451+fa3.xml, 68451+xrech_ubl.xml

Files with attachments

If you need XRechnung or Peppol BIS invoices with embedded attachments, use this naming convention:

Invoice file:

1
2

<unique-file-name>+source.xml
<unique-file-name>+source.pdf

Attachment files:

1

<unique-file-name>+attachment_<id>.<extension>

Allowed attachment extensions: jpg, jpeg, png, pdf, xlsx, ods

For Peppol routing via file name, use +source+ before the IDs:

1
2
3

invoice-20200821-1+source+9930.DE279247134+9930.DE123456789.xml
invoice-20200821-1+attachment_1.pdf
invoice-20200821-1+attachment_2.png

For email routing:

1
2

invoice-20200821-1+source+max@webware24.de.xml
invoice-20200821-1+attachment_1.pdf

Folder structure

When SFTP access is enabled, you get the following folder structure. You can add or delete files in these folders, but you cannot delete folders.

You can upload multiple files at once, including ZIP archives or folders. ZIP archives are unpacked; all files from subfolders (at any nesting level) are moved into upload and checked. Uploaded archives and empty folders are removed.

Outgoing invoices

Upload folder

To send an invoice via SFTP:

1. Upload a valid invoice file with a correct name to upload.
2. xTool registers the file and processes it (validate, optionally convert, send via Peppol or email).
3. The file is removed from upload after processing. You can view the document in the portal.

Example file names:

• INV2020_158.xml
• INV2020_212.pdf
• invoice+9930.DE279247134+9930.DE123456789.xml
• invoice+receiver@webware24.de.xml
• 68451+fa3.xml

Upload response folder

For each uploaded file, one or more response XML files are written to upload_response/<invoice_number>/ — one per processing step (for example validation, conversion, sending).

Response files are named:

1

<format>_<unix-timestamp>.xml

Examples:

• FA3_1713000000.xml (Validation Accepted)
• Inv-20200821-01/FA3_1713000001.xml (KSeF Accepted)

If validation or conversion fails, a response with status Validation Rejected or Conversion Rejected and an <Errors> block is created in the same subfolder.

Rejected folder

Files that fail basic checks before processing (unsupported extension, empty file, invalid characters in the name, unknown format code) are moved to rejected. For each such file, a text file with the reason is created:

1

<original-file-name>_<timestamp>_error.txt

Example:

• INV2020_144.xml
• INV2020_144_1592399949_error.txt

Incoming invoices

If your organisation is registered as a Peppol receiver, incoming invoices can be delivered to the download folder according to your Inbound File Delivery settings on the SFTP page.

Delivery mode

Delivery content

You can choose what to deliver:

• Original File — the received XML (or source file)
• PDF Visualization — PDF rendering of the invoice
• Attachments — decoded attachments from XML or extracted from ZUGFeRD PDF

Delivered files are named after the document number, for example:

1
2

68451.xml
68451.pdf

Download status folder

For every received invoice, a status file is created in download_status:

1

<document_number>_<timestamp>.xml

Example: 68451_1713000000.xml

See Receive via Peppol.

Response files

Each response XML contains a <Status> element describing the result of one processing step.

Possible status values:

• Validation Accepted / Validation Rejected
• Conversion Accepted / Conversion Rejected
• Upload Rejected
• Peppol Accepted / Peppol Rejected
• Email Accepted
• KSeF Accepted / KSeF Rejected

When a step fails, the response includes an <Errors> block with one or more error elements.

Outgoing — validation accepted

1
2
3
4
5
6
7
8
9

<?xml version="1.0" encoding="utf-8"?>
<Response>
  <File>INV2020_158.xml</File>
  <Time>2020-06-01 09:37:16</Time>
  <Format>PEPPOL BIS 3 Invoice</Format>
  <Sender>9930:987654321</Sender>
  <Receiver>9930:123456789</Receiver>
  <Status>Validation Accepted</Status>
</Response>

Outgoing — validation rejected

On validation errors, <Sender> and <Receiver> are set to 0088:0000000000000.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

<?xml version="1.0" encoding="utf-8"?>
<Response>
  <File>INV № 2020/144.xml</File>
  <Time>2020-06-01 09:37:16</Time>
  <Format>Undefined</Format>
  <Sender>0088:0000000000000</Sender>
  <Receiver>0088:0000000000000</Receiver>
  <Status>Validation Rejected</Status>
  <Errors>
    <Error>Incorrect file name.</Error>
  </Errors>
</Response>

Outgoing — Peppol accepted

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

<?xml version="1.0" encoding="utf-8"?>
<Response>
  <File>INV2020_158.xml</File>
  <Time>2020-06-01 09:37:16</Time>
  <Format>PEPPOL BIS 3 Invoice</Format>
  <Sender>9930:987654321</Sender>
  <Receiver>9930:123456789</Receiver>
  <Status>PEPPOL Accepted</Status>
  <Details>
    <MessageTime>2020-06-01T09:35:30Z</MessageTime>
    <MessageUID>b07fba39-496f-49cb-b910-3f52a3658c82@receiver</MessageUID>
    <InvoiceUID>c24b8882-b6f3-4df2-a13f-db3d62d53a36</InvoiceUID>
  </Details>
</Response>

Incoming — download status

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<?xml version='1.0' encoding='utf-8'?>
<InboundNotification>
  <DocumentNumber>68451</DocumentNumber>
  <Time>2026-04-16 12:34:56</Time>
  <Status>SUCCESS</Status>
  <DeliveredFiles>
    <File>68451.xml</File>
    <File>68451.pdf</File>
  </DeliveredFiles>
</InboundNotification>

KSeF conversion chain (example)

When you upload a Peppol BIS 3 invoice with +fa3 in the file name (for example 603275+fa3.xml), xTool validates, converts to KSeF FA (3), and submits to KSeF. Response files for each step are written to upload_response/<invoice_number>/. On success, the KSeF reference number is included:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<?xml version="1.0" encoding="utf-8"?>
<Response>
  <File>603275.xml</File>
  <Time>2026-03-31 15:14:00</Time>
  <Format>KSeF FA (3)</Format>
  <Sender>9945:PL5252567476</Sender>
  <Receiver>9945:PL9581498695</Receiver>
  <Status>KSeF Accepted</Status>
  <KSeF>5252567476-20260331-6B31C2000000-54</KSeF>
</Response>

After successful KSeF submission, the converted FA (3) document is saved in the same subfolder, for example FA3_1743429240.xml.

See Status lifecycle.

CSV import via SFTP

Place .csv files in the upload folder. Each file must contain one invoice or credit note in xTool CSV v1.0 format. xTool uses the same importer as the web and API.

Filenames can include + routing (same pattern as for XML). See Import documents — SFTP for CSV-specific rules and CSV import format for column specification.

Next steps

• Import CSV — Import documents
• Supported formats — Formats
• Send via Peppol — Send via Peppol
• Send by email — Send by email
• Receive via Peppol — Receive via Peppol
• Help — Support

← Import documents · Send via Peppol