Glossary

Every command, option, response field, and domain term used by fit-connect. For recipes see Usage.md; for the library see DEVELOPING.md.

Commands

Command What it does
routes <leikaKey> Find the responsible authority(ies) (Zustellpunkte) for a public service in an area. Needs a leikaKey and exactly one area selector.
areas <query...> Search areas by name and/or postal code. Returns id + name + type.
info Show the semantic version of the deployed Routing API instance.

Domain terms

FIT-Connect. A platform operated by the FITKO for transmitting applications and reports between online application services (“sendende Systeme”) and the receiving systems at authorities. It exposes a Routing API (read-only, wrapped here), a Submission API and a Destination API (the write path, not wrapped here).

FITKO. Föderale IT-Kooperation — the body operating FIT-Connect on behalf of the federal and state IT cooperation.

Routing API / Routingdienst. The read-only FIT-Connect service that resolves which destination is responsible for a service in an area, drawing largely on PVOG / XZuFi catalogue data. This is the only API this CLI wraps.

Zustellpunkt (delivery point) / destination. A uniquely addressable endpoint for submitting applications to a specific authority for a specific service. A routing result is a Zustellpunkt: a destinationId plus human-readable info about the responsible authority. (Actually submitting to it is the Submission API’s job — out of scope here.)

Leistungsschlüssel (leikaKey). The FIM service-catalogue key (formerly LeiKa key) identifying a public administrative service, a 14-digit string matching ^99\d{12}$ (e.g. 99123456760610). Identifies what service you’re routing. Not discoverable through this CLI — bring it from the FIM-Portal / Leistungskatalog.

PVOG. Portalverbund-Online-Gateway — a federal index of administrative services and responsibilities that backs much of the routing data (origin: "PVOG").

XZuFi. The XÖV data standard for administrative-service catalogues; the source format behind the authority/service descriptions.

ags — Amtlicher Gemeindeschlüssel. Official municipality code, 8 digits. An area selector for routes (--ags).

ars — Amtlicher Regionalschlüssel. Official regional code (a superset of the ags with hierarchy), 12 digits. An area selector for routes (--ars).

area id. The id returned by fit-connect areas. The third area selector for routes (--area-id).

routes options

Option Meaning
--ags <ags> Amtlicher Gemeindeschlüssel, 8 digits — area selector (use exactly one)
--ars <ars> Amtlicher Regionalschlüssel, 12 digits — area selector (use exactly one)
--area-id <id> Area id from fit-connect areas — area selector (use exactly one)
--offset <n> Start offset into the result set (default 0)
--limit <n> Page size, 1..500 (default 100)

areas options

Option Meaning
<query...> One or more search terms (names / postal codes); * wildcard supported. Terms are split into words on spaces and punctuation, and every word must match the same area (AND)
--offset <n> Start offset into the result set (default 0)
--limit <n> Page size, 1..500 (default 100)

Global options

Option Meaning
-v, --version Print the CLI version
-h, --help Show help
--compact Single-line JSON instead of pretty-printed
--base-url <url> API base URL (default https://routing-api-prod.fit-connect.fitko.net)
--api-version <version> Routing API version, v1 or v2 (default v2; v1 is legacy)
--timeout <ms> Time limit per request, reading the whole response included (default 30000; 0 disables; at most 2147483647)
--user-agent <ua> User-Agent header (blank falls back to default; some values are blocked by the API’s bot detection)
--max-retries <n> Retries for transient 429/503 (default 2)
--max-response-bytes <n> Response body size cap in bytes (0 = unlimited; default 100 MiB)

Response fields — routes

Envelope: { count, offset, totalCount, routes: Route[] }.

Route field Meaning
destinationId UUID of the FIT-Connect delivery point (target for submitting an application)
destinationSignature JWS over the addressing information (RFC 7515)
destinationName Full name of the responsible authority, incl. hierarchy
destinationShortName Short name of the authority
destinationLogo URL of the authority’s logo
contactPersons[] name, tel, fax, email for the service
address Street address — street, houseNumber, additional, zip, city
postalAddress Postal address (same shape as address)
postOfficeBox Post-office-box address — postOfficeBox, zip, city
privacyPolicyUrl, imprintUrl, accessibilityUrl, contactFormUrl Region-specific links
furtherInformation, requiredDocuments, legalBasis, deadline Localized text blocks: { description: { de, en, … } }, may contain HTML
processingDuration { minDuration, maxDuration, unit } (unit: year/month/week/day/workday/hour/minute/second)
customParameters Open-ended, service-specific parameters (e.g. fees, variants)
origin Source system of the routing info (e.g. PVOG)

Only destinationId and destinationSignature are guaranteed present; everything else varies per service and region.

Signature verification is the consumer’s responsibility. This tool passes destinationSignature through as an opaque, unverified string — it does no JWS/JWK/crypto validation of any kind. Before trusting destinationId to submit an application, verify the JWS against FITKO’s published FIT-Connect keys per the FIT-Connect specification. A spoofed or MITM’d routing response could otherwise misdirect a submission to an attacker-controlled destination.

Response fields — areas

Envelope: { count, offset, totalCount, areas: Area[] }.

Area field Meaning
id Numeric area id — pass as --area-id to routes
name Area name, e.g. "Halle (Saale)"
type Area type; the values differ by Land, e.g. "Bundesland", "Landkreis", "kreisfreie Stadt", "Stadt", "Gemeinde", "Amt", "Gemeindeteil", "Ortsteil"

Response fields — info

{ version: { major, minor, patch } } — the deployed Routing API’s semantic version.

Exit codes

Code Meaning
0 Success (also --help / --version; includes an empty routes/areas list)
4 Not found (404)
1 Any other API, network, parse, validation, or usage error

View the source on GitHub →