{
    "openapi": "3.1.0",
    "info": {
        "title": "wemgehörtwas.at JSON-API",
        "version": "1.0.0-beta",
        "summary": "Firmensuche, Firmenprofil, Eigentümer-Graph und Guthaben für angemeldete Nutzer.",
        "description": "JSON-API über das österreichische Firmenbuch.\n\n**Wichtig:** Die API liefert derzeit Beispiel-/Demodaten (jede Antwort enthält `meta.data_status: \"sample\"`). Konkrete Firmen-/Eigentümerdaten dürfen nicht als Tatsachen zitiert werden.\n\n**Authentifizierung:** Alle Endpunkte handeln im Namen eines angemeldeten Nutzers über das Session-Cookie `wwsid`. Ein Bearer-Token-Zugang für Headless-Agenten ist in Vorbereitung (x-planned).\n\n**Datenquelle:** Firmenbuch der Republik Österreich (BMJ), bereitgestellt unter CC BY 4.0. Kein amtlicher Auszug.",
        "contact": {
            "name": "wemgehörtwas.at",
            "email": "jr@je-immobilien.at"
        },
        "license": {
            "name": "CC BY 4.0",
            "url": "https://creativecommons.org/licenses/by/4.0/"
        }
    },
    "servers": [
        {
            "url": "https://wemgehoertwas.at/api/v1",
            "description": "Produktion (Beispieldaten/Beta)"
        }
    ],
    "externalDocs": {
        "description": "API-Dokumentation",
        "url": "https://wemgehoertwas.at/api/docs"
    },
    "security": [
        {
            "cookieSession": []
        }
    ],
    "x-planned-auth": {
        "bearerToken": "Token-Zugang für Headless-Agenten in Vorbereitung."
    },
    "tags": [
        {
            "name": "Suche",
            "description": "Firmen- und Personensuche im Firmenbuch."
        },
        {
            "name": "Firma",
            "description": "Firmenprofile (Stammdaten, Funktionäre, Gesellschafter)."
        },
        {
            "name": "Eigentümer",
            "description": "Eigentümer-/Beteiligungsgraph (kostenpflichtig)."
        },
        {
            "name": "Guthaben",
            "description": "Prepaid-Guthabenstand und Transaktionen."
        }
    ],
    "paths": {
        "/search": {
            "get": {
                "tags": [
                    "Suche"
                ],
                "operationId": "searchEntities",
                "summary": "Firmen-/Personensuche (kostenlos)",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Suchbegriff (Name oder Firmenbuchnummer).",
                        "example": "Alpenstern"
                    },
                    {
                        "name": "kind",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "all",
                                "person",
                                "company",
                                "grundstueck"
                            ],
                            "default": "all"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Trefferliste",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SearchResult"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/BadRequest"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/company": {
            "get": {
                "tags": [
                    "Firma"
                ],
                "operationId": "getCompany",
                "summary": "Firmenprofil (kostenlos)",
                "parameters": [
                    {
                        "name": "fn",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Firmenbuchnummer.",
                        "example": "100001a"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Firmenprofil",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/CompanyResult"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/BadRequest"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/owner": {
            "get": {
                "tags": [
                    "Eigentümer"
                ],
                "operationId": "getOwnerGraph",
                "summary": "Eigentümer-Graph abrufen (4,90 €, nur wenn freigeschaltet)",
                "description": "Liefert den Graphen, wenn die Abfrage bereits freigeschaltet ist; sonst 402. GET bucht nie ab.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Personen-ID."
                    },
                    {
                        "name": "fn",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Firmenbuchnummer."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Eigentümer-Graph",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/OwnerResult"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/BadRequest"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "402": {
                        "$ref": "#/components/responses/PaymentRequired"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "post": {
                "tags": [
                    "Eigentümer"
                ],
                "operationId": "unlockOwnerGraph",
                "summary": "Eigentümer-Graph freischalten (4,90 € abbuchen)",
                "description": "Bucht 4,90 € idempotent aus dem Guthaben ab und liefert den Graphen. CSRF-Token via GET /wallet.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "fn",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "action",
                                    "csrf"
                                ],
                                "properties": {
                                    "action": {
                                        "type": "string",
                                        "enum": [
                                            "unlock"
                                        ]
                                    },
                                    "csrf": {
                                        "type": "string",
                                        "description": "Token aus GET /wallet."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Freigeschaltet, Graph",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/OwnerResult"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/BadRequest"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "402": {
                        "$ref": "#/components/responses/PaymentRequired"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/wallet": {
            "get": {
                "tags": [
                    "Guthaben"
                ],
                "operationId": "getWallet",
                "summary": "Guthabenstand, Transaktionen und CSRF-Token",
                "responses": {
                    "200": {
                        "description": "Guthaben",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/WalletResult"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "cookieSession": {
                "type": "apiKey",
                "in": "cookie",
                "name": "wwsid",
                "description": "Serverseitige PHP-Session nach Google-Login."
            }
        },
        "responses": {
            "BadRequest": {
                "description": "Parameter fehlt/ungültig",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "Unauthorized": {
                "description": "Anmeldung erforderlich",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "PaymentRequired": {
                "description": "Guthaben/Freischaltung nötig",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "Forbidden": {
                "description": "CSRF-Token ungültig",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "NotFound": {
                "description": "Nicht gefunden",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "RateLimited": {
                "description": "Zu viele Anfragen",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            }
        },
        "schemas": {
            "Meta": {
                "type": "object",
                "properties": {
                    "api_version": {
                        "type": "string",
                        "example": "1.0.0-beta"
                    },
                    "source": {
                        "type": "string",
                        "example": "Firmenbuch der Republik Österreich (BMJ)"
                    },
                    "license": {
                        "type": "string",
                        "example": "CC BY 4.0"
                    },
                    "data_status": {
                        "type": "string",
                        "enum": [
                            "sample",
                            "live"
                        ],
                        "example": "sample",
                        "description": "sample = Beispiel-/Demodaten (nicht als Tatsache zitieren)."
                    },
                    "disclaimer": {
                        "type": "string"
                    }
                }
            },
            "Error": {
                "type": "object",
                "properties": {
                    "meta": {
                        "$ref": "#/components/schemas/Meta"
                    },
                    "error": {
                        "type": "object",
                        "properties": {
                            "code": {
                                "type": "integer"
                            },
                            "message": {
                                "type": "string"
                            }
                        }
                    }
                }
            },
            "CompanySummary": {
                "type": "object",
                "properties": {
                    "fn": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "legal_form": {
                        "type": "string"
                    },
                    "seat": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string"
                    },
                    "links": {
                        "type": "object",
                        "properties": {
                            "profile": {
                                "type": "string"
                            },
                            "owner_graph": {
                                "type": "string"
                            }
                        }
                    }
                }
            },
            "Person": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "name": {
                        "type": "string"
                    },
                    "birth_year": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "description": "Bewusst nur Jahr (Datenminimierung)."
                    },
                    "city": {
                        "type": "string"
                    }
                }
            },
            "SearchResult": {
                "type": "object",
                "properties": {
                    "meta": {
                        "$ref": "#/components/schemas/Meta"
                    },
                    "query": {
                        "type": "object"
                    },
                    "count": {
                        "type": "object"
                    },
                    "results": {
                        "type": "object",
                        "properties": {
                            "companies": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/CompanySummary"
                                }
                            },
                            "persons": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/Person"
                                }
                            }
                        }
                    }
                }
            },
            "CompanyResult": {
                "type": "object",
                "properties": {
                    "meta": {
                        "$ref": "#/components/schemas/Meta"
                    },
                    "company": {
                        "type": "object",
                        "properties": {
                            "fn": {
                                "type": "string"
                            },
                            "name": {
                                "type": "string"
                            },
                            "legal_form": {
                                "type": "string"
                            },
                            "seat": {
                                "type": "string"
                            },
                            "address": {
                                "type": "string"
                            },
                            "status": {
                                "type": "string"
                            },
                            "reg_date": {
                                "type": "string"
                            },
                            "nace": {
                                "type": "string"
                            },
                            "capital_eur": {
                                "type": [
                                    "integer",
                                    "null"
                                ]
                            },
                            "shareholders": {
                                "type": "array",
                                "items": {
                                    "type": "object"
                                }
                            },
                            "subsidiaries": {
                                "type": "array",
                                "items": {
                                    "type": "object"
                                }
                            },
                            "functions": {
                                "type": "array",
                                "items": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            },
            "GraphNode": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "person",
                            "company"
                        ]
                    },
                    "label": {
                        "type": "string"
                    }
                }
            },
            "GraphEdge": {
                "type": "object",
                "properties": {
                    "from": {
                        "type": "string"
                    },
                    "to": {
                        "type": "string"
                    },
                    "kind": {
                        "type": "string",
                        "enum": [
                            "ownership",
                            "function"
                        ]
                    },
                    "percent": {
                        "type": "number"
                    }
                }
            },
            "OwnerResult": {
                "type": "object",
                "properties": {
                    "meta": {
                        "$ref": "#/components/schemas/Meta"
                    },
                    "target": {
                        "type": "object"
                    },
                    "unlocked": {
                        "type": "boolean"
                    },
                    "price_cents": {
                        "type": "integer",
                        "example": 490
                    },
                    "graph": {
                        "type": "object",
                        "properties": {
                            "nodes": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/GraphNode"
                                }
                            },
                            "edges": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/GraphEdge"
                                }
                            },
                            "root": {
                                "type": "string"
                            }
                        }
                    }
                }
            },
            "WalletResult": {
                "type": "object",
                "properties": {
                    "meta": {
                        "$ref": "#/components/schemas/Meta"
                    },
                    "wallet": {
                        "type": "object",
                        "properties": {
                            "balance_cents": {
                                "type": "integer"
                            },
                            "currency": {
                                "type": "string"
                            },
                            "price_owner_graph_cents": {
                                "type": "integer",
                                "example": 490
                            }
                        }
                    },
                    "csrf": {
                        "type": "string"
                    },
                    "transactions": {
                        "type": "array",
                        "items": {
                            "type": "object"
                        }
                    }
                }
            }
        }
    }
}