bzst

n8n node for the BZSt eVatR API (VAT ID validation)

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 1.0.0
Author: cotec it-systeme GmbH

Available Nodes

Documentation generating…

BZSt API icon
BZSt API
USt-IdNr. über die eVatR-Schnittstelle des BZSt bestätigen

Documentation

@cotec-it-systeme/n8n-nodes-bzst

An n8n community node for the eVatR API of the Bundeszentralamt für Steuern (BZSt) — confirm
EU VAT IDs (USt-IdNr.) directly from a workflow. The UI is in German, following BZSt terminology.

📖 Documentation: https://docs.cotec-it-systeme.de/n8n-nodes/bzst-node/

Installation

In n8n: Settings → Community Nodes → Install → @cotec-it-systeme/n8n-nodes-bzst.
See the n8n community node guide.

Requires n8n 2.0+ and Node.js >= 20.19.

Credentials

Field Description
Eigene USt-IdNr. Your own German VAT ID (DE123456789), sent as the requesting party.

The eVatR interface needs no API key. Your own VAT ID is required by the BZSt for every query.

Operations

Resource: USt-IdNr.

Validieren — confirm a VAT ID of an EU member state.

  • Simple query: only Zu überprüfende USt-IdNr. — returns validity (status), anfrageZeitpunkt
    and, where applicable, gueltigAb / gueltigBis.
  • Qualified query: additionally set Firmenname and Ort (and optionally Straße,
    PLZ) under Zusätzliche Felder — the response adds ergFirmenname, ergOrt, ergStrasse,
    ergPlz with the comparison result per field (A match, B no match, C not queried,
    D not provided by the member state).

VAT IDs are normalised (whitespace removed, upper-cased) before sending.

Resource: Info

  • Statusmeldungen — all evatr-* status codes with their message text (one item per code).
  • EU-Mitgliedstaaten — member states and the current availability of their VIES system.

Error handling

The BZSt reports business results such as "VAT ID not assigned" (evatr-2001, HTTP 404) or
"own VAT ID invalid" (evatr-2005) as HTTP 4xx. The node returns these as a normal output item
(status + httpCode) so a workflow can branch on them — use Info → Statusmeldungen to resolve
the code to a message. Temporary failures (HTTP 5xx, e.g. evatr-1001, or network errors) raise an
error and honour Continue On Fail.

Compatibility

Built against the eVatR API v1 (https://api.evatr.vies.bzst.de/app/v1).

CI/CD (GitLab)

Ref What happens
any branch / MR lint, npm audit, SAST, secret detection, build
development deploy-test — copies dist/ into the test n8n instance and restarts it
master deploy — same for the prod n8n instance
tag vX.Y.Z stage-release — stages the package on npmjs.org; approve with 2FA

Deploys run on the shell runner tagged n8n-prod on the n8n host (ci/deploy.sh). Targets default
to /opt/n8n/bzst-nodes (service n8n) and /opt/n8n/bzst-nodes-test (service n8n-test);
override via N8N_CUSTOM_DIR, N8N_COMPOSE_SERVICE, N8N_TEST_CUSTOM_DIR,
N8N_TEST_COMPOSE_SERVICE. stage-release needs the masked variable NPM_TOKEN (granular token,
Read and write (stage only)). The tag is the version — no bump in the repo required.

License

MIT

Discussion