Firmenwatch Identitaet API

openapi: 3.2.0
info:
  title: Firmenwatch Identitaet API
  version: 1.11.0
  summary: Schweizer Firmenidentitaeten, atomarer Portfolio-Abgleich, amtliche SHAB-Publikationen und ein geschlossener Arbeitskreislauf.
  description: 'REST-Schnittstelle auf den uebernommenen Zefix/LINDAS-Stammbestand und erfasste Publikationen des Schweizerischen Handelsamtsblatts: Firmensuche, sicherer Namensabgleich ohne bekannte UID, Einzelabfrage per UID, Organe, Historie, Ereignisstrom, resumierbarer und atomarer Portfolio-Abgleich, priorisierte Prueffaelle, konkurrenzsichere Rueckmeldung von Bearbeitungsstand und Entscheidung sowie UID-Pruefung. Der separate Root-Resolver /uid/{uid}.json liefert ohne API-Schluessel einen minimalen, versionierten Identitaetskern. Alle Zeitangaben sind UTC, alle Datumsangaben ISO 8601 (YYYY-MM-DD). Die erfasste Publikationshistorie beginnt am 2025-01-03; fruehere Zeitstaende werden nicht aus dem heutigen Bestand zurueckgerechnet und eine vollstaendige amtliche Gesamthistorie wird nicht zugesichert. Betraege in Franken ohne Rappen, sofern nicht anders vermerkt.


    Ereignisse des Stroms /events folgen dem Ereignisvertrag (Schema FeedEvent): stabile Kennung id, schema_version, sequence als Lesezeiger, status, revised_at, content_hash und source. Die menschenlesbare Begruendung steht unter https://firmenwatch.ch/api-docs#ereignisvertrag.


    Optionale X-Firmenwatch-Monthly-*-Kopfzeilen melden nach der Kontingentpruefung den kontoweiten Buchungsstand aller Schluessel und geschuetzten MCP-Aufrufe. Zugelassene Aufrufe zaehlen einschliesslich leerer Antworten, weiterer Seiten und nachgelagerter Eingabe- oder Fachfehler. Eine 402-Abweisung wegen ausgeschoepftem Monatskontingent zaehlt nicht; fruehe 401/403/429-Antworten und oeffentliche Endpunkte enthalten keine Monatswerte. Bestaetigte technische Rueckbuchungen koennen in derselben Antwort fuer den urspruenglich gebuchten UTC-Kalendermonat beruecksichtigt sein. Der Stand ist eine Momentaufnahme und reserviert kein Budget fuer parallele oder folgende Aufrufe. Eingeschlossenes Restvolumen = max(0, Included - Used); bei Overage=true bedeutet 0 keine Sperre. X-RateLimit-* beschreibt getrennt die kurzfristige Ratenbegrenzung.'
  termsOfService: https://firmenwatch.ch/agb
  contact:
    name: Firmenwatch Support
    url: https://firmenwatch.ch/kontakt
  license:
    name: 'Firmenevent-CH- und Firmenidentitaet-CH-Schema samt Testvektoren: CC0-1.0'
    url: https://creativecommons.org/publicdomain/zero/1.0/
servers:
- url: https://firmenwatch.ch/api/v1
  description: Produktion
security:
- bearerAuth: []
tags:
- name: Identitaet
  description: Schluesselfreie, dauerhaft per UID adressierbare Identitaetskerne.
