n8n-nodes-taxmetall

An n8n community node package that connects TaxMetall ERP and TaxDMS to your workflows. Read and create records across all major ERP domains — customers, articles, orders, offers, invoices, delivery notes, purchase inquiries, purchase orders, purchase invoices, suppliers, dunning — and run custom SQL reports and upload documents to TaxDMS, all directly from n8n.

TaxMetall is an ERP system for metal trading and processing companies, developed by Vectotax Software GmbH.

---

Table of Contents

• Installation
• Credentials
• Node: TaxMetall ERP
  • Acquisition
  • Article
  • Customer
  • Customer Inquiry
  • Delivery Note
  • Document Management
  • Document Sync (SharePoint WF1 / WF2)
  • Dunning
  • Invoice
  • Newsletter
  • Offer
  • Order
  • Purchase Inquiry
  • Purchase Invoice
  • Purchase Order
  • Statistic
  • Supplier
• Compatibility
  • Required TaxMetall API Service version
  • Finding your service version
• Resources
• License

---

Installation

Follow the n8n community nodes installation guide.

Via the n8n UI:

1. Go to Settings → Community Nodes
2. Click Install a community node
3. Enter @vectotaxsoftwaregmbh/n8n-nodes-taxmetall
4. Click Install

Via CLI:

npm install @vectotaxsoftwaregmbh/n8n-nodes-taxmetall

---

Credentials

Create a TaxMetall API credential in n8n (Settings → Credentials → New → TaxMetall API).

Field	Required	Description
Base URL	Yes	URL of your TaxMetall API service, e.g. https://api.example.com:8443
API Key	Yes	The tax-api-key configured in your TaxMetall API service
Use ngrok Tunnel	No	Enable if your TaxMetall instance is accessed via an ngrok tunnel — adds the ngrok-skip-browser-warning header to bypass the ngrok browser interstitial page
Ignore SSL Issues (Insecure)	No	Disable TLS certificate validation — enable only for on-premises installations using self-signed certificates. Named Allow Self-Signed Certificates up to 1.27.0; after updating to 1.27.1 or later it has to be switched on again once (see the changelog).

The API key is automatically injected as the tax-api-key HTTP header with every request.

Use the Test button to verify the connection. From service version 1.26.0 on, the response also
carries the version of the service you are connected to — worth checking against
Required TaxMetall API Service version before you build a
workflow around a newer resource.

---

Node: TaxMetall ERP

The TaxMetall ERP node covers all major TaxMetall domains. Select a Resource and then an Operation to configure the node.

Entering positions

Every operation that creates a document with positions (Offer, Order, Customer Inquiry, Purchase Inquiry, Purchase Order and Purchase Invoice in Parameters mode) has a Positions Input field:

• Manual List (default): one row per position, as in earlier versions.
• From JSON: the positions come as a JSON list, typically from a previous node via an expression such as {{ $json.positions }}. The list may also be wrapped in an object under positionen, positions, items or lines.
• Offer additionally offers Single Article, the default for workflows created before multiple positions existed.

The JSON keys are the ones of the TaxMetall API (for example artikelnr, menge, preis). From service version 1.27.0 on, the service also accepts keys in any letter case and common English alternatives: articleNumber/sku → artikelnr, articleId → articleid, quantity/qty → menge, price/unitPrice → preis, pricePer → preispro, discount → rabatt, description → bezeichnung, deliveryDate → liefertermin, unit → mengeneinheit.

[
  { "artikelnr": "A-100045", "menge": 5 },
  { "articleNumber": "A-100046", "quantity": 2 }
]

---

Acquisition

Manages acquisition/lead contacts in TaxMetall.

Create

Creates a new acquisition entry.

Field	Required	Description
Email	Yes	Contact email address
Company	Yes	Company name
First Name	No	Contact first name
Last Name	No	Contact last name
Phone	No	Phone number
Street	No	Street address
Postal Code	No	Postal code
City	No	City
Country	No	Country
Lead Source	No	Origin of the lead (e.g. trade fair, website)
Campaign Info	No	Associated campaign
Perspective Lead ID	No	External ID from Perspective CRM

Search by ID

Returns a single acquisition entry by its internal contact number.

Field	Required	Description
Acquisition ID	Yes	Internal contact number (KontaktNr)

Search by Name

Searches acquisition entries by partial match on company or contact name.

Field	Required	Description
Name	Yes	Partial name to search for

Search by Date Range

Lists acquisition entries by their first contact date.

Field	Required	Description
Date From	Yes	Start date in format yyyy-mm-dd
Date To	Yes	End date in format yyyy-mm-dd

---

Article

Manages articles (Artikel) in TaxMetall.

Create

Creates a new article. If no article number is provided, the next number from the configured number range is used automatically.

Field	Required	Description
Name	Yes	Article name / description (Bezeichnung)
Unit of Measure	Yes	Unit of measure, e.g. Stk, m, kg
Article Number	No	Article number — auto-assigned if left empty
Drawing Number	No	Drawing or part number (Zeichnungsnr)
Revision Number	No	Revision index
Material	No	Material designation, e.g. S235, 1.4301
Manufacturing Indicator	No	Manufacturing key (FertigungsKz)
Bill of Materials	No	0 = no BOM, 1 = is a BOM
Custom Tariff Number	No	Customs tariff number (Zolltarifnr)
Preliminary	No	Mark article as preliminary (Vorläufig)

Search by Article ID

Returns an article by its internal numeric ID.

