Firmenwatch UID API

openapi: 3.2.0
info:
  title: Firmenwatch UID 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: UID
  description: Pruefung und Normalisierung von Unternehmens-Identifikationsnummern.
paths:
  /uid/validate:
    post:
      tags:
      - UID
      operationId: validateUid
      summary: UID pruefen und normalisieren
      description: Prueft die Pruefziffer nach der Spezifikation des Bundesamts fuer Statistik (Modulo 11 mit den Gewichten 5, 4, 3, 2, 7, 6, 5, 4) und schlaegt die UID anschliessend im Bestand nach. Eine formal gueltige UID muss nicht eingetragen sein.
      x-max-body-bytes: 4096
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - uid
              additionalProperties: false
              properties:
                uid:
                  type: string
                  maxLength: 40
                  description: UID in beliebiger Schreibweise.
            example:
              uid: CHE-000.000.000
      responses:
        '200':
          description: Pruefergebnis.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/UidValidation'
              example:
                data:
                  valid: true
                  normalized: CHE-000.000.000
                  found: false
                  company: null
          headers:
            X-Firmenwatch-Monthly-Included:
              $ref: '#/components/headers/MonthlyIncluded'
            X-Firmenwatch-Monthly-Used:
              $ref: '#/components/headers/MonthlyUsed'
            X-Firmenwatch-Monthly-Reset:
              $ref: '#/components/headers/MonthlyReset'
            X-Firmenwatch-Monthly-Overage:
              $ref: '#/components/headers/MonthlyOverage'
        '400':
          description: Ungueltige Anfrage (invalid_request).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Firmenwatch-Monthly-Included:
              $ref: '#/components/headers/MonthlyIncluded'
            X-Firmenwatch-Monthly-Used:
              $ref: '#/components/headers/MonthlyUsed'
            X-Firmenwatch-Monthly-Reset:
              $ref: '#/components/headers/MonthlyReset'
            X-Firmenwatch-Monthly-Overage:
              $ref: '#/components/headers/MonthlyOverage'
        '401':
          description: Kein oder ungueltiger Schluessel (unauthorized).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            WWW-Authenticate:
              $ref: '#/components/headers/BearerChallenge'
        '402':
          description: Monatskontingent erschoepft (quota_exceeded).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Firmenwatch-Monthly-Included:
              $ref: '#/components/headers/MonthlyIncluded'
            X-Firmenwatch-Monthly-Used:
              $ref: '#/components/headers/MonthlyUsed'
            X-Firmenwatch-Monthly-Reset:
              $ref: '#/components/headers/MonthlyReset'
            X-Firmenwatch-Monthly-Overage:
              $ref: '#/components/headers/MonthlyOverage'
        '403':
          description: Abonnement nicht aktiv oder benoetigtes Schluesselrecht fehlt (forbidden).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Anfrage-Rumpf zu gross (payload_too_large).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Firmenwatch-Monthly-Included:
              $ref: '#/components/headers/MonthlyIncluded'
            X-Firmenwatch-Monthly-Used:
              $ref: '#/components/headers/MonthlyUsed'
            X-Firmenwatch-Monthly-Reset:
              $ref: '#/components/headers/MonthlyReset'
            X-Firmenwatch-Monthly-Overage:
              $ref: '#/components/headers/MonthlyOverage'
        '415':
          description: JSON-Medientyp erforderlich (unsupported_media_type).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Firmenwatch-Monthly-Included:
              $ref: '#/components/headers/MonthlyIncluded'
            X-Firmenwatch-Monthly-Used:
              $ref: '#/components/headers/MonthlyUsed'
            X-Firmenwatch-Monthly-Reset:
              $ref: '#/components/headers/MonthlyReset'
            X-Firmenwatch-Monthly-Overage:
              $ref: '#/components/headers/MonthlyOverage'
        '429':
          description: Ratenbegrenzung erreicht (rate_limited).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Unerwarteter Fehler (internal).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Firmenwatch-Monthly-Included:
              $ref: '#/components/headers/MonthlyIncluded'
            X-Firmenwatch-Monthly-Used:
              $ref: '#/components/headers/MonthlyUsed'
            X-Firmenwatch-Monthly-Reset:
              $ref: '#/components/headers/MonthlyReset'
            X-Firmenwatch-Monthly-Overage:
              $ref: '#/components/headers/MonthlyOverage'
        '503':
          description: Der Registerbestand wird gerade vollständig verifiziert (temporarily_unavailable). Dieselbe Abfrage später erneut senden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              description: Empfohlene Wartezeit vor demselben Abruf in Sekunden.
              schema:
                type: integer
                minimum: 1
            X-Firmenwatch-Monthly-Included:
              $ref: '#/components/headers/MonthlyIncluded'
            X-Firmenwatch-Monthly-Used:
              $ref: '#/components/headers/MonthlyUsed'
            X-Firmenwatch-Monthly-Reset:
              $ref: '#/components/headers/MonthlyReset'
            X-Firmenwatch-Monthly-Overage:
              $ref: '#/components/headers/MonthlyOverage'
