> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fynn.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Organisationsstruktur

> Bilde Unternehmenshierarchien mit Parent-Child-Beziehungen zwischen Kunden ab.

Viele Organisationen bestehen aus einer übergeordneten Einheit mit mehreren Abteilungen, Standorten oder Tochtergesellschaften. Die Organisationsstruktur ermöglicht es, diese Beziehungen direkt in Fynn abzubilden — mit einer klaren Parent-Child-Hierarchie zwischen Kunden.

<Info>
  Die Organisationsstruktur erfordert die Aktivierung des Feature-Flags `customer.hierarchy`. Kontaktiere den Support, um diese Funktion für deinen Mandanten freizuschalten.
</Info>

## Überblick

Mit der Organisationsstruktur kannst du:

* **Parent-Child-Beziehungen** zwischen Kunden definieren (z. B. Hauptunternehmen → Abteilungen)
* **Bis zu 3 Hierarchieebenen** abbilden (Hauptunternehmen → Tochtergesellschaft → Abteilung)
* **Abonnements, Rechnungen und Transaktionen** gefiltert nach Organisationszugehörigkeit einsehen
* **Aktivitäten** zur Nachverfolgung von Hierarchieänderungen nutzen

<Note>
  Die Organisationsstruktur ist eine rein organisatorische Funktion. Sie hat in der aktuellen Version keinen Einfluss auf die Rechnungsstellung oder Zahlungsabwicklung. Sie bildet die Grundlage für zukünftige Funktionen wie die organisationsbasierte Abrechnung (Consolidated Billing).
</Note>

## Anwendungsbeispiele

| Branche          | Parent-Kunde              | Child-Kunden                            |
| ---------------- | ------------------------- | --------------------------------------- |
| Gesundheitswesen | Klinik Musterstadt        | Radiologie, Orthopädie, Kardiologie     |
| Recht            | Kanzlei Schmidt & Partner | Standort Berlin, Standort München       |
| Einzelhandel     | Retail Group GmbH         | Filiale Nord, Filiale Süd, Filiale West |

## Hierarchie verwalten

### Parent-Kunde zuweisen

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Kundendetails öffnen">
        Navigiere zum Kunden, der als Child-Kunde einem übergeordneten Kunden zugewiesen werden soll.
      </Step>

      <Step title="Parent-Kunde zuweisen">
        Im Bereich Organisationsstruktur kannst du den übergeordneten Kunden (Parent) auswählen und zuweisen.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende den [Set parent customer](/api-reference/customer/set-parent-customer) Endpunkt.

    ```bash theme={null}
    PUT /customers/{customerId}/set-parent
    ```

    ```json theme={null}
    {
        "parentCustomerId": "00000000-0000-0000-0000-000000000000"
    }
    ```
  </Tab>
</Tabs>

### Parent-Kunde entfernen

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Kundendetails öffnen">
        Navigiere zum Child-Kunden, dessen Parent-Zuweisung entfernt werden soll.
      </Step>

      <Step title="Parent-Zuweisung entfernen">
        Im Bereich Organisationsstruktur kannst du die bestehende Parent-Zuweisung entfernen. Der Kunde wird dadurch wieder zu einem eigenständigen Kunden ohne Hierarchie.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende den [Remove parent customer](/api-reference/customer/remove-parent-customer) Endpunkt.

    ```bash theme={null}
    PUT /customers/{customerId}/remove-parent
    ```
  </Tab>
</Tabs>

### Child-Kunden einsehen

<Tabs>
  <Tab title="Web-App verwenden">
    Auf der Kundendetailseite eines Parent-Kunden wird die Anzahl der Child-Kunden angezeigt. Über den Bereich Organisationsstruktur kannst du direkt zu den Child-Kunden navigieren.
  </Tab>

  <Tab title="API verwenden">
    Verwende den [Get customer children](/api-reference/customer/get-customer-children) Endpunkt, um alle direkten Child-Kunden inklusive Metriken abzurufen.

    ```bash theme={null}
    GET /customers/{customerId}/children
    ```

    Die Antwort enthält für jeden Child-Kunden die Kundendaten sowie die Anzahl aktiver Abonnements (`activeSubscriptionCount`).
  </Tab>