Field	Required	Description
Article ID	Yes	Internal article ID (AID)

Search by Article Number

Returns an article by its exact article number.

Field	Required	Description
Article Number	Yes	Article number (Artikelnr)

Search by Drawing Number

Searches articles by drawing or part number.

Field	Required	Description
Drawing Number	Yes	Drawing number (Zeichnungsnr)

Search by Name

Searches articles by partial match on the article name.

Field	Required	Description
Name	Yes	Partial name to search for

---

Customer

Manages customers (Kunden) in TaxMetall.

Create

Creates a new customer.

Field	Required	Description
Company Name	Yes	Customer company name
Name Addition	No	Additional name line (Namenzusatz)
Street	No	Street address
Postal Code	No	Postal code
City	No	City
Country	No	Country name
ISO Country Code	No	Two-letter ISO code, e.g. DE, AT, CH
Email	No	Email address
Phone	No	Phone number
Website	No	Website URL

Search by ID

Returns a customer by their customer number.

Field	Required	Description
Customer ID	Yes	Customer number (Kundennr)

Search by Name

Searches customers by partial match on their company name.

Field	Required	Description
Customer Name	Yes	Partial name to search for

Search by Order ID

Returns the customer associated with a given order number.

Field	Required	Description
Order ID	Yes	Order number (Auftragnr)

---

Customer Inquiry

Creates and reads customer inquiries (Kundenanfragen) in TaxMetall — the request-for-quote a customer
sends you, before it becomes an offer. Backed by the ERP tables KundenAnfrage, KundenAnfragePos
and KundenAnfrageHistorie.

Requires TaxMetall API Service 1.25.0 or newer for all operations of this resource. See
Compatibility.

Create

Creates a new customer inquiry with one or more positions. A position may reference an article
(Article ID or Article Number) or be a pure free-text position — for a new part coming in as
a drawing, a Description alone is enough. When an article is given, description, unit, drawing
number, revision and the preferred supplier are taken from the article master.

Customer Source decides which master the customer number refers to: Existing Customer
(Kunden_s) or Prospect (Neukunden_s, the acquisition table also used by the Acquisition
resource). Address and contact data are copied into the inquiry header from whichever master applies.

Field	Required	Description
Customer Number	Yes	kundennr — for a prospect this is the KontaktNr
Customer Source	Yes	Existing Customer (default) or Prospect
Positions	Yes	At least one; Article ID, Article Number or Description per position
Additional Fields	No	Subject, inquiry channel, customer reference, priority, due date, project, note, …
History Entry	No	Optional first entry in the inquiry history

Some fields are validated against ERP selection lists (Listen) and are rejected with the list of
allowed entries if they do not match: Subject (KAnfrageBetreff), Order Type (Auftragsart),
Estimated Value (Schaetzwert) and, in the history entry, Text, Type, Contact Type and
Status. Inquiry Channel and Document Status are free text.

Note on Subject: in the ERP the subject line lives in the database column Status — the field is
named Subject here to match what the ERP mask shows. The workflow status is Document Status
(BelegStatus).

If positions carry a Value, their sum is written to the inquiry header, mirroring the ERP.

Search by Inquiry No.

Returns a single inquiry including its positionen[] and historie[].

Field	Required	Description
Inquiry Number	Yes	anfragenr

Search by Customer No. / Search by Email / Search by Date Range

Return a list of inquiry headers. Search by Email matches the email address stored on the inquiry,
which makes it useful for assigning an incoming mail to an existing inquiry.

Field	Required	Description
Customer Number / Email / Date From + Date To	Yes	Depending on the operation
Additional Filters	No	Document status, order type, priority, inquiry channel, project, offer number, customer reference, customer source, limit

---

Delivery Note

Reads delivery notes (Lieferscheine) including their line items.

Search by Delivery Note No.

Returns a single delivery note with all its line items.

Field	Required	Description
Delivery Note Number	Yes	Delivery note number (Lieferscheinnr)

Search by Customer No.

Lists all delivery notes for a given customer.

Field	Required	Description
Customer Number	Yes	Customer number (Kundennr)

Search by Date Range

Lists all delivery notes within a date range.

Field	Required	Description
Date From	Yes	Start date in format yyyy-mm-dd
Date To	Yes	End date in format yyyy-mm-dd

---

Document Management

Uploads files to the TaxDMS document management system (Vectotax Software GmbH).

Create File

Uploads a binary file together with a metadata object to TaxDMS via the /api/create-dms-file endpoint. The file is transferred as Base64.

Field	Required	Description
Data (JSON)	Yes	Metadata object — structure defined by your TaxDMS configuration
File (Binary)	Yes	Name of the n8n binary property that holds the file, e.g. data

Tip: Use an HTTP Request node, a Read Binary File node, or any node that outputs a binary property to provide the file. The value of File (Binary) must match the property name under which n8n stores the file in that node's output.

---

Document Sync (SharePoint WF1 / WF2)

Connects the TaxMetall document pocket (Dokutasche) with SharePoint through the TaxMetall document-sync work queue (APIEventTrigger / APIEventDetail). It implements two workflows:

• WF1 — Export (TaxMetall → SharePoint): claim newly created documents from the queue, download each file, upload it to SharePoint, then report the result back so the entry is closed or retried.
• WF2 — Import (SharePoint / mail → TaxMetall): create a document (typically an .eml built by the service) in TaxMetall and write a closing audit entry, with optional deduplication by mail message ID.

