Send and receive via SFTP

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

Incoming documents appear in the xTool web app (see Receive via Peppol). They are copied to the SFTP download folder only when Inbound invoices is enabled.

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. Your ERP or integration client connects to this server and places files in the upload folder. xTool processes them on a schedule 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. When setup succeeds, connection details (Host, Port, Username) are shown and the status is Active.

Password requirements: at least 12 characters; at least one uppercase letter, one lowercase letter, one digit, and one special character (!@#$%^&*()_+-=[]{}|;:,.<>?).

Login uses this password. Key-based login for the organisation account is not available.

Actions on the SFTP page:

xTool checks the upload folder about once an hour. Newly uploaded files are skipped until they are at least about 10 seconds old (so the transfer can finish). Source files with attachments wait up to 5 minutes for the attachment files to arrive.

See Organisation and users for permissions.

File name rules

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

Allowed characters in the base name: a-z, A-Z, 0-9, ., _, -

Allowed extensions for invoice files: .xml, .pdf, .csv

Examples — correct:

• INV2020_158.xml
• INV2020_212.pdf
• invoice.csv

Examples — incorrect:

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

Limits: one file up to 50 MB. Duplicate content (same SHA-256 hash as a file already processed for this organisation) is rejected. Hidden files (names starting with .) are ignored.

Complete invoice files

Send via Peppol — IDs in the XML

Put sender and receiver Peppol Participant IDs in the invoice XML (or PDF with embedded XML). Use a unique file name:

1
2

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

xTool validates the file, creates the document, and sends it via Peppol when the detected format supports Peppol. Addressing comes from the document content, not from the file name.

Send via email

To send by email instead of Peppol, put the recipient address in the file name:

1
2

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

Examples:

1
2

invoice-20200821-1+receiver@webware24.de.xml
68451+buyer@example.com+xrech_ubl.pdf

If the file name contains an email address, xTool sends by email, even if other + segments look like Peppol IDs.

Convert before sending

Add a format code to convert the file, or to recognize a Raw PDF, into a target format before sending:

1
2

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

The code may appear in any + segment after the base name (for example 68451+fa3.xml, 68451+xrech_ubl.pdf, or 68451+buyer@example.com+xrech_ubl.xml).

Unknown format codes are rejected.

Structured files (XML, PDF with embedded invoice, …)

When the file is already a structured e-invoice (for example Peppol XML or a ZUGFeRD / Factur-X PDF), a format code converts it to the target format and then sends it.

Raw PDF with a format code

A Raw PDF is a scan or an ordinary PDF without embedded e-invoice data. With a format code, xTool recognizes the invoice from the PDF and sends the recognized document. This is the same recognition as Format conversion in the web app.

Without a format code, SFTP does not run recognition. The file is stored as a Raw PDF. You can send it by email using the file name. Peppol is used only when the PDF already contains embedded invoice data (see above).

With a format code:

• On success, xTool sends the recognized invoice, not the original PDF. An email address in the file name still sends by email instead of Peppol, France, or KSeF.
• If recognition fails, xTool does not send. The file is removed from upload and is not moved to rejected. The original PDF, and the recognized invoice if one was created, stay in the portal so you can review them. The step response status is Recognition Rejected.

Examples:

1
2
3

68451+xrech_ubl.pdf
603275+fa3.pdf
68451+buyer@example.com+peppol_ubl.pdf

The +source workflow with attachments (below) is for XML invoices. It is not supported for Raw PDF recognition.

After conversion or successful recognition, the send channel follows the target format (and an email in the file name, if present): KSeF formats go to KSeF; Peppol-capable formats go to Peppol; French formats go to the France channel unless an email receiver is set. France send requires an active France configuration for the organisation that can issue invoices (not reception-only).

France receiver in the file name

For French target formats you can set the buyer in the file name (one + segment):

For a Raw PDF with a French format code, the buyer from the file name is used on the recognized invoice. If that buyer cannot be used, the response status is Recognition Rejected.

An email address in the file name still sends by email instead of France.

Upload only (hold)

Add the reserved segment hold in any + position after the base name to validate (and convert, if requested), save the document in xTool, and skip Peppol, email, KSeF, and France sending:

1
2
3

invoice+hold.xml
68451+xrech_ubl+hold.xml
invoice+source+hold+buyer@example.com.xml

You can combine hold with format codes, source, sender/receiver segments, and IDoc files (see below).

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>

<id> is 1–3 digits. Allowed attachment extensions: jpg, jpeg, png, pdf, xlsx, ods

xTool waits up to 5 minutes after the source file appears so attachments can be uploaded. A source file with no matching attachments is rejected.

You can add a format code and/or an email receiver after +source:

1
2
3

invoice-20200821-1+source+xrech_ubl.xml
invoice-20200821-1+attachment_1.pdf
invoice-20200821-1+attachment_2.png

1
2

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

Attachments are embedded into the invoice XML, then the original attachment files are removed from upload.

This flow is for XML invoices. It is not supported for Raw PDF recognition (see Raw PDF with a format code).

SAP IDoc

XML SAP IDoc invoices are recognised from the file content. By default, routing (email vs Peppol, XRechnung vs ZUGFeRD) is read from IDoc enhancement segments (X-E, X-P, Z-E, Z-P).

You may use the same + segments as for other files (hold, format codes, source, sender/receiver). File name instructions override IDoc routing when both are present — for example INVOIC+other@mail.com.xml sends to that email instead of ZZ_EMAIL_RE, and INVOIC+hold.xml saves to xTool without sending.

Without + segments in the name, behaviour is unchanged (for example invoice.xml).

Folder structure

When SFTP access is enabled, these folders are created. Leave the system folders in place.

Provisioning also creates /download_response and /tech. They are not used for the invoice flow described here.

You can upload multiple files at once, including ZIP archives or folders. ZIP archives are unpacked; files from subfolders are moved into upload (nested paths inside the ZIP are flattened to the file name only). The archive is then removed; empty nested folders are removed when possible.

ZIP limits: total extracted size 200 MB, at most 1000 files.

Outgoing invoices

Upload folder

To send an invoice via SFTP:

1. Upload a valid invoice file with a correct name to upload.
2. After the wait times above, xTool picks up the file on the hourly run (validate, optionally convert, send via Peppol, email, or KSeF).
3. On success the file is removed from upload. You can view the document in the portal.

Example file names:

• INV2020_158.xml
• INV2020_212.pdf
• invoice+receiver@webware24.de.xml
• 68451+fa3.xml
• 68451+xrech_ubl.pdf
• 603275+fa3.pdf

Upload response folder

For each processed invoice, one or more response XML files are written to upload_response/<invoice_number>/ — typically one per processing step (validation, conversion, upload to xTool, sending). The subfolder name is the document number from the invoice when it can be read; otherwise the file name without extension.

Step statuses include Upload Accepted / Upload Rejected when the document is stored in xTool. If conversion validation fails after a successful conversion, xTool still writes Conversion Rejected (with errors), saves the converted document in xTool as invalid, writes Upload Accepted, and does not send or move the file to rejected.

For a Raw PDF with a format code, the step response is Recognition Accepted or Recognition Rejected. If recognition is rejected, xTool does not send the invoice and removes the file from upload without moving it to rejected.

Step response files are named:

1

<format>_<unix-timestamp>_<unique>.xml

<unique> is a short random id, so several reports written in the same second do not overwrite each other.

<format> is the internal format code, for example peppol_bis_billing.invoice.3_0.xml_ubl or ksef_fa.invoice.3_0.xml — not a short label such as FA3.

After a successful conversion, the converted XML is also saved in the same subfolder as:

1

<original-stem>_<unix-timestamp>_converted.xml

If validation or conversion fails, a response with status Validation Rejected or Conversion Rejected and an <Errors> block is written in the same subfolder; the original file is then moved to rejected.

xTool may also write a summary file named <original-stem>_<unix-timestamp>_<unique>_response.xml with status VALIDATION_ACCEPTED or VALIDATION_REJECTED.

Rejected folder

Files that fail before or during processing (unsupported extension, empty file, invalid characters in the name, unknown format code, duplicate content, file larger than 50 MB, validation/conversion/send errors) are moved to rejected. The original name is not kept: the file is renamed to:

1

<original-stem>_<unix-timestamp><extension>

For each rejection, xTool also writes:

1
2

<original-stem>_<unix-timestamp>_error.txt
<original-stem>_<unix-timestamp>_response.xml

The text file contains File, Status (for example Validation Error or Duplicate), Time, and Details. The organisation also receives an email about the rejection.

Example: original INV2020_144.xml becomes INV2020_144_1592399949.xml plus INV2020_144_1592399949_error.txt.

Incoming invoices

Received invoices are available in the web app. See Receive via Peppol.

On Interfaces → SFTP Configuration, Inbound invoices controls whether a successfully received invoice is also copied to SFTP. The default mode is Disabled, so nothing is written until you choose a mode and at least one content type, then save.

After a successful receive (Peppol, email, KSeF, France, or Slovakia), xTool writes the selected files into /download/<document number>/:

Content can include the original XML, attachments, and a PDF rendering. A status file /download_status/<document number>_<timestamp>.xml is written with status SUCCESS or FAILED and the list of delivered files. A locked SFTP account is skipped.

Archive storage

On Interfaces → SFTP Configuration, Archive Storage controls whether successfully processed documents are copied to /archive/send or /archive/receive. Nothing is written until you enable archive storage and save.

Archive delivery runs only when the document status is send completed or receive completed. Failed sends and receives are not archived. This is independent of Inbound invoices in /download.

You can choose:

• Include PDF visualisation — adds {invoice_number}_visual.pdf (a separate human-readable PDF, not a copy of a PDF/A-3 invoice file).
• Storage layout — invoice file only in the root of send/receive (with timestamp in the file name), a folder {invoice_number}_{timestamp}/, or a ZIP {invoice_number}_{timestamp}.zip.
• Grouping — none, by year (/archive/send/2026/...), or by year and month (/archive/receive/2026/09/...).

The invoice file is always included. Root layout is available only when PDF visualisation is disabled.

Response files

Each step response XML contains a <Status> element for that processing step.

Status values written for outgoing files:

• Validation Accepted / Validation Rejected
• Conversion Accepted / Conversion Rejected
• Recognition Accepted / Recognition Rejected
• Attachment Embedding Failed
• Upload Rejected
• Peppol Accepted
• Email Accepted
• KSeF Accepted / KSeF Rejected
• Rejected (in /rejected for early failures)

Peppol Accepted and Email Accepted mean xTool has dispatched the send. They are not a confirmation from the Peppol network or the mail server. There is no Peppol Rejected status file on the success path; a send error moves the file to /rejected.

When a step fails, the response includes an <Errors> block. Each error is an <e> element (not <Error>).

<Format> is the internal format identifier (for example peppol_bis_billing.invoice.3_0.xml_ubl), not a display name. <Sender> and <Receiver> are taken from the document when they can be parsed; otherwise they may be empty or 0088:0000000000000.

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_billing.invoice.3_0.xml_ubl</Format>
  <Sender>9930:987654321</Sender>
  <Receiver>9930:123456789</Receiver>
  <Status>Validation Accepted</Status>
</Response>

Outgoing — validation rejected

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

<?xml version="1.0" encoding="utf-8"?>
<Response>
  <File>INV2020_144.xml</File>
  <Time>2020-06-01 09:37:16</Time>
  <Format>peppol_bis_billing.invoice.3_0.xml_ubl</Format>
  <Sender>9930:987654321</Sender>
  <Receiver>9930:123456789</Receiver>
  <Status>Validation Rejected</Status>
  <Errors>
    <e>Validation error: example message</e>
  </Errors>
</Response>

Early failures (before the document is parsed) use <Format>Unknown</Format>, empty <Sender> / <Receiver>, and <Status>Rejected</Status>. Those files land in /rejected.

Outgoing — Peppol 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_billing.invoice.3_0.xml_ubl</Format>
  <Sender>9930:987654321</Sender>
  <Receiver>9930:123456789</Receiver>
  <Status>Peppol Accepted</Status>
</Response>

KSeF conversion chain (example)

When you upload a Peppol BIS 3 XML invoice with +fa3 in the file name (for example 603275+fa3.xml), xTool validates the source, converts to KSeF FA (3), validates the result, and submits to KSeF. The organisation must already be connected to KSeF. Field mapping: Peppol BIS to KSeF FA(3). 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+fa3.xml</File>
  <Time>2026-03-31 15:14:00</Time>
  <Format>ksef_fa.invoice.3_0.xml</Format>
  <Sender>9945:PL5252567476</Sender>
  <Receiver>9945:PL9581498695</Receiver>
  <Status>KSeF Accepted</Status>
  <KSeF>5252567476-20260331-6B31C2000000-54</KSeF>
</Response>

The converted FA (3) document is saved in the same subfolder as <original-stem>_<unix-timestamp>_converted.xml.

For a Raw PDF with +fa3 (for example 603275+fa3.pdf), xTool recognizes the invoice as FA (3) and, when recognition succeeds, submits it to KSeF. The step response status is Recognition Accepted or Recognition Rejected.

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, then converts the result to the internal model and continues with validation and sending like any other file.

Add a format code (+fa3, +xrech_ubl, …) when the document must be converted before send. Put an email address in the file name to send by email after import.

Peppol sender and receiver must be in the CSV/document data, not in the file name. Segments that look like Peppol IDs in the file name are not applied to addressing.

See Import documents — SFTP and CSV import format.

Next steps

• Import CSV — Import documents
• Supported formats — Formats
• Connect to KSeF — Connect to KSeF
• 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