Firmenwatch Betrieb API

openapi: 3.2.0
info:
  title: Firmenwatch Betrieb 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: Betrieb
  description: Verfuegbarkeit und Datenstand.
paths:
  /health:
    get:
      tags:
      - Betrieb
      operationId: getHealth
      summary: Verfuegbarkeit und Datenstand
      description: Trennt die juengste bereits verfuegbare SHAB-Publikation von der lueckenlos verifizierten Freigabegrenze und dem daraus abgeleiteten Datenqualitaetsstatus. identity_quarantined_publications zaehlt exakt aktive, gespeicherte Quellen mit ungeklärter UID-Zuordnung. Ein positiver Wert bedeutet ok=false, data_quality_status=degraded und HTTP 503; auch ein aktueller oder unveraenderter erfolgreicher Ingest loest die Quarantaene nicht. problems erlaeutert diesen Befund. compliance_screening meldet Frische und Abdeckung der MWST-, FINMA- und SECO-Quellen unabhaengig. Ein dortiges Problem erzeugt allein keinen HTTP 503 und darf nie als negativer Firmenbefund gelten.
      security: []
      responses:
        '200':
          description: SHAB-Kernbestand betriebsbereit und aktuell, ohne aktive Identitaetsquarantaene; Compliance kann im getrennten Feld eingeschraenkt sein.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
        '503':
          description: Datenbestand veraltet, eine aufmerksamkeitspflichtige Ingest-Scheibe ist unvollstaendig oder fehlgeschlagen, eine aktive Identitaetsquarantaene bleibt offen (ok=false, data_quality_status=degraded), oder die Datenbank ist nicht erreichbar.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/Health'
                - type: object
                  required:
                  - ok
                  - error
                  properties:
                    ok:
                      const: false
                    error:
                      const: database_unavailable
components:
  schemas:
    ComplianceHealth:
      type: object
      required:
      - status
      - healthy
      - checked_at
      - checked_sources
      - problem_codes
      - warning_codes
      - sources
      properties:
        status:
          type: string
          enum:
          - checked
          - unavailable
        healthy:
          type: boolean
        checked_at:
          type: string
          format: date-time
        checked_sources:
          type: integer
          minimum: 0
          maximum: 4
        problem_codes:
          type: array
          items:
            type: string
        warning_codes:
          type: array
          items:
            type: string
        sources:
          type: array
          items:
            type: object
            required:
            - key
            - sync_status
            - coverage_status
            - last_success_at
            - last_complete_at
            - freshness
            - freshness_warning_after_hours
            - freshness_problem_after_hours
            - problem_codes
            - warning_codes
            properties:
              key:
                type: string
                enum:
                - uid_vat
                - finma_authorisations
                - finma_warnings
                - seco_sanctions
              sync_status:
                type: string
                enum:
                - idle
                - fetching
                - healthy
                - error
                - missing
              coverage_status:
                type: string
                enum:
                - not_applicable
                - delta_only
                - building
                - complete
                - unknown
              last_success_at:
                type:
                - string
                - 'null'
                format: date-time
              last_complete_at:
                type:
                - string
                - 'null'
                format: date-time
              freshness:
                type: string
                enum:
                - fresh
                - stale_warning
                - stale_problem
                - unknown
              freshness_warning_after_hours:
                type: integer
                minimum: 1
              freshness_problem_after_hours:
                type: integer
                minimum: 1
              problem_codes:
                type: array
                items:
                  type: string
              warning_codes:
                type: array
                items:
                  type: string
    Health:
      type: object
      required:
      - ok
      - latest_publication
      - verified_through
      - expected_publication
      - data_age_days
      - verified_age_days
      - data_quality_status
      - entities
      - events
      - publications
      - identity_quarantined_publications
      - problems
      - counts_estimated
      - history_available_from
      - history_complete
      - stream_high_water
      - ingest_backlog_from
      - ingest_backlog_scope
      - ingest_backlog_status
      - compliance_screening
      properties:
        ok:
          type: boolean
        latest_publication:
          type:
          - string
          - 'null'
          format: date
          description: Datum der juengsten bereits im Bestand verfuegbaren SHAB-Publikation; kein Vollstaendigkeitsbeleg.
        verified_through:
          type:
          - string
          - 'null'
          format: date
          description: Letzter Publikationstag des lueckenlos technisch freigegebenen Datenstroms.
        expected_publication:
          type: string
          format: date
          description: Publikationstag, bis zu dem der regulaere Ingest aktuell sein muss.
        data_age_days:
          type:
          - integer
          - 'null'
          minimum: 0
        verified_age_days:
          type:
          - integer
          - 'null'
          minimum: 0
          description: Alter der technischen Freigabegrenze in ganzen UTC-Tagen.
        data_quality_status:
          type: string
          enum:
          - current
          - processing
          - degraded
          - unavailable
          description: Zusammenfassender Zustand aus Verfuegbarkeit, Freigabegrenze, offenen Ingest-Scheiben und aktiver Identitaetsquarantaene. Ein positiver identity_quarantined_publications-Wert bedeutet immer degraded.
        entities:
          type: integer
          minimum: 0
          description: Bei der letzten PostgreSQL-Analyse geschaetzter Bestand.
        events:
          type: integer
          minimum: 0
          description: Bei der letzten PostgreSQL-Analyse geschaetzter Bestand.
        publications:
          type: integer
          minimum: 0
          description: Bei der letzten PostgreSQL-Analyse geschaetzter Bestand.
        identity_quarantined_publications:
          type: integer
          minimum: 0
          description: Exakte Anzahl aktiver Publikationen mit dauerhaft ungeklärter UID-Zuordnung. Die Quellen sind gespeichert, aber nicht fuer eine Firmenprojektion freigegeben; unabhaengig vom Ergebnis des letzten Ingest-Laufs.
        problems:
          type: array
          items:
            type: string
          description: Lesbare Hinweise zu aktiver UID-Quarantaene. Eine leere Liste allein belegt keinen gesunden Datenstand; massgebend sind ok und data_quality_status.
        counts_estimated:
          type: boolean
          const: true
          description: Nur entities, events und publications sind geschaetzte Bestandszahlen. identity_quarantined_publications, Datenalter und Stromgrenze sind exakt.
        history_available_from:
          type: string
          format: date
          const: '2025-01-03'
          description: Fruehester angebotener Tag der erfassten Publikationshistorie.
        history_complete:
          type: boolean
          const: false
          description: Es wird keine vollstaendige amtliche Gesamthistorie zugesichert.
        stream_high_water:
          type: integer
          minimum: 0
          description: Exakte, zuletzt freigegebene Sequenz des oeffentlichen Ereignisstroms.
        ingest_backlog_from:
          type:
          - string
          - 'null'
          format: date
          description: Publikationstag der wichtigsten unvollstaendigen Ingest-Scheibe; sonst null.
        ingest_backlog_scope:
          type:
          - string
          - 'null'
          description: Kanonischer Rubrik-/Subrubrik-Scope der unvollstaendigen Scheibe; sonst null.
        ingest_backlog_status:
          type:
          - string
          - 'null'
          enum:
          - running
          - error
          - null
          description: Status der wichtigsten unvollstaendigen Ingest-Scheibe; sonst null.
        compliance_screening:
          $ref: '#/components/schemas/ComplianceHealth'
          description: Unabhaengiger Betriebs-, Frische- und Abdeckungsstatus der MWST-, FINMA- und SECO-Pruefquellen.
  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