The service stores the resulting SharePoint URL under Payload.sharePoint.mainUrl and, for WF2, the mail ID under Payload.email.messageId.

Requires TaxMetall API Service 1.20.3 or newer; the Unpack MSG File operation requires
1.23.2 or newer. See Compatibility.

Check New Documents

Claims up to Limit pending entries from the work queue and returns the list of documents to process (WF1, step 1). Claim locking is handled in-memory per tenant by the service — there is no token to pass around.

Field	Required	Description
Limit	No	Max number of documents to claim in one call (default 50). The service caps this at its configured maximum.

Important response fields:

Field	Description
busy	true when another batch is still being processed; then documents[] is empty and nothing is claimed — simply poll again later
documents[]	Entries ready for processing
documents[].syncId	Queue entry ID — needed for download and status report
documents[].downloadUrl	Ready-to-use relative URL /api/document-file?syncId=… (CREATE only)
documents[].eventTyp	Event type as integer: 1 = CREATE, 3 = DELETE
documents[].aktion	The same event as text: CREATE or DELETE
documents[].belegTyp / belegNr	Business document type (e.g. Auftrag, Rechnung, Angebot) and document number — the internal table name is not exposed
documents[].dateiname	Source file path/name
documents[].email	For mail documents (Typ=2) on CREATE events: { from, to, subject, date } from the document record — handy when uploading the mail to storage. Absent for non-mail documents.
documents[].payload	For DELETE events only: the full payload object that was stored on the prior upload (the transfer-status payload, or — for documents imported via Create Document — { "sharePoint": { "mainUrl": … } }), so you can remove the file from SharePoint. Read the URL from payload.sharePointUrl or payload.sharePoint.mainUrl. null if no prior upload is found / already purged by retention.
skipped[]	Entries the service skipped this batch (informational only — nothing to download/upload) — dms_reference (a DMS: pointer, not a local file) or file_not_found (the referenced file is no longer on disk). Both occur only on CREATE events and the queue row is removed permanently.

Coalescing (per file path): Between two polls the same file can be created/deleted several times (e.g. created → deleted → created). For SharePoint only the final state matters. Coalescing is handled in the ERP trigger itself (only the latest event per file path / highest syncId is kept in the queue), so superseded earlier events never reach check-new-documents — there is no superseded skip reason. Combined with the delete correlation this means: a created→deleted pair where nothing was ever uploaded collapses to a no-op (the kept DELETE event returns payload: null), while created→deleted→created collapses to a single upload of the latest version.

Download Document File

Downloads the file of a single claimed entry as binary data (WF1, step 2). The node parses the file name from the response and sets the MIME type automatically.

Field	Required	Description
Sync ID	Yes	syncId of the entry (from Check New Documents)
Put Output File in Field	Yes	Name of the binary property to write the file to (default data)

The downloaded file is placed in the chosen binary property, ready for an upload node (e.g. HTTP Request or a Microsoft SharePoint node). The item JSON also carries syncId, fileName and mimeType.

Check & Download New Documents

Combines Check New Documents and Download Document File into a single step (WF1, steps 1 + 2). It claims a batch from the queue and downloads the file for each CREATE entry (those with a downloadUrl) — so you no longer need a Split/loop + a separate download node.

Field	Required	Description
Limit	No	Max number of documents to claim in one call (default 50). The service caps this at its configured maximum.
Put Output File in Field	Yes	Name of the binary property to write each file to (default data)

Output: one item per claimed document — and exactly one summary item when nothing was found, so the node always returns something to branch on.

• Nothing found: a single item { "success": false, "count": 0, "description": "No new documents found" } (no binary). Use this to drive a "nothing to do" branch.
• Documents found: one item per claimed document. Every item carries success: true, count (number of documents in the batch) and index (0-based position), in addition to:
  • CREATE entries (with a file): the full document metadata plus fileName and mimeType; the file is in the chosen binary property — ready to wire straight into an upload node.
  • Non-file events (e.g. DELETE): metadata only, no binary.
  • If a single file fails to download (it was removed or skipped server-side between claim and download), that item carries downloadError and httpCode instead of a binary; the rest of the batch still comes through.

Tip: filter downstream on {{ $json.success }} to separate the "found" items from the empty-result item.

Because the syncId is on every found item, a downstream Report SharePoint Transfer Status can acknowledge each entry as usual. Use the low-level Check New Documents / Download Document File operations only when you need full manual control over the claim/download split.

Report SharePoint Transfer Status

Reports the upload result back to the service (WF1, step 4).

Field	Required	Description
Sync ID	Yes	syncId of the entry
Success	Yes	true = synced successfully, false = transfer failed
Payload Fields	No	Shown when Success is on — custom key/value pairs stored as the entry payload (flat JSON), e.g. Key sharePointUrl with the uploaded URL. Stored verbatim and returned in full on a later DELETE event (documents[].payload) so you can act on it. Keys must be non-empty and unique; values are sent as strings. Total payload limited to 8 KB.
Error Message	No	Shown when Success is off — error text recorded for the failed transfer

Retry handling: on success = false the service keeps the work-queue row, so the document is retried on the next poll — unconditionally and without limit (there is no retry counter and no dead state). The failure is recorded only in the service log.

Create Document

WF2: creates a document in TaxMetall from mail data. When no existing file path is supplied, the service builds a standards-compliant .eml (via Indy) from the email fields and attachments, links it to the target record, and writes a closing audit entry (Quelle = API:create-new-dokument). A CONTEXT_INFO marker prevents the ERP trigger from re-syncing the document (no loop).