paths:
  /uid/{uid}.json:
    get:
      tags:
      - Identitaet
      operationId: resolveCompanyIdentity
      summary: Minimalen Identitaetskern per UID aufloesen
      description: Schluesselfreier Root-Resolver ausserhalb von /api/v1. Liefert UID, aktuellen Namen, Registerstatus, Rechtsform, registrierten Sitz und Zeitstaende. Strassenadresse, Zweck, Kapital, Branche, Organe und Ereignisse sind bewusst nicht enthalten. Die Fassung folgt dem dauerhaft versionierten JSON Schema Firmenidentitaet CH 1.0.
      servers:
      - url: https://firmenwatch.ch
        description: Dauerhafter Identitaetsresolver
      security: []
      parameters:
      - name: uid
        in: path
        required: true
        description: Kanonisch formatierte UID; andere Schreibweisen werden bewusst nicht aufgeloest.
        schema:
          type: string
          pattern: ^CHE-[0-9]{3}\.[0-9]{3}\.[0-9]{3}$
        example: CHE-116.281.710
      responses:
        '200':
          description: Aktueller minimaler Identitaetskern der Rechtseinheit. Die Antwort ist no-store; auch bedingte Abrufe erhalten deshalb den vollständigen 200-Vertrag statt einer 304-Antwort.
          headers:
            Cache-Control:
              description: Unterdrueckungen muessen sofort wirken; der Identitaetskern darf nicht gespeichert werden.
              schema:
                type: string
                const: no-store
            Link:
              description: Kanonische Identitaet, versioniertes JSON Schema und alternatives HTML-Profil.
              schema:
                type: string
            X-Firmenwatch-Schema-Version:
              description: Version des Identitaetsvertrags.
              schema:
                type: string
                const: '1.0'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyIdentity'
        '404':
          description: Keine sichtbare Rechtseinheit unter dieser exakt kanonischen UID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Unerwarteter Fehler beim Aufloesen der UID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Die vollstaendig gepruefte Firmenidentitaet wird gerade aktualisiert.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              description: Empfohlene Wartezeit bis zum erneuten Abruf in Sekunden.
              schema:
                type: integer
                minimum: 1
