n8n-nodes-handelsregister

An n8n community node for company searches in the shared German Handelsregister portal. It implements the current advanced-search wire contract and the useful legacy fields documented by bundesAPI/handelsregister.

Features

• Stateful JSF/PrimeFaces session handling with JSESSIONID and ViewState
• Origin-restricted redirect and scoped cookie handling; no user credentials or API key required
• All keyword, register, legal-form, location, address, status, and federal-state filters
• Current register types including GsR
• Current legal forms including GbR and partnership-company variants
• Validated pagination with Return All or a configurable result limit
• Structured register, court, document-category, history, and branch-count metadata
• Explicit timeout, CAPTCHA, expired-session, JSF, HTTP, and layout errors
• One n8n output item per company with item linking

Installation

Install n8n-nodes-handelsregister through Settings > Community Nodes in n8n, or from the n8n installation directory:

npm install n8n-nodes-handelsregister

Restart n8n after a manual installation.

Authentication

The Handelsregister search is public. There is no API key, username, or password in the upstream project or portal search. The apparent authentication is technical session state:

1. The node opens the portal and receives a short-lived JSESSIONID cookie.
2. It extracts the current JSF javax.faces.ViewState value.
3. It submits the navigation and search forms within the same session.
4. It carries that state through all AJAX pagination requests.

For this reason the node intentionally has no n8n credential type. Sessions are created per input item and are never persisted.

Search Parameters

At least one search criterion is required.

| Parameter | Description | | --- | --- | | Keywords | Company-name search; * and ? work in exact mode | | Keyword Mode | All terms, at least one term, or exact company name | | Registered Office / Seat | Location filter with wildcard support | | Federal States | Any combination of Germany's 16 federal states | | Register Type | HRA, HRB, GnR, GsR, PR, or VR | | Register Number | Main-office register number | | Register Court | Current portal list of 150 register courts and their codes | | Legal Form | Every legal-form code currently offered by the portal | | Address Filters | Current portal country list, postal code, city, and street | | Search Options | Phonetic matching, deleted records, and new-law branches | | Return All / Limit | Retrieve every page or stop at a maximum result count | | Timeout | Per-request timeout between 1 and 120 seconds |

The court, country, legal-form, and register-type lists reflect the live portal as checked on 2026-07-14. The node rejects register-type/legal-form combinations that the portal UI does not offer. Seat, postal-code, city, and street values support * and ?; the portal's current maximum lengths are validated before a session is opened.

Output

Each company is returned as a separate item:

{
  "court": "Berlin Amtsgericht Berlin (Charlottenburg) HRB 44343",
  "courtName": "Amtsgericht Berlin (Charlottenburg)",
  "courtCode": "F1103",
  "registerType": "HRB",
  "registerNumber": "HRB 44343 B",
  "registerNumberRaw": "HRB 44343",
  "register_num": "HRB 44343 B",
  "name": "GASAG AG",
  "registeredOffice": "Berlin",
  "federalState": "Berlin",
  "state": "Berlin",
  "status": "aktuell",
  "statusCurrent": "AKTUELL",
  "documents": "ADCDHDDKUTVÖSI",
  "documentTypes": [
    {
      "code": "AD",
      "id": "...",
      "title": null,
      "description": "Aktueller Abdruck"
    }
  ],
  "history": [
    { "name": "1.) Gasag Berliner Gaswerke Aktiengesellschaft", "location": "1.) Berlin" }
  ],
  "branchCount": 0
}

register_num and state preserve the field names of the BundesAPI CLI. Prefer the clearer registerNumber, registeredOffice, and federalState fields in new workflows. registerNumberRaw preserves the number exactly as displayed by the search result before Berlin or Bremen suffix completion.

Documents

The upstream BundesAPI repository does not implement document downloads; its source contains a TODO and only concatenates the available document-category labels. This node returns stable descriptions for AD, CD, HD, DK, UT, VÖ, and SI, but does not download documents. Collapsed branch sections expose branchCount; expanded branch-detail downloads are not attempted.

Troubleshooting

Transient GET failures and GET responses with status 429, 502, 503, or 504 are retried twice. Stateful JSF POST requests are not replayed with potentially consumed ViewState; instead, transient POST or response-body failures restart the complete operation up to twice with a fresh session. Errors report the affected request phase and safe Node/Undici causes. Matrix and query session values are redacted, and submitted search fields are never included in diagnostics.

Pagination fails instead of returning partial data if the portal repeats rows, changes offsets, omits ViewState, reports an inconsistent total, or returns fewer rows than expected. An explicit session-expiry response restarts the complete search once with a fresh session. Workflow cancellation aborts active requests and retry waits.

Development

npm install
npm run lint
npm test
npm run typecheck
npm run build

The package supports the Node.js range supported by n8n 2.x (>=20.19 <=24) and declares n8n-workflow >=2.8.0 <3. Development and tests are pinned to n8n-workflow 2.8.0, matching n8n 2.8.3. Tags such as 0.1.0 trigger linting, tests, a build, version validation, and npm publication with provenance.

License

MIT