Field	Required	Description
Area (Bereich)	Yes	Target area, chosen from a dropdown. Position documents are attached to the article, so use Article (Artikel) for those.
Document Number (Belegnummer)	Yes	Number of the target record. For position documents use the article number.
SharePoint URL	No	Optional source SharePoint URL (stored under Payload.sharePoint.mainUrl when set). Leave empty to create the document without a SharePoint reference — e.g. when the export to storage is handled later by WF1 (enable Also Export to Storage).
Email To	No*	Recipient address (email.an) — required when the service generates the .eml
Attach All Input Binary Fields	No	Attach every binary property on the input item automatically (variable number of files, e.g. all attachments from a Gmail/IMAP trigger). When on, the manual Attachments list is hidden and ignored.
Allow Duplicates	No	Skip deduplication. Off by default.
Also Export to Storage (Disable Loop Guard)	No	Off by default — the imported document is not re-exported. Enable to additionally queue the created document for export (WF1), e.g. to mirror it to SharePoint.

Area (Bereich) mapping — the dropdown sends these table names. Documents attached from positions use Artikel_s with BelegNr = ArtikelNr.

Dropdown	API value	Dropdown	API value
Order (Auftrag)	Auftrag_s	Offer (Angebot)	Angebot_s
Invoice (Rechnung)	Rechnung_s	Delivery Note (Lieferschein)	Lieferschein_s
Purchase Order (Bestellung)	Bestellung_s	Article (Artikel)	Artikel_s
Inquiry (Anfrage)	Anfrage_s	Project (Projekt)	Projekt
Customer (Kunde)	Kunden_s	Supplier (Lieferant)	Liefer_s
Purchase Invoice (ER)	ER	Customer Inquiry (Kundenanfrage)	Kundenanfrage

Email Fields (collection — used to build the .eml):

Field	API field	Description
Date	email.datum	Date the mail was received (ISO 8601)
From	email.von	Sender address
HTML	email.html	HTML body — provide Text or HTML
Message ID	email.messageId	Unique mail ID — drives deduplication
Subject	email.betreff	Email subject
Text	email.text	Plain text body — provide Text or HTML

*When the service builds the .eml, email.an and at least one of email.text / email.html are required; otherwise the API returns 400.

Attachments (add one row per file):

Field	Description
Input Binary Field	Name of the n8n binary property to attach. If set, its content is Base64-encoded automatically and the file name / MIME type are taken from the binary metadata (unless overridden below).
File Name	Attachment file name (dateiname) — overrides the binary file name
MIME Type	Attachment MIME type — overrides the binary MIME type
Content (Base64)	Base64 content (inhaltBase64) — used when Input Binary Field is empty

Binary handling: the most convenient way to add attachments is to wire a node that outputs binary data (e.g. HTTP Request, Read Binary File, a SharePoint download) and reference its binary property under Input Binary Field — the node performs the Base64 conversion for you. The combined upload is bounded by the service limit (MAX_UPLOAD_SIZE, 60 MB request body ≈ 45 MiB of decoded attachments); a larger request is rejected with 403 Forbidden.

Deduplication & allowDuplicates:

allowDuplicates	email.messageId	Behaviour
off (default)	present, already seen	No .eml, no document, no audit entry — returns duplicate: true
off (default)	present, new	Document is created normally
off (default)	absent	No dedup check — document is created normally
on	any	Dedup skipped — document is always created

The duplicate check matches on the previously stored JSON_VALUE(Payload, '$.email.messageId') of WF2 audit entries.

Example workflows

WF1 — Export to SharePoint (combined, recommended):

[Schedule/Trigger]
      ↓
[TaxMetall ERP · Document Sync · Check & Download New Documents] → one item per document, binary "data"
      ↓
[Upload to SharePoint]                                          → sharePointUrl
      ↓
[TaxMetall ERP · Document Sync · Report Transfer Status]        (success = true, Payload Field sharePointUrl)

WF1 — Export to SharePoint (manual claim/download split):

[Schedule/Trigger]
      ↓
[TaxMetall ERP · Document Sync · Check New Documents]   → documents[]
      ↓ (Split / loop over documents[])
[TaxMetall ERP · Document Sync · Download Document File] → binary "data"
      ↓
[Upload to SharePoint]                                  → sharePointUrl
      ↓
[TaxMetall ERP · Document Sync · Report Transfer Status] (success = true, Payload Field sharePointUrl)

On an upload failure, set Success = false and pass the error message — the entry stays in the queue and is retried on the next poll, unconditionally and without limit (no retry counter, no dead state).

WF2 — Import from SharePoint / mail:

[SharePoint / Mail source]
      ↓
[TaxMetall ERP · Document Sync · Create Document]  (bereich, belegnummer, sharePointUrl, email, attachments)

Example JSON for Create Document

The node assembles the request below from its fields. The same body can also be sent directly to POST /api/create-new-dokument:

{
  "bereich": "Auftrag_s",
  "belegnummer": "10523",
  "sharePointUrl": "https://contoso.sharepoint.com/sites/erp/Freigegebene%20Dokumente/10523.eml",
  "allowDuplicates": false,
  "email": {
    "messageId": "<a1b2c3@mail.example.com>",
    "von": "kunde@example.com",
    "an": "vertrieb@firma.de",
    "betreff": "Bestellung 10523",
    "datum": "2026-06-15T09:30:00",
    "text": "Anbei die Bestellung.",
    "html": "<p>Anbei die Bestellung.</p>"
  },
  "attachments": [
    {
      "dateiname": "bestellung.pdf",
      "mimeType": "application/pdf",
      "inhaltBase64": "JVBERi0xLjcZ…"
    }
  ]
}