</Tabs>

### Gesamte Hierarchie anzeigen

Über die API kannst du die vollständige Hierarchie eines Kunden als Baumstruktur abrufen — unabhängig davon, ob du den Parent- oder einen Child-Kunden angibst. Die Antwort beginnt immer beim Root-Kunden.

```bash theme={null}
GET /customers/{customerId}/hierarchy
```

```json theme={null}
{
    "root": {
        "id": "uuid-100",
        "name": "Klinik Musterstadt",
        "customerNumber": "CUST-100",
        "isCurrentCustomer": false,
        "children": [
            {
                "id": "uuid-101",
                "name": "Radiologie",
                "customerNumber": "CUST-101",
                "isCurrentCustomer": true,
                "children": []
            },
            {
                "id": "uuid-102",
                "name": "Orthopädie",
                "customerNumber": "CUST-102",
                "isCurrentCustomer": false,
                "children": []
            }
        ]
    }
}
```

## Kundenliste filtern

Die Kundenliste unterstützt zusätzliche Filter für die Organisationsstruktur:

| Filter             | Beschreibung                                                       |
| ------------------ | ------------------------------------------------------------------ |
| `parentCustomerId` | Zeigt nur die direkten Child-Kunden eines bestimmten Parent-Kunden |
| `isParent=true`    | Zeigt nur Kunden, die Child-Kunden haben                           |
| `hasParent=true`   | Zeigt nur Kunden, die einem Parent-Kunden zugewiesen sind          |

Beispiel über die API:

```bash theme={null}
GET /customers?parentCustomerId={parentId}
GET /customers?isParent=true
GET /customers?hasParent=true
```

## Organisationsübergreifende Ansichten

Wenn ein Parent-Kunde ausgewählt ist, können Abonnements, Rechnungen und Transaktionen aller zugehörigen Child-Kunden über den `parentCustomer`-Filter zusammen eingesehen werden.

```bash theme={null}
GET /subscriptions?parentCustomer={parentCustomerId}
GET /invoices?parentCustomer={parentCustomerId}
GET /transactions?parentCustomer={parentCustomerId}
```

## Validierungsregeln

Bei der Verwaltung der Organisationsstruktur gelten folgende Regeln:

| Regel              | Beschreibung                                                                         |
| ------------------ | ------------------------------------------------------------------------------------ |
| Maximale Tiefe     | Die Hierarchie unterstützt maximal 3 Ebenen (Root → Child → Grandchild)              |
| Keine Zirkelbezüge | Ein Kunde kann nicht sein eigener Parent sein, weder direkt noch indirekt            |
| Gleicher Mandant   | Parent- und Child-Kunde müssen zum selben Mandanten gehören                          |
| Aktiver Parent     | Der Parent-Kunde darf nicht archiviert sein                                          |
| Archivierung       | Ein Kunde mit aktiven (nicht archivierten) Child-Kunden kann nicht archiviert werden |

## Webhooks

Änderungen an der Organisationsstruktur lösen Webhook-Events aus:

| Event                      | Beschreibung                      |
| -------------------------- | --------------------------------- |
| `customer.parent.assigned` | Ein Parent-Kunde wurde zugewiesen |
| `customer.parent.removed`  | Ein Parent-Kunde wurde entfernt   |

Weitere Informationen zur Konfiguration von Webhooks findest du unter [Webhooks](/guide/webhooks/introduction).

## Ausblick

Die Organisationsstruktur ist die Grundlage für zukünftige Abrechnungsfunktionen auf Organisationsebene. Geplant sind unter anderem:

* **Organisationsbasierte Abrechnung (Consolidated Billing):** Rechnungen für Child-Kunden können an den Parent-Kunden gerichtet werden.
* **Flexible Zahlungssteuerung:** Pro Child-Kunde kann festgelegt werden, wer Rechnungsempfänger und Zahlungspflichtiger ist.
* **Konsolidierungszeiträume:** Rechnungen können monatlich oder quartalsweise zusammengefasst werden.