Strainovic IT

Zefix API: Firmendaten aus dem Handelsregister abfragen

Zefix ist der zentrale Firmenindex der Schweiz, betrieben vom Eidgenössischen Amt für das Handelsregister (EHRA) im Bundesamt für Justiz. Neben der Suche im Browser gibt es Zefix als REST-Schnittstelle, die «Zefix PublicREST API». Damit holt eine Anwendung Firmenname, Sitz, Rechtsform, Status und Zweck direkt aus dem Handelsregister. Diese Anleitung zeigt Zugang, Abfragen und Antwort, und wann das UID-Register die einfachere Wahl ist.

Ablauf einer Zefix-Abfrage: Die eigene Anwendung fragt mit Benutzername und Passwort bei Zefix PublicREST nach einer UID oder einem Namen und erhält die Firmendaten aus dem HandelsregisterEigene AnwendungUID oderFirmennameZefix PublicRESTAnmeldung mitBenutzernameund PasswortHandelsregisterName, Sitz,Rechtsform,Status, ZweckEigene AnwendungFormular füllenoder KundenprüfenAblauf einer Zefix-Abfrage: Die eigene Anwendung fragt mit Benutzername und Passwort bei Zefix PublicREST nach einer UID oder einem Namen und erhält die Firmendaten aus dem HandelsregisterEigene AnwendungUID oder FirmennameZefix PublicRESTAnmeldung mit Benutzername und PasswortHandelsregisterName, Sitz, Rechtsform, Status, ZweckEigene AnwendungFormular füllen oder Kunden prüfen

Was die Zefix API liefert

Die Schnittstelle liegt unter https://www.zefix.admin.ch/ZefixPublicREST. Die Beschreibung der Endpunkte steht in der Swagger-Oberfläche, maschinenlesbar als OpenAPI unter /v3/api-docs. Die wichtigsten Endpunkte:

  • GET /api/v1/company/uid/{id}: Firma über die UID
  • POST /api/v1/company/search: Suche über Name, Rechtsform, Sitz oder Kanton
  • GET /api/v1/sogc/bydate/{date}: Publikationen im Schweizerischen Handelsamtsblatt (SHAB) eines Tages
  • GET /api/v1/legalForm und GET /api/v1/community: Listen der Rechtsformen und Gemeinden

Die Daten stehen unter der Bedingung «Open use», mit der Pflicht, die Quelle anzugeben.

Schritt 1: Zugang beantragen

Die Abfragen sind kostenlos, brauchen aber ein Konto. Den Zugang vergibt das EHRA auf eine E-Mail an zefix@bj.admin.ch; als Benutzername dient eine E-Mail-Adresse. Angemeldet wird per HTTP Basic Auth, also mit Benutzername und Passwort bei jeder Anfrage. Bis die Zugangsdaten da sind, kann es einige Tage dauern, darum früh beantragen.

Schritt 2: Firma per UID abfragen

Die UID steht im Pfad ohne Punkte und Bindestrich:

curl -u "benutzer@example.ch:passwort" \
  https://www.zefix.admin.ch/ZefixPublicREST/api/v1/company/uid/CHE107721785

Die Antwort ist eine Liste, nicht ein einzelnes Objekt. Ist die UID nicht im Handelsregister, antwortet Zefix mit 404.

Schritt 3: Firma per Name suchen

Die Suche erwartet den Anfang des Firmennamens, mindestens drei Zeichen, mit * als Platzhalter:

{
  "name": "Muster*",
  "canton": "SG",
  "activeOnly": true
}

Sie verhält sich wie die genaue Suche auf der Zefix-Website. activeOnly blendet gelöschte Firmen aus. Die Treffer kommen in Kurzform; die vollen Daten holt danach eine Abfrage per UID.

Was in der Antwort steht

  • name, uid, legalSeat (Sitzgemeinde) und canton
  • legalForm mit dem Code nach eCH-0097
  • status: ACTIVE aktiv, BEING_CANCELLED in Liquidation, CANCELLED gelöscht, dazu deletionDate
  • purpose, der Zweck aus dem Handelsregister
  • address mit Strasse, Hausnummer, Postleitzahl und Ort
  • capitalNominal und capitalCurrency bei Kapitalgesellschaften
  • sogcPub mit den SHAB-Publikationen und oldNames mit früheren Namen
  • cantonalExcerptWeb, der Link zum Auszug des kantonalen Handelsregisters

Zefix oder UID-Register?

Zefix kennt nur Firmen mit Handelsregistereintrag. Das UID-Register des Bundesamts für Statistik kennt jedes Unternehmen mit UID, auch Einzelunternehmen und Vereine ohne Eintrag, und zeigt den Eintrag im Mehrwertsteuerregister. Seine öffentliche Abfrage braucht kein Konto.

Für die Frage, ob eine UID im Checkout gültig und die Firma aktiv ist, reicht deshalb das UID-Register. Zefix lohnt sich, wenn Zweck, Kapital, frühere Namen oder Publikationen gebraucht werden. Wie die Prüfung über das UID-Register geht, steht im Ratgeber UID-Nummer prüfen.

Stolperfallen

  • Schreibweise der UID: Im Pfad ohne Trenner (CHE107721785), in der Anzeige mit (CHE-107.721.785). Vor der Abfrage normalisieren.
  • Liste statt Objekt: Auch die Abfrage per UID liefert eine Liste.
  • Liquidation: BEING_CANCELLED ist noch nicht gelöscht, aber auch kein normaler Geschäftspartner mehr. Die eigene Anwendung muss entscheiden, wie sie damit umgeht.
  • Zugangsdaten: Benutzername und Passwort gehören auf den Server. Ein Aufruf aus dem Browser würde sie jedem Besucher zeigen.
  • Zwischenspeichern: Firmendaten ändern sich selten. Antworten eine Weile speichern statt bei jedem Seitenaufruf neu zu fragen.

Fertig im Shop

Wer UIDs im WooCommerce-Checkout prüfen will, braucht dafür keinen eigenen Code: mein Plugin UID-Check prüft Format, Prüfziffer und Status im UID-Register, ohne Konto und ohne Schlüssel.

Alle Ratgeber