Successful response (new document):

{ "success": true, "emlGenerated": true, "messageId": "<a1b2c3@mail.example.com>" }

Duplicate response (same messageId, allowDuplicates off):

{ "success": true, "duplicate": true, "message": "Mail bereits verarbeitet" }

Typical errors

Status	Meaning
400 Bad Request	Missing/invalid field — e.g. bereich/belegnummer missing, no sharePointUrl, email.an or body missing, invalid Base64, or allowDuplicates not boolean
401 Unauthorized	API key (tax-api-key header) missing or invalid
403 Forbidden	Request body exceeds MAX_UPLOAD_SIZE, or the source file is not readable
404 Not Found	Queue entry or source file not found; or an invalid target reference for WF2
409 Conflict	Wrong event type (e.g. a DELETE event has no file to download), or a DMS: reference that cannot be delivered as a local file
503 Service Unavailable	Document sync disabled in the service config, or the APIEvent tables (APIEventTrigger/APIEventDetail) not present for the tenant — run syncschema-init

---

Dunning

Reads open dunning items (Mahnungen). Dunning records are not independent documents in TaxMetall — they are a filtered view of the invoice table (open balance > 0, not a credit note, no dunning block active).

Search by Customer No.

Lists all open dunning items for a specific customer.

Field	Required	Description
Customer Number	Yes	Customer number (Kundennr)
Due Date From	No	Optional: filter by due date start (yyyy-mm-dd)
Due Date To	No	Optional: filter by due date end (yyyy-mm-dd)
Dunning Level	No	Show only items of this dunning level — 0 = all levels
Include Blocked	No	Include items with dunning block (Mahnsperre) — default: off
Include Paid	No	Include already paid items — default: off

Search by Due Date Range

Lists all open dunning items within a due date range.

Field	Required	Description
Due Date From	Yes	Start date in format yyyy-mm-dd
Due Date To	Yes	End date in format yyyy-mm-dd
Dunning Level	No	Show only items of this dunning level — 0 = all levels
Include Blocked	No	Include items with dunning block — default: off
Include Paid	No	Include already paid items — default: off

---

Invoice

Reads invoices (Rechnungen) including their line items.

Search by Invoice No.

Returns a single invoice with all its line items.

Field	Required	Description
Invoice Number	Yes	Invoice number (Rechnungnr)

Search by Customer No.

Lists all invoices for a given customer.

Field	Required	Description
Customer Number	Yes	Customer number (Kundennr)

Search by Date Range

Lists all invoices within a date range (by invoice date).

Field	Required	Description
Date From	Yes	Start date in format yyyy-mm-dd
Date To	Yes	End date in format yyyy-mm-dd

---

Newsletter

Syncs customer and acquisition contacts who opted in to the newsletter (the dedicated Newsletter checkbox on the contact) to an external tool such as CleverReach. TaxMetall tracks which contacts were already handed over in its own database, so Get Subscribers only ever returns contacts that have not been confirmed yet — poll it on a schedule, create the subscriber in your newsletter tool, then call Confirm Sync so the same contact is not returned again.