components:
  schemas:
    CompanyIdentity:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: https://firmenwatch.ch/schemas/firmenidentitaet-ch/1.0.json
      title: Firmenidentitaet CH 1.0
      description: Minimaler, von Firmenwatch gepflegter Identitaetsvertrag fuer Schweizer Rechtseinheiten. Kein amtlicher Registerauszug.
      type: object
      required:
      - schema_version
      - id
      - uid
      - name
      - register_status
      - legal_form
      - registered_seat
      - first_registered_at
      - last_event_at
      - record_updated_at
      - profile_url
      - resolver_url
      - source
      properties:
        schema_version:
          const: '1.0'
          description: Formatversion. Additive Felder sind kompatibel; Entfernen, Umbenennen oder Umdeuten verlangt eine neue Hauptversion.
        id:
          type: string
          format: uri
          pattern: ^https://firmenwatch\.ch/uid/CHE-[0-9]{3}\.[0-9]{3}\.[0-9]{3}$
          description: Namensunabhaengige, dauerhafte URI der Rechtseinheit.
        uid:
          type: string
          pattern: ^CHE-[0-9]{3}\.[0-9]{3}\.[0-9]{3}$
          description: Kanonisch formatierte Schweizer Unternehmens-Identifikationsnummer.
        name:
          type: string
          minLength: 1
          description: Aktuell uebernommener Firmenname.
        register_status:
          type: string
          enum:
          - active
          - in_liquidation
          - bankrupt
          - deleted
          description: Aktuell uebernommener Registerstatus.
        legal_form:
          type: object
          required:
          - code
          - label
          properties:
            code:
              type:
              - string
              - 'null'
              description: Rechtsformcode nach eCH-0097, sofern vorhanden.
            label:
              type:
              - string
              - 'null'
              description: Bezeichnung der Rechtsform, sofern vorhanden.
          additionalProperties: true
        registered_seat:
          type: object
          description: Registrierter Sitz ohne Strassen- oder Zustelladresse.
          required:
          - municipality
          - canton
          properties:
            municipality:
              type:
              - string
              - 'null'
            canton:
              type:
              - string
              - 'null'
              pattern: ^[A-Z]{2}$
          additionalProperties: true
        location_review:
          type: object
          required:
          - seat
          - address
          description: Aktuelle Ortsangaben werden wegen einer noch geprüften Quellenmeldung zurückgehalten.
          properties:
            seat:
              type: boolean
            address:
              type: boolean
          additionalProperties: false
        first_registered_at:
          type:
          - string
          - 'null'
          format: date
          description: Datum der ersten bekannten Eintragung, sofern vorhanden.
        last_event_at:
          type:
          - string
          - 'null'
          format: date
          description: Datum der juengsten bei Firmenwatch bekannten amtlichen Aktualisierung.
        record_updated_at:
          type: string
          format: date-time
          description: Technischer Verarbeitungszeitpunkt dieses Datensatzes bei Firmenwatch; kein amtlicher Eintragungs- oder Publikationszeitpunkt.
        profile_url:
          type: string
          format: uri
          description: Aktuelles menschenlesbares Firmenprofil.
        resolver_url:
          type: string
          format: uri
          pattern: ^https://firmenwatch\.ch/uid/CHE-[0-9]{3}\.[0-9]{3}\.[0-9]{3}\.json$
          description: Diese maschinenlesbare Darstellung.
        data_status:
          type: object
          required:
          - latest_available_publication
          - verified_through
          - quality
          - incomplete_from
          - health_url
          description: Kanonischer Firmenwatch-Datenqualitaetsstatus. Fuer lueckenlose Aussagen gilt verified_through; aktuelle Details stehen unter health_url.
          properties:
            latest_available_publication:
              type:
              - string
              - 'null'
              format: date
            verified_through:
              type:
              - string
              - 'null'
              format: date
            quality:
              type: string
              enum:
              - current
              - processing
              - degraded
              - unavailable
            incomplete_from:
              type:
              - string
              - 'null'
              format: date
            health_url:
              type: string
              format: uri
          additionalProperties: true
        source:
          type: object
          required:
          - master_data
          - updates
          - methodology_url
          properties:
            master_data:
              type: object
              required:
              - name
              - delivery
              - url
              properties:
                name:
                  const: Zefix
                delivery:
                  const: LINDAS
                url:
                  type: string
                  format: uri
              additionalProperties: true
            updates:
              type: object
              required:
              - name
              - role
              - url
              properties:
                name:
                  const: Schweizerisches Handelsamtsblatt (SHAB)
                role:
                  const: Aktualisierungsbasis
                url:
                  type: string
                  format: uri
              additionalProperties: true
            methodology_url:
              type: string
              format: uri
          additionalProperties: true
      additionalProperties: true
      examples:
      - schema_version: '1.0'
        id: https://firmenwatch.ch/uid/CHE-116.281.710
        uid: CHE-116.281.710
        name: Muster Handels AG
        register_status: active
        legal_form:
          code: '0106'
          label: Aktiengesellschaft
        registered_seat:
          municipality: Zuerich
          canton: ZH
        first_registered_at: '2019-03-14'
        last_event_at: '2026-08-25'
        record_updated_at: '2026-08-25T08:30:00.000Z'
        profile_url: https://firmenwatch.ch/firma/muster-handels-ag-che-116281710
        resolver_url: https://firmenwatch.ch/uid/CHE-116.281.710.json
        data_status:
          latest_available_publication: '2026-08-25'
          verified_through: '2026-08-25'
          quality: current
          incomplete_from: null
          health_url: https://firmenwatch.ch/api/v1/health
        source:
          master_data:
            name: Zefix
            delivery: LINDAS
            url: https://lindas.admin.ch/foj/zefix
          updates:
            name: Schweizerisches Handelsamtsblatt (SHAB)
            role: Aktualisierungsbasis
            url: https://www.shab.ch
          methodology_url: https://firmenwatch.ch/datenquellen
      x-maintainer: Firmenwatch / Vodinali Ventures
      x-resolver-template: https://firmenwatch.ch/uid/{uid}.json
      x-license:
        name: CC0-1.0
        url: https://creativecommons.org/publicdomain/zero/1.0/
        scope: Schema und Beispiel; nicht die bezogenen Registerdaten.
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              enum:
              - unauthorized
              - forbidden
              - not_found
              - invalid_request
              - payload_too_large
              - unsupported_media_type
              - conflict
              - precondition_required
              - rate_limited
              - quota_exceeded
              - stream_reset
              - temporarily_unavailable
              - internal
            message:
              type: string
            details:
              type: object
              additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: fw_live_…
      description: 'API-Schluessel als Bearer-Token im Authorization-Kopf. Produktivschluessel beginnen mit fw_live_. Das ist bewusst kein OAuth-Flow: Die unveraenderlichen Rechte werden beim Erstellen des Schluessels vergeben.'
      x-firmenwatch-scopes:
        api:read: Registerdaten, Ereignisstrom und eigene Prueffaelle lesen.
        actions:write: Status, Wiedervorlage und finale Entscheidung eigener Prueffaelle schreiben.
        portfolio:write: Eigene Portfolios aus einem angebundenen System synchronisieren.
externalDocs:
  description: Firmenevent CH 1.0 — offener Ereignisvertrag und Integrationsablauf
  url: https://firmenwatch.ch/standard
x-history-coverage:
  available_from: '2025-01-03'
  complete_history_guaranteed: false
  before_start: not_available