Skip to content

Import documents

This guide describes how to import invoices and credit notes into xTool from an xTool CSV file — via the web interface, REST API, or SFTP. For the CSV column specification and examples, see CSV import format.

What import is

Import means ingesting a source file, parsing and validating it, and creating a stored document in xTool. The importer converts the file into the internal xTool model (xtool.invoice.1_0 or xtool.credit_note.1_0 when document_type_code is 381).

Currently, the only supported import source is xTool CSV version 1.0 (semicolon-delimited).

The result is a document with an id. You can then edit it, convert it to a target format (e.g. XRechnung or Peppol BIS), send it (Peppol, email), or use other document operations. See Document model and Status lifecycle.

Import vs create or upload

Aspect Create / Upload Import (CSV)
Input JSON model (form/API) or XML file xTool CSV file
Format Working format (e.g. XRechnung UBL, Peppol BIS) or internal model CSV is not a working format — import-only
Stored as Chosen or detected format / model Internal xTool model after conversion
CSV kept? — No — CSV is not stored as document content
  • Create — Fill the unified form or POST a JSON model. See Create documents.
  • Upload — Upload an XML invoice or credit note in a supported format. See Create documents.
  • Import — Upload a CSV file; xTool parses it and creates a document from the internal model. CSV cannot be chosen as a document format, sent, or validated via the Format API as a format code.

For field semantics after import, see Format models. For CSV columns and file structure, see CSV import format.

Web: Import from CSV

  1. Documents → Import (requires permission to create documents).
  2. Select an xTool CSV file (.csv, semicolon-delimited, version 1.0).
  3. Submit. The file is parsed, validated, and stored as an outbound document.
  4. On success you are redirected to the document details page. On validation failure, a validation report is shown (CSV parse or model errors).

Direction

The web import creates outbound documents. Use the API if you need a different direction.

See Documents interface.

API: Import CSV

Send a POST request with the raw CSV body.

Endpoint: POST /api/v2/documents/import/csv

Permission: api.v2.documents.import.csv (include it when creating the API key).

Headers: x-api-key, Content-Type: text/csv

Query parameters:

Parameter Default Description
direction outbound Document direction (outbound or inbound).
require_valid true If true, invalid documents are rejected with a validation report.

Body: Raw CSV file content (UTF-8).

Response: Created document details (including id). Use this id for send, get, list, or convert.

1
2
3
4
curl -X POST "https://xtool.invoice-portal.de/api/v2/documents/import/csv?direction=outbound" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary "@invoice.csv"

Error responses:

  • 400 — Parse or validation error (validation report in the response body when require_valid=true).
  • 409 — Format not recognized or unsupported.

See Setup, API keys and logs, and API Reference.

SFTP: Automatic CSV import

Place .csv files in the SFTP upload folder. xTool processes them with the same importer as the web and API. For SFTP setup, folder structure, and file naming, see Send and receive via SFTP.

CSV files on SFTP

  • Place .csv files in the upload folder. Each file must contain one invoice or credit note in xTool CSV v1.0 format.
  • The importer runs automatically: CSV is parsed, validated, converted to the internal model, and a document is created.
  • Processed files are removed from the upload folder; status or errors may be written to a response folder depending on your configuration.

Optional filename routing

Filenames can include routing information using a + separator (same pattern as for XML on SFTP):

Pattern Example Effect
file.csv invoice.csv Import only; recipient from document metadata
file+receiver.csv invoice+buyer@example.com.csv Route for email delivery after processing
file+sender+receiver.csv inv+1234.DE123456789+5678.DE987654321.csv Peppol routing (sender and receiver in filename)

After import, treat the document like any other: convert to the target format if needed, then send via Peppol or email. See Send by Peppol and Send by email.

Next steps