This resource is disabled by default on the service side ([Newsletter] Enabled=0 in the service's config.ini) — ask your administrator to enable it if Get Subscribers returns an error.

Get Subscribers

Returns customer or acquisition contacts with the newsletter opt-in set that have not yet been confirmed as synced.

Field	Required	Description
Source	Yes	Customer: contacts on customers (KundPa_s). Acquisition: contacts on acquisition/leads (NeuKundPa_s)

Confirm Sync

Marks a contact as synced so it is no longer returned by Get Subscribers. Safe to call more than once for the same contact — the response's alreadyConfirmed field tells you whether a new record was written.

Field	Required	Description
Source	Yes	Customer or Acquisition — must match the contact's source
Customer Number	Only if Source = Customer	Customer number (Kundennr) the contact belongs to
Contact Number	Only if Source = Acquisition	Acquisition/lead contact number (Kontaktnr)
Partner Number	Yes	Partner number (Partnernr) of the contact person, as returned by Get Subscribers

---

Offer

Manages offers (Angebote) in TaxMetall.

Create

Creates a new offer for a customer with one or more article positions. Prices, discounts, surcharges and the offer totals are determined and calculated like in TaxMetall. The whole offer is created in one transaction: if a position fails, no offer is created.

Multiple positions require TaxMetall API Service 1.27.0 or newer. Older services only accept Single Article. See Compatibility.

Field	Required	Description
Customer ID	Yes	Customer number (Kundennr)
Positions Input	No	Single Article (default, as in earlier versions), Multiple Positions (one row per article) or From JSON (a list from a previous node).
Article ID	No*	Single Article: numeric internal article ID
Article Number	No*	Single Article: article number as text, used when Article ID is 0
Quantity	No	Single Article: quantity, default 1
Positions	For Multiple Positions	One row per article with Article ID or Article Number, Quantity (default 1) and optionally Price and Discount % (0 = determined by TaxMetall)
Positions (JSON)	For From JSON	List of objects with articleid or artikelnr and optional menge, e.g. [{"artikelnr": "A-100045", "menge": 5}]. An object holding the list under positionen works too.
Rounding (additional field)	No	Commercial (Like TaxMetall) (default) or Mathematical (Half to Even)
Rounding Factor (additional field)	No	Like the TaxMetall workstation setting RF. 100 = two decimals (default)

*Per position either Article ID or Article Number. If both are set, Article ID takes precedence.

The response contains angebotNr, positionen (position number, article, quantity, prices) and the offer summen.

Search by Offer No.

Returns a single offer with all its line items.

Field	Required	Description
Offer Number	Yes	Offer number (Angebotsnr)

Search by Customer No.

Lists all offers for a given customer.

Field	Required	Description
Customer Number	Yes	Customer number (Kundennr)

Search by Date Range

Lists all offers within a date range (by offer date).

Field	Required	Description
Date From	Yes	Start date in format yyyy-mm-dd
Date To	Yes	End date in format yyyy-mm-dd

---

Order

Creates and reads orders (Aufträge) in TaxMetall.

Create

Creates a new order for a customer with one or more article positions. For each position, either Article ID or Article Number must be provided — if both are set, Article ID takes precedence. Header and position data (addresses, VAT, prices, discounts, open quantity) are derived automatically from the customer and article master data, and the order totals are calculated.

Field	Required	Description
Customer ID	Yes	Customer number (Kundennr) the order is created for
Positions	Yes	One or more positions. Add a row per article.
› Article ID	No*	Numeric internal article ID
› Article Number	No*	Article number as text — used when Article ID is 0
› Quantity	No	Quantity for the position — default: 1
› Price	No	Unit price that replaces the price determined by TaxMetall. 0 = determined by TaxMetall. Requires service 1.27.0.
› Discount %	No	Discount that replaces the discount determined by TaxMetall. 0 = determined by TaxMetall; send "rabatt": 0 via JSON input to force no discount. Requires service 1.27.0.
Create Calculation	No	Freeze the bill of materials and create the calculation (work plan / material) for each position. Off by default.
Rounding (additional field)	No	Commercial (Like TaxMetall) (default) or Mathematical (Half to Even)
Rounding Factor (additional field)	No	Like the TaxMetall workstation setting RF. 100 = two decimals (default)

From service version 1.27.0 on, position prices and order totals are calculated like in TaxMetall (commercial rounding, weight-based prices, surcharges, document surcharges, packaging and freight costs of the delivery terms). The response additionally contains the order summen.

*At least one of Article ID or Article Number must be provided per position.

Each created position is marked in the Text1 field with the note "Erstellt durch TaxMetall API Service".

Create From Offer

Transfers an existing offer (Angebot) into a new order, like the dialog "Uebergabe: Angebot in
Auftrag" in TaxMetall. Header data, positions with their quantities, prices, delivery dates and
texts, surcharges, payment terms, the approval chain and the back reference in the offer are
handled the same way TaxMetall does it, and the calculation matches TaxMetall to the cent. Price
tiers (Staffelpreise) of an offer position are copied to the order position as well.

Requires TaxMetall API Service 1.27.0 or newer. See Compatibility.

Field	Required	Description
Offer Number	Yes	Number of the offer (Angebotnr)
Position Selection	No	Manual List (default): enter positions below. Accepted in Offer: transfer the positions whose accept checkbox (Akzeptieren) is set in the offer, like TaxMetall. From JSON: take the positions from a JSON list, e.g. from a previous node.
Positions (JSON)	For From JSON	A list of position numbers ([1, 2, 3]) or objects with positionsnr (also position, pos), optional gruppennr (group) and optional menge (quantity, qty). An object holding the list under positionen, positions or items works too. Example: [{"positionsnr": 1}, {"positionsnr": 2, "menge": 10}]
Positions	For Manual List	One row per offer position.
› Position Number	Yes	Position number in the offer
› Group Number	No	Offer group, only needed if the position number exists in several groups. 0 = any group.
› Quantity	No	Quantity for the order position. 0 = quantity from the offer. A different quantity recalculates the position like a quantity change in the TaxMetall order.
Customer Order Number	No*	The customer's own purchase order number (Bestell-Nummer), e.g. PO-4711. It is stored in the order.
Customer Order Date	No	Order date of the customer, yyyy-mm-dd. Empty = today.
Transfer Intro Text	No	Copy the intro text of the offer. Off = default intro text for orders.
Transfer Closing Text	No	Copy the closing text of the offer. Off = default closing text for orders.
Transfer Personnel Number	No	Keep the employee of the offer (default on). Off = service employee from the service configuration.
Transfer Attention Of	No	Copy contact person, partner number and salutation (default on).
Transfer Shipping Costs	No	Copy shipping costs (packaging, transport, customs, insurance).
Keep Group Sorting	No	Order the positions by offer group first.
Allow Repeated Transfer	No	Allow transferring positions that are already part of an order. Off = HTTP 409 instead of a duplicate order.
Rounding	No	Commercial (Like TaxMetall) (default): half away from zero, identical to TaxMetall. Mathematical (Half to Even): banker's rounding, can differ from TaxMetall by one cent.
Order Number (additional field)	No	Explicit number for the new order. Default: next number from the TaxMetall number range.
Rounding Factor (additional field)	No	Rounding of position prices, like the TaxMetall workstation setting RF. 100 = two decimals (default).
Create Post-Calculation (additional field)	No	Create a post-calculation for every position, like the TaxMetall workstation setting AutoNachKalk. Off by default.

*Optional by default. If the TaxMetall system setting that enforces a customer order number (PruefextBestnr) is switched on, TaxMetall's own transfer dialog cannot be completed without it, and the node behaves the same way: the request is rejected with HTTP 400 and no order is created.

The response contains auftragNr, the transferred positionen (offer position → order position,
quantity, prices), the order summen and a list of warnings, for example when background
reservation is active in TaxMetall. Reservation is not performed by the service and has to be
checked in TaxMetall. The transfer runs in a single transaction: on any error nothing is written.

Get Order Status

Returns a single order including all its line items and current production status.

Field	Required	Description
Order Number	Yes	Internal order number (Auftragnr)

Search by Date Range

Lists all orders within a date range.

Field	Required	Description
Date From	Yes	Start date in format yyyy-mm-dd
Date To	Yes	End date in format yyyy-mm-dd

---

Purchase Inquiry

Creates and reads purchase inquiries (Anfragen) to suppliers in TaxMetall.

Requires TaxMetall API Service 1.24.0 or newer for all operations of this resource. See
Compatibility.

Create

Creates a new purchase inquiry for a supplier with one or more article positions. For each position, either Article ID or Article Number must be provided — if both are set, Article ID takes precedence.

Field	Required	Description
Supplier Number	Yes	Supplier number (Liefernr) the inquiry is created for
Positions	Yes	One or more positions. Add a row per article.
› Article ID	No*	Numeric internal article ID
› Article Number	No*	Article number as text — used when Article ID is 0
› Quantity	No	Quantity for the position — default: 1
› Price	No	Optional expected unit purchase price
Inquiry Date	No	Inquiry date in format yyyy-mm-dd. Defaults to today.

*At least one of Article ID or Article Number must be provided per position.

Search by Inquiry No.

Returns a single purchase inquiry including all its line items.

Field	Required	Description
Inquiry Number	Yes	Purchase inquiry number (AnfrageNr)

Search by Supplier

Lists all purchase inquiries for a given supplier.

Field	Required	Description
Supplier Number	Yes	Supplier number (Liefernr)

Search by Date Range

Lists all purchase inquiries within a date range (by inquiry date).

Field	Required	Description
Date From	Yes	Start date in format yyyy-mm-dd
Date To	Yes	End date in format yyyy-mm-dd

---

Purchase Invoice

Reads incoming purchase invoices (Eingangsrechnungen) including their line items, and creates them
either from individual fields or from an EN 16931 e-invoice file.

The Search operations work with TaxMetall API Service 1.10.0 or newer. The Create
operation requires 1.25.0 or newer. See Compatibility.

Search by Purchase Invoice No.

Returns a purchase invoice by its invoice number. If multiple entries share the same invoice number (from different suppliers), add the supplier number to narrow the result.

Field	Required	Description
Purchase Invoice Number	Yes	Purchase invoice number (ERNr)
Supplier Number	No	Supplier number to narrow results when the invoice number is not unique

Search by Supplier

Lists all purchase invoices for a given supplier.

Field	Required	Description
Supplier Number	Yes	Supplier number (Liefernr)

Search by Date Range

Lists all purchase invoices within a date range (by invoice date).

Field	Required	Description
Date From	Yes	Start date in format yyyy-mm-dd
Date To	Yes	End date in format yyyy-mm-dd

---

Purchase Order

Creates and reads purchase orders (Bestellungen) to suppliers in TaxMetall.

Requires TaxMetall API Service 1.24.0 or newer for all operations of this resource. See
Compatibility.

Create

Creates a new purchase order for a supplier with one or more article positions. For each position, either Article ID or Article Number must be provided — if both are set, Article ID takes precedence.

Field	Required	Description
Supplier Number	Yes	Supplier number (Liefernr) the order is created for
Positions	Yes	One or more positions. Add a row per article.
› Article ID	No*	Numeric internal article ID
› Article Number	No*	Article number as text — used when Article ID is 0
› Quantity	No	Quantity for the position — default: 1
› Price	No	Unit purchase price
› Discount %	No	Position discount in percent
› Price Per	No	Price base quantity, e.g. 100 for price per 100 units — default: 1
Book to Disposition	No	Book the order into disposition (writes ArtikelBestellt). Off by default.
Order Date	No	Order date in format yyyy-mm-dd. Defaults to today.

*At least one of Article ID or Article Number must be provided per position.

Search by Order No.

Returns a single purchase order including all its line items.

Field	Required	Description
Order Number	Yes	Purchase order number (BestellNr)

Search by Supplier

Lists all purchase orders for a given supplier.

Field	Required	Description
Supplier Number	Yes	Supplier number (Liefernr)

Search by Date Range

Lists all purchase orders within a date range (by order date).

Field	Required	Description
Date From	Yes	Start date in format yyyy-mm-dd
Date To	Yes	End date in format yyyy-mm-dd

---

Statistic

Executes pre-configured SQL reports stored in TaxMetall and returns the results as a JSON array. This covers both custom SQL reports and Business Cockpit reports defined in your TaxMetall installation.

The available reports are loaded dynamically from the API and presented in a dropdown — each option shows the report name and which parameters it requires.

Note: Reports of type Individual (Individuell) and Business Cockpit (BC) are supported, plus a small, fixed set of built-in reports the service exposes explicitly ("n.g. …" not-printed/not-emailed reports). Most other static system reports (Statisch) are not available because their SQL is not stored in the database and lives in the ERP client instead.

Execute

Field	Required	Description
Statistics / Report	Yes	Select the report from the dropdown — the description shows which parameters are needed
Date From	No	Start of the reporting period (SQL parameter: DatumVon)
Date To	No	End of the reporting period (SQL parameter: DatumBis)
Comparison From	No	Start of an optional comparison period (SQL parameter: VergleichVon)
Comparison To	No	End of an optional comparison period (SQL parameter: VergleichBis)
Only Open	No	Whether to only include open items, if supported by the selected report (SQL parameter: ChkNO)
Without Blanket Orders	No	Whether to exclude blanket orders (Rahmenauftraege), if supported by the selected report (SQL parameter: ChkOR)
Not Printed	No	Whether to only include documents not yet printed, if supported by the selected report (SQL parameter: ChkND)
Not Emailed	No	Whether to only include documents not yet emailed, if supported by the selected report (SQL parameter: ChkNM)

Additional Parameters (collection — add only what the report requires):

Field	SQL Parameter	Description
Article No.	Artikel	Filter by article number
Article Group	ArtikelGruppe	Filter by article group
Order No.	Auftrag	Filter by order number
Order Position	AuftragsPos	Filter by order position
Order Type	AuftragsArt	Filter by order type code
Business Area	GeschBereich	Filter by business area
Customer No.	Kunden	Filter by customer number
Warehouse	Lagerort	Filter by warehouse code
Supplier No.	Lieferanten	Filter by supplier number
Employee	Mitarbeiter	Filter by employee code
Offer No.	Angebot	Filter by offer number
Offer Position	AngebotsPos	Filter by offer position
Project No.	Projekt	Filter by project ID
Purchase Order No.	Bestellung	Filter by purchase order number
Purchase Order Position	BestellPos	Filter by purchase order position
Value Range From	WertebereichVon	Numeric start value for range filters
Value Range To	WertebereichBis	Numeric end value for range filters
Variable 1	Variable1	Free text parameter

---

Supplier

Manages suppliers (Lieferanten) in TaxMetall.

Create

Creates a new supplier.

Field	Required	Description
Company Name	Yes	Supplier company name
Name Addition	No	Additional name line (Namenzusatz)
Street	No	Street address
Postal Code	No	Postal code
City	No	City
Country	No	Country name
ISO Country Code	No	Two-letter ISO code, e.g. DE, AT, CH
Email	No	Email address
Phone	No	Phone number
Website	No	Website URL

Search by ID

Returns a supplier by their supplier number.

Field	Required	Description
Supplier Number	Yes	Supplier number (Liefernr)

Search by Name

Searches suppliers by partial match on their company name.

Field	Required	Description
Name	Yes	Partial name to search for

Search by Article

Returns all suppliers linked to a specific article via the supplier-article assignment table.

Field	Required	Description
Article Number	Yes	Article number from the supplier-article assignment

---

Compatibility

Requirement	Version
n8n	>= 1.0.0
Node.js	>= 18
n8n Nodes API	1

Required TaxMetall API Service version

Every operation of this node calls an endpoint of the TaxMetall API Service running on your
premises. Those endpoints were added over time, so an operation only works if the service on
the other end is new enough. The node does not check this for you: calling an operation
your service does not know yet returns HTTP 404 with Endpoint nicht gefunden.

Newer service versions never remove endpoints, so a service that is at or above the highest
version listed below covers everything in this package.

Resource / Operation	Endpoint	Requires service
Acquisition, Article, Customer, Delivery Note, Document Management, Dunning, Invoice, Offer, Order, Statistic, Supplier — all operations	(base set)	1.10.0
Purchase Invoice — Search operations	/api/get-purchase-invoices	1.10.0
Document Sync — Check New Documents, Download Document File, Check & Download New Documents, Report Transfer Status, Create Document	/api/check-new-documents, /api/document-file, /api/sharepoint-transfer-status, /api/create-new-dokument	1.20.3
Document Sync — Unpack MSG File	/api/unpack-msg	1.23.2
Purchase Inquiry — all operations	/api/get-purchase-inquiries, /api/create-purchase-inquiry	1.24.0
Purchase Order — all operations	/api/get-purchase-orders, /api/create-purchase-order	1.24.0
Purchase Invoice — Create	/api/create-purchase-invoice	1.25.0
Customer Inquiry — all operations	/api/get-customer-inquiries, /api/create-customer-inquiry	1.25.0
Workflow — all operations	/api/get-workflows, /api/execute-workflow	1.25.0
Newsletter — all operations	/api/get-newsletter-subscribers, /api/confirm-newsletter-sync	1.26.0
Order — Create From Offer	/api/create-order-from-offer	1.27.0
Offer — Create with Multiple Positions or From JSON	/api/create-offer (positionen[])	1.27.0
Positions Input From JSON with English or mixed-case keys (all create operations)	all create endpoints	1.27.0

Finding your service version

From service version 1.26.0 on, /api/validate reports the version it is running, so the
Test button on the TaxMetall API credential shows it directly. You can also read it with:

curl -H "tax-api-key: YOUR_KEY" https://your-host:8443/api/validate

{ "success": true, "message": "Connected", "version": "1.26.0", "mandant": 1, "mandant_name": "Example GmbH", "db_connected": true }

Older services answer the same call without a version field. In that case the version is in
the first lines of the service log file, and in Windows → Programs and Features next to
TaxMetall API Service.

---

Resources

• Vectotax Software GmbH
• n8n community nodes documentation
• npm package
• Report an issue

---

License

MIT