{
    "openapi": "3.1.0",
    "info": {
        "title": "Fynvo",
        "version": "1.0.0",
        "description": "Deutsches Firmenverzeichnis für KI-Assistenten und Agenten.\n\nDer Zugang ist frei und hat ein Tageslimit je IP-Adresse. Ein Schlüssel im Kopf `X-Fynvo-Key` hebt das Limit.\n\nJede Angabe zeigt ihre Herkunft: `quellen` nennt je Feld die Quelle, die Quelle-URL und den Stand. Die Stufen, absteigend nach Gewicht: `unternehmen` (selbst gepflegt), `redaktion` (von uns geprüft), `register` (amtliches Register), `website` (aus der Website erhoben), `karte` (offene Karten und Ortsverzeichnisse), `import` (übernommener Bestand).\n\nBasisprofile entstehen aus den Websites der Unternehmen. Profile mit zu wenigen geprüften Angaben werden nicht ausgeliefert.\n\nEs werden keine personenbezogenen Angaben geführt, nur Firmendaten.",
        "contact": {
            "name": "Fynvo",
            "url": "https://fynvo.de"
        }
    },
    "servers": [
        {
            "url": "https://api.fynvo.de",
            "description": "Fynvo"
        }
    ],
    "components": {
        "securitySchemes": {
            "FynvoKey": {
                "type": "apiKey",
                "in": "header",
                "name": "X-Fynvo-Key",
                "description": "Freiwillig. Ohne Schlüssel gilt ein kleineres Tageslimit."
            }
        },
        "schemas": {
            "FirmaKurz": {
                "type": "object",
                "properties": {
                    "slug": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "domain": {
                        "type": "string"
                    },
                    "ort": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "plz": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "bundesland": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "branche": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "kurzbeschreibung": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "leistungen": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "rechtsform": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "gruendungsjahr": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "groessenklasse": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "Klasse nach Beschäftigten: Kleinstunternehmen, Kleines Unternehmen, Mittleres Unternehmen, Großunternehmen. NULL, solange keine Zahl vorliegt."
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "basis",
                            "beansprucht",
                            "verifiziert",
                            "premium"
                        ]
                    },
                    "qualitaet": {
                        "type": "integer",
                        "description": "Qualitätsscore 0 bis 100."
                    },
                    "stand": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date"
                    },
                    "profil_url": {
                        "type": "string",
                        "format": "uri"
                    },
                    "verknuepfungen": {
                        "type": "object",
                        "description": "Dieselbe Firma an anderer Stelle im Netz, von ihrer eigenen Website verlinkt. Schlüssel ist die Plattform (linkedin, xing, facebook, instagram, youtube, x, tiktok, kununu, provenexpert, trustedshops, github, wikipedia, googlemaps), Wert die Adresse. Entspricht sameAs in schema.org. Fynvo liest dort keine Inhalte und keine Bewertungen.",
                        "additionalProperties": {
                            "type": "string",
                            "format": "uri"
                        }
                    },
                    "quellen": {
                        "type": "object",
                        "description": "Je Feld die Herkunft: quelle, quelle_url und stand.",
                        "additionalProperties": {
                            "type": "object",
                            "properties": {
                                "quelle": {
                                    "type": "string",
                                    "enum": [
                                        "unternehmen",
                                        "redaktion",
                                        "register",
                                        "website",
                                        "karte",
                                        "import"
                                    ]
                                },
                                "quelle_url": {
                                    "type": [
                                        "string",
                                        "null"
                                    ]
                                },
                                "stand": {
                                    "type": "string",
                                    "format": "date"
                                }
                            }
                        }
                    }
                }
            },
            "Fehler": {
                "type": "object",
                "properties": {
                    "fehler": {
                        "type": "string",
                        "description": "Feste Kennung, etwa nicht_gefunden."
                    },
                    "meldung": {
                        "type": "string"
                    }
                },
                "required": [
                    "fehler",
                    "meldung"
                ]
            }
        },
        "responses": {
            "Limit": {
                "description": "Tageslimit erreicht.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Fehler"
                        }
                    }
                }
            },
            "NichtGefunden": {
                "description": "Nicht vorhanden oder nicht ausgeliefert.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Fehler"
                        }
                    }
                }
            }
        }
    },
    "security": [
        [],
        {
            "FynvoKey": []
        }
    ],
    "paths": {
        "/v1/firmen": {
            "get": {
                "operationId": "firmenSuchen",
                "summary": "Firmen suchen",
                "description": "Sucht Unternehmen nach Leistung, Zertifikat, Region oder Freitext. Ein Oberbegriff bei `leistung` trifft auch alle Leistungen darunter. Die zulässigen Werte für `leistung` und `zertifikat` stehen unter /v1/leistungen und /v1/zertifikate.",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Freitext über Firmenname und Kurzbeschreibung."
                    },
                    {
                        "name": "leistung",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Slug einer Leistung oder eines Oberbegriffs, etwa cnc-fraesen oder metallbearbeitung."
                    },
                    {
                        "name": "zertifikat",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Slug eines Zertifikats, etwa iso-9001."
                    },
                    {
                        "name": "plz",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Fünf Ziffern für eine genaue Postleitzahl, zwei bis vier für eine Region."
                    },
                    {
                        "name": "umkreis_km",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 999
                        },
                        "description": "Umkreis um plz in Kilometern. Solange keine Koordinaten gepflegt sind, wird stattdessen nach dem Anfang der Postleitzahl gesucht; die Antwort sagt das im Feld hinweis."
                    },
                    {
                        "name": "bundesland",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Eines der sechzehn Bundesländer, amtliche Schreibweise."
                    },
                    {
                        "name": "rechtsform",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "GmbH & Co. KGaA",
                                "GmbH & Co. KG",
                                "AG & Co. KGaA",
                                "AG & Co. KG",
                                "UG (haftungsbeschränkt) & Co. KG",
                                "GmbH & Co. OHG",
                                "SE & Co. KGaA",
                                "gGmbH",
                                "UG (haftungsbeschränkt)",
                                "GmbH",
                                "KGaA",
                                "mbH",
                                "OHG",
                                "GbR",
                                "eG",
                                "e.V.",
                                "e.K.",
                                "AG",
                                "KG",
                                "UG",
                                "SE"
                            ]
                        },
                        "description": "Rechtsform des Unternehmens, etwa GmbH oder GmbH & Co. KG."
                    },
                    {
                        "name": "groesse",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "kleinst",
                                "klein",
                                "mittel",
                                "gross"
                            ]
                        },
                        "description": "Betriebsgröße nach Beschäftigten: kleinst 1 bis 9, klein 10 bis 49, mittel 50 bis 249, gross ab 250. Firmen ohne Angabe bleiben draußen."
                    },
                    {
                        "name": "besteht_jahre_min",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 999
                        },
                        "description": "Nur Firmen, die seit mindestens so vielen Jahren bestehen. Firmen ohne Gründungsjahr bleiben draußen."
                    },
                    {
                        "name": "seite",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "default": 1
                        }
                    },
                    {
                        "name": "pro_seite",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 50,
                            "default": 20
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Trefferliste.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "treffer": {
                                            "type": "integer"
                                        },
                                        "seite": {
                                            "type": "integer"
                                        },
                                        "seiten": {
                                            "type": "integer"
                                        },
                                        "pro_seite": {
                                            "type": "integer"
                                        },
                                        "hinweis": {
                                            "type": "string"
                                        },
                                        "firmen": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/FirmaKurz"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/NichtGefunden"
                    },
                    "429": {
                        "$ref": "#/components/responses/Limit"
                    }
                }
            }
        },
        "/v1/firmen/{slug}": {
            "get": {
                "operationId": "firmaAbrufen",
                "summary": "Profil einer Firma",
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Vollständiges Profil mit Leistungen, Zertifikaten und Herkunft je Feld.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NichtGefunden"
                    },
                    "429": {
                        "$ref": "#/components/responses/Limit"
                    }
                }
            }
        },
        "/v1/firmen/{slug}/anfragen": {
            "post": {
                "operationId": "anfrageSenden",
                "summary": "Anfrage an eine Firma",
                "description": "Schickt eine Anfrage an das Unternehmen. Für dieses Verfahren gilt ein eigenes, kleineres Tageslimit.",
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "description": "Antwortadresse des Absenders."
                                    },
                                    "nachricht": {
                                        "type": "string",
                                        "description": "Mindestens 20, höchstens 5000 Zeichen."
                                    },
                                    "name": {
                                        "type": "string",
                                        "description": "Freiwillig."
                                    },
                                    "firma": {
                                        "type": "string",
                                        "description": "Freiwillig."
                                    }
                                },
                                "required": [
                                    "email",
                                    "nachricht"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Angelegt.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "angelegt": {
                                            "type": "boolean"
                                        },
                                        "anfrage": {
                                            "type": "integer"
                                        },
                                        "meldung": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NichtGefunden"
                    },
                    "422": {
                        "$ref": "#/components/responses/NichtGefunden"
                    },
                    "429": {
                        "$ref": "#/components/responses/Limit"
                    }
                }
            }
        },
        "/v1/leistungen": {
            "get": {
                "operationId": "leistungenAuflisten",
                "summary": "Leistungsvokabular",
                "description": "Zweistufig: Oberbegriffe mit den Leistungen darunter, je mit der Zahl der Firmen.",
                "responses": {
                    "200": {
                        "description": "Liste.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/zertifikate": {
            "get": {
                "operationId": "zertifikateAuflisten",
                "summary": "Zertifikatsvokabular",
                "responses": {
                    "200": {
                        "description": "Liste.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}