components:
  schemas:
    Address:
      type: object
      required:
      - care_of
      - street
      - house_number
      - po_box
      - zip
      - town
      properties:
        masked:
          type: boolean
          description: 'true: genaue Adresse aus Datenschutzgründen nicht öffentlich; Ort bleibt verfügbar.'
        care_of:
          type:
          - string
          - 'null'
          description: Zustellvermerk, z. B. c/o Muster Treuhand AG.
        street:
          type:
          - string
          - 'null'
        house_number:
          type:
          - string
          - 'null'
        po_box:
          type:
          - string
          - 'null'
          description: Postfachnummer ohne das Wort Postfach.
        zip:
          type:
          - string
          - 'null'
        town:
          type:
          - string
          - 'null'
    UidValidation:
      type: object
      required:
      - valid
      - normalized
      - found
      properties:
        valid:
          type: boolean
          description: Format und Pruefziffer sind korrekt.
        normalized:
          type:
          - string
          - 'null'
          description: Kanonische Schreibweise CHE-000.000.000; null bei ungueltigem Format.
        found:
          type: boolean
          description: Die UID ist im Firmenwatch-Bestand vorhanden.
        reason:
          type: string
          enum:
          - format
          - checksum
          description: Grund bei ungueltiger UID.
        company:
          oneOf:
          - $ref: '#/components/schemas/Company'
          - type: 'null'
    Capital:
      type: object
      required:
      - nominal
      - paid
      - currency
      - verification
      - evidence_basis
      - publication
      properties:
        nominal:
          type: number
          description: Nominalkapital mit belegtem ISO-Waehrungscode.
        paid:
          type:
          - number
          - 'null'
          description: Belegtes liberiertes Kapital, soweit erfasst.
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          description: In einer erfassten Registerpublikation belegter ISO-Waehrungscode.
        verification:
          type: string
          const: currency_evidenced
        evidence_basis:
          type: string
          const: structured_shab_company_capital
        publication:
          type: object
          required:
          - id
          - date
          - number
          - sub_rubric
          - state
          - url
          properties:
            id:
              type: string
            date:
              type: string
              format: date
            number:
              type:
              - string
              - 'null'
            sub_rubric:
              type: string
            state:
              type: string
              enum:
              - commonsActual
              - commonsNew
            url:
              type: string
              format: uri
    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
    Company:
      type: object
      required:
      - uid
      - name
      - slug
      - legal_form_code
      - legal_form
      - status
      - seat
      - canton
      - address
      - purpose
      - capital
      - industry
      - first_registered_at
      - deleted_at
      - last_event_at
      - url
      properties:
        uid:
          type: string
          example: CHE-000.000.000
        name:
          type: string
          example: Muster Handels AG
        slug:
          type: string
          example: muster-handels-ag-zuerich
        legal_form_code:
          type:
          - string
          - 'null'
          example: '0106'
        legal_form:
          type:
          - string
          - 'null'
          example: Aktiengesellschaft
        status:
          type: string
          enum:
          - active
          - in_liquidation
          - bankrupt
          - deleted
        seat:
          type:
          - string
          - 'null'
          description: Politische Gemeinde des Sitzes.
        canton:
          type:
          - string
          - 'null'
          example: ZH
        address:
          $ref: '#/components/schemas/Address'
        purpose:
          type:
          - string
          - 'null'
          description: Zweckumschreibung gemaess Handelsregister.
        capital:
          description: Nur vorhanden, wenn Betrag und Waehrung gemeinsam belegt sind; sonst null.
          oneOf:
          - $ref: '#/components/schemas/Capital'
          - type: 'null'
        industry:
          oneOf:
          - $ref: '#/components/schemas/Industry'
          - type: 'null'
        first_registered_at:
          type:
          - string
          - 'null'
          format: date
          description: SHAB publication date of the earliest evidenced new registration; not the cantonal journal date.
        deleted_at:
          type:
          - string
          - 'null'
          format: date
        last_event_at:
          type:
          - string
          - 'null'
          format: date
        url:
          type: string
          format: uri
          description: Oeffentliches Firmenprofil auf firmenwatch.ch.
    Industry:
      type: object
      description: Aus dem eingetragenen Zweck abgeleitete Firmenwatch-Klassifikation; keine amtliche NOGA-Zuordnung.
      required:
      - code
      - label
      - confidence
      - qualification
      - basis
      properties:
        code:
          type:
          - string
          - 'null'
          description: Interner, NOGA-naher Klassifikationscode.
        label:
          type: string
          description: Deutsche Bezeichnung der abgeleiteten Branche.
        confidence:
          type: number
          minimum: 0.45
          maximum: 1
        qualification:
          type: string
          enum:
          - derived
          - probable
        basis:
          type: string
          const: registered_purpose_text
  headers:
    MonthlyOverage:
      description: 'Optional: true erlaubt Abfragen oberhalb des eingeschlossenen Volumens. Bei false fuehrt ein ausgeschoepftes Monatskontingent zu HTTP 402. Der Verbrauch darf bei true groesser als Included sein.'
      required: false
      schema:
        type: boolean
    MonthlyIncluded:
      description: 'Optional: eingeschlossene Abfragen im wirksamen Kontotarif fuer den gebuchten UTC-Kalendermonat.'
      required: false
      schema:
        type: integer
        minimum: 0
    BearerChallenge:
      description: HTTP-Bearer-Herausforderung fuer einen fehlenden oder ungueltigen API-Schluessel.
      schema:
        type: string
        const: Bearer realm="firmenwatch"
    MonthlyUsed:
      description: 'Optional: kontoweit verbuchte Abfragen einschliesslich dieses zugelassenen Aufrufs. Alle Schluessel und geschuetzten MCP-Aufrufe teilen den Stand. Bestaetigte Rueckbuchungen koennen ihn senken; keine Reservierung fuer den naechsten Aufruf.'
      required: false
      schema:
        type: integer
        minimum: 0
    MonthlyReset:
      description: 'Optional: Unix-Zeit in Sekunden fuer den naechsten Monatsanfang um 00:00 UTC, bezogen auf den urspruenglich gebuchten Monat, auch nach einer Rueckbuchung.'
      required: false
      schema:
        type: integer
        format: int64
        minimum: